Document API

Representation of an odML document. Depending on the used back-end an odML document can either be attached to a certain data source (e.g. a data base) or it can be detached. Attached documents persist changes immediately to the respective data source while detached documents write data only when save() is called.

class odml2.Document(back_end='yaml', strategy=TerminologyStrategy.Ignore)

Parameters:

• back_end (str | odml2.api.base.BaseDocument) – The name of the back-end to use for this document or a back-end instance.
• strategy (TerminologyStrategy) – How to deal with definitions and terminologies.

author

The name of the documents author. Is None if not specified otherwise.

Type:str

back_end

The back-end used by a document.

NOTICE: This is mostly for internal use.

Type:odml2.api.base.BaseDocument

create_root(type, uuid, label=None, reference=None)

Create an empty root section. If the document already contains sections the whole content of the document will be replaces with the new root.

NOTICE: This method is primarily for internal use (see root as alternative)

Parameters:

• type (str) – The odML type name of the new section.
• uuid (str) – The uuid of the section.
• label (str|None) – The label (a human readable identifier) of the section
• reference (str|None) – A uri or path to other data referenced by this section.

Returns:

Section

date

The creation date of the document.

Type:datetime.date

find_section(uuid, search_namespaces=False)

Find a Section within the document and associated documents.

Parameters:

• uuid (str) – The UUID of the section
• search_namespaces (bool) – If True also search in other namespaces.

Returns:

The found section or None

find_section_and_prefix(uuid, search_namespaces=False)

Find a Section and its namespace within the document and associated documents.

Parameters:

• uuid (str) – The UUID of the section
• search_namespaces (bool) – If True also search in other namespaces.

Returns:

The section with its namespace or None

is_attached

Whether or not the back-end used by the odML document is attached to a data source. This is a read only property.

Type:bool

is_writable

Whether or not the the document is writable. This is a read only property.

Type:bool

iter_sections()

Iterate over all Section objects of the odML document.

Return type:generator

load(source, is_writable=True)

Load data to the document from a certain source.

Parameters:

• source (str | io.FileIO | io.StringIO) – Where to load the content of the document from.
• is_writable (bool) – Whether or not the loaded document should be writable.

location

An uri or path to the location of the document. Is None for newly created documents. This is a read only property.

Type:str

namespaces

A dictionary like access to all name spaces of the document. Name spaces can be used to include other documents under a certain prefix.

Type:NameSpaceMap

property_definitions

Dictionary like access to all property definitions. Property definitions are terms that provide descriptions for properties which may occur in sections of the document.

Type:PropertyDefMap

root

The root section of the document. Is always None for newly created documents. If the document already contains sections the whole content of the document will be replaces with the new root.

Type:Section | SB

save(destination=None)

Save a document to a given destination.

Parameters:destination (str | io.FileIO | io.StringIO) – Where to store the content of the document.

terminology_strategy

The terminology strategy defines how section types and property names are handled with respect to a given terminology.

TerminologyStrategy

type_definitions

Dictionary like access to all type definitions. Type definitions are terms that provide descriptions for section types which may occur in a document.

Type:TypeDefMap

version

The version of the document. Is 1 unless specified otherwise.

Type:int

TerminologyStrategy

The terminology strategy defines how section types and property names are handled with respect to a given terminology.

class odml.TerminologyStrategy

Ignore

Terminology violations such as undefined type or property names are always ignored. This is the default strategy.

Create

Property and type definitions without prefix are created and updated on the fly. This strategy can be used in order to define your custom terminology.

Strict

Each property and type must be defined and used correctly. This strategy can be used to ensure that a document adheres to a terminology.

NameSpaceMap

Provides a dictionary like access to all name spaces of a document.

class odml2.NameSpaceMap(back_end)

keys()

List or generator of all keys

items()

List or generator over all items

values()

List or generator over all name space objects

__delitem__(prefix)

__getitem__(prefix)

__iter__()

__len__()

__setitem__(prefix, ns)

__str__()

set(prefix, uri)

TypeDefMap

Provides a dictionary like access to all type definitions which are part of the terminology of a document.

class odml2.TypeDefMap(back_end)

keys()

List or generator of all keys

items()

List or generator over all items

values()

List or generator over all type definition objects

__delitem__(name)

__getitem__(name)

__iter__()

__len__()

__setitem__(name, td)

__str__()

PropertyDefMap

Provides a dictionary like access to all property definitions which are part of the terminology of a document.

class odml2.PropertyDefMap(back_end)

keys()

List or generator of all keys

items()

List or generator over all items

values()

List or generator over all property definition objects

__delitem__(name)

__getitem__(name)

__iter__()

__len__()

__setitem__(name, pd)

__str__()