odML-Base Classes

These classes are the core data-structures of odML. To sum things up, an odML-Document consists of several Sections. Each Section may contain other Sections and Properties. Again each Property can have multiple Values.

The odml Module contains wrappers, that are shortcuts for creating the main objects:

>>> from odml import Document, Section, Property
>>> Document(version=0.9, author="Kermit")
<Doc 0.9 by Kermit (0 sections)>

Several modules exist to extend the implementation. The ones included in the library are those:

Document

class odml.doc.BaseDocument(author=None, date=None, version=None, repository=None, oid=None)

A representation of an odML document in memory. Its odml attributes are: author, date, version and repository. A Document behaves very much like a section, except that it cannot hold properties.

append(section)

Method appends a single Section to the section child-lists of the current Object.

Parameters

section – odML Section object.

property author

The author of the document.

clean()

Runs clean() on all immediate child-sections causing any resolved links or includes to be unresolved.

This should be called for the document prior to saving.

clone(children=True, keep_id=False)

Clone this object recursively allowing to copy it independently to another document

contains(obj)

Checks if a subsection of name&type of obj is a child of this section if so return this child

create_section(name, type='undefined', oid=None)

Creates a new subsection that is a child of this section.

Parameters

  • name – The name of the section to create.

  • type – The type of the section.

  • oid – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned.

Returns

The new section.

property date

The date the document was created.

property document

Returns the parent-most node (if its a document instance) or None

extend(sec_list)

Method adds Sections to the section child-list of the current object.

Parameters

sec_list – Iterable containing odML Section entries.

finalize()

This needs to be called after the document is set up from parsing it will perform additional operations, that need the complete document. In particular, this method will resolve all link and include attributes accordingly.

find(key=None, type=None, findAll=False, include_subtype=False)

Return the first subsection named key of type type

Finds a related section named key and/or type

  • by searching its children’s children if children is True if recursive is true all leave nodes will be searched

  • by searching its siblings if siblings is True

  • by searching the parent element if parents is True if recursive is True all parent nodes until the root are searched

  • if findAll is True, returns a list of all matching objects

format()
get_path()

Returns the absolute path of this section

get_property_by_path(path)

Find a Property through a path like “../name1/name2:property_name”

Parameters

path (str) – path like “../name1/name2:property_name”

get_relative_path(section)

Returns a relative (file)path to point to section like (e.g. ../other_section)

If the common parent of both sections is the document (i.e. /), return an absolute path

get_repository()

Return the current applicable repository (may be inherited from a parent) or None

get_section_by_path(path)

Find a Section through a path like “../name1/name2”

Parameters

path (str) – path like “../name1/name2”

get_terminology_equivalent()

Returns the equivalent object in an terminology (should there be one defined) or None

property id

The uuid for the document.

insert(position, section)

Insert a Section at the child-list position. A ValueError will be raised, if a Section with the same name already exists in the child-list.

Parameters

  • position – index at which the object should be inserted.

  • section – odML Section object.

iterproperties(max_depth=None, filter_func=<function Sectionable.<lambda>>)

Iterate each related property (recursively)

Example: return all children properties which name contains “foo” >>> filter_func = lambda x: getattr(x, ‘name’).find(“foo”) > -1 >>> sec_or_doc.iterproperties(filter_func=filter_func)

Parameters

  • max_depth (bool) – iterate all properties recursively if None, only to a certain level otherwise

  • filter_func (function) – accepts a function that will be applied to each iterable. Yields iterable if function returns True

itersections(recursive=True, yield_self=False, filter_func=<function Sectionable.<lambda>>, max_depth=None)

Iterate each child section

Example: return all subsections which name contains “foo” >>> filter_func = lambda x: getattr(x, ‘name’).find(“foo”) > -1 >>> sec_or_doc.itersections(filter_func=filter_func)

Parameters

  • recursive (bool) – iterate all child sections recursively (deprecated)

  • yield_self (bool) – includes itself in the iteration

  • filter_func (function) – accepts a function that will be applied to each iterable. Yields iterable if function returns True

itervalues(max_depth=None, filter_func=<function Sectionable.<lambda>>)

Iterate each related value (recursively)

# Example: return all children values which string converted version

has “foo”

>>> filter_func = lambda x: str(x).find("foo") > -1
>>> sec_or_doc.itervalues(filter_func=filter_func)
Parameters

  • max_depth (bool) – iterate all properties recursively if None, only to a certain level otherwise

  • filter_func (function) – accepts a function that will be applied to each iterable. Yields iterable if function returns True

new_id(oid=None)

new_id sets the id of the current object to a RFC 4122 compliant UUID. If an id was provided, it is assigned if it is RFC 4122 UUID format compliant. If no id was provided, a new UUID is generated and assigned. :param oid: UUID string as specified in RFC 4122.

property oid

The uuid for the document. Required for entity creation and comparison, saving and loading.

property parent

The parent of a document is always None.

pprint(indent=2, max_depth=1, max_length=80, current_depth=0)

Pretty print method to visualize Document-Section trees.

Parameters

  • indent – number of leading spaces for every child Section or Property.

  • max_depth – maximum number of hierarchical levels printed from the starting Section.

  • max_length – maximum number of characters printed in one line.

  • current_depth – number of hierarchical levels printed from the starting Section.

remove(section)

Removes the specified child-section

property repository

A URL to a terminology.

property sections

The list of sections contained in this section/document

property version

A personal version-specifier that can be used to track different versions of the same document.

Section

class odml.section.BaseSection(name=None, type=None, parent=None, definition=None, reference=None, repository=None, link=None, include=None, oid=None)

An odML Section

append(obj)

Method adds single Sections and Properties to the respective child-lists of the current Section.

Parameters

obj – Section or Property object.

property can_be_merged

Returns True if either a link or an include attribute is specified

clean()

Runs clean() on all immediate child-sections causing any resolved links or includes to be unresolved.

This should be called for the document prior to saving.

clone(children=True, keep_id=False)

Clone this Section allowing to copy it independently to another document. By default the id of any cloned object will be set to a new uuid.

Parameters

  • children – If True, also clone child sections and properties recursively.

  • keep_id – If this attribute is set to True, the uuids of the Section and all child objects will remain unchanged.

Returns

The cloned Section.

contains(obj)

If the child-lists of the current Section contain a Section with the same name and type or a Property with the same name as the provided object, the found Section or Property is returned.

Parameters

obj – Section or Property object.

create_property(name, value=None, dtype=None, oid=None)

Create a new property that is a child of this section.

Parameters

  • name – The name of the property.

  • value – Some data value, it can be a single value or a list of homogeneous values.

  • dtype – The data type of the values stored in the property, if dtype is not given, the type is deduced from the values. Check odml.DType for supported data types.

  • oid – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned.

Returns

The new property.

create_section(name, type='undefined', oid=None)

Creates a new subsection that is a child of this section.

Parameters

  • name – The name of the section to create.

  • type – The type of the section.

  • oid – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned.

Returns

The new section.

property definition

Name Definition of the section

property document

Returns the parent-most node (if its a document instance) or None

export_leaf()

Export only the path from this section to the root. Include all properties for all sections, but no other subsections.

extend(obj_list)

Method adds Sections and Properties to the respective child-lists of the current Section.

Parameters

obj_list – Iterable containing Section and Property entries.

find(key=None, type=None, findAll=False, include_subtype=False)

Return the first subsection named key of type type

Finds a related section named key and/or type

  • by searching its children’s children if children is True if recursive is true all leave nodes will be searched

  • by searching its siblings if siblings is True

  • by searching the parent element if parents is True if recursive is True all parent nodes until the root are searched

  • if findAll is True, returns a list of all matching objects

format()
get_merged_equivalent()

Return the merged object or None

get_path()

Returns the absolute path of this section

get_property_by_path(path)

Find a Property through a path like “../name1/name2:property_name”

Parameters

path (str) – path like “../name1/name2:property_name”

get_relative_path(section)

Returns a relative (file)path to point to section like (e.g. ../other_section)

If the common parent of both sections is the document (i.e. /), return an absolute path

get_repository()

Returns the repository responsible for this section, which might not be the repository attribute, but may be inherited from a parent section / the document

get_section_by_path(path)

Find a Section through a path like “../name1/name2”

Parameters

path (str) – path like “../name1/name2”

get_terminology_equivalent()

Returns the equivalent object in an terminology (should there be one defined) or None

property id

The uuid for the section.

property include

The same as odml.section.BaseSection.link, except that include specifies an arbitrary url instead of a local path within the same document

insert(position, obj)

Insert a Section or a Property at the respective child-list position. A ValueError will be raised, if a Section or a Property with the same name already exists in the respective child-list.

Parameters

  • position – index at which the object should be inserted.

  • obj – Section or Property object.

property is_merged

Returns True if the section is merged with another one (e.g. through odml.section.BaseSection.link or odml.section.BaseSection.include) The merged object can be accessed through the _merged attribute.

iterproperties(max_depth=None, filter_func=<function Sectionable.<lambda>>)

Iterate each related property (recursively)

Example: return all children properties which name contains “foo” >>> filter_func = lambda x: getattr(x, ‘name’).find(“foo”) > -1 >>> sec_or_doc.iterproperties(filter_func=filter_func)

Parameters

  • max_depth (bool) – iterate all properties recursively if None, only to a certain level otherwise

  • filter_func (function) – accepts a function that will be applied to each iterable. Yields iterable if function returns True

itersections(recursive=True, yield_self=False, filter_func=<function Sectionable.<lambda>>, max_depth=None)

Iterate each child section

Example: return all subsections which name contains “foo” >>> filter_func = lambda x: getattr(x, ‘name’).find(“foo”) > -1 >>> sec_or_doc.itersections(filter_func=filter_func)

Parameters

  • recursive (bool) – iterate all child sections recursively (deprecated)

  • yield_self (bool) – includes itself in the iteration

  • filter_func (function) – accepts a function that will be applied to each iterable. Yields iterable if function returns True

itervalues(max_depth=None, filter_func=<function Sectionable.<lambda>>)

Iterate each related value (recursively)

# Example: return all children values which string converted version

has “foo”

>>> filter_func = lambda x: str(x).find("foo") > -1
>>> sec_or_doc.itervalues(filter_func=filter_func)
Parameters

  • max_depth (bool) – iterate all properties recursively if None, only to a certain level otherwise

  • filter_func (function) – accepts a function that will be applied to each iterable. Yields iterable if function returns True

Specifies a softlink, i.e. a path within the document When the merge()-method is called, the link will be resolved creating according copies of the section referenced by the link attribute. When the unmerge() method is called (happens when running clean()) the link is unresolved, i.e. all properties and sections that are completely equivalent to the merged object will be removed. (They will be restored accordingly when calling merge()). When changing the link attribute, the previously merged section is unmerged, and the new reference will be immediately resolved. To avoid this side-effect, directly change the _link attribute.

merge(section=None, strict=True)

Merges this section with another section. See also: odml.section.BaseSection.link If section is none, sets the link/include attribute (if _link or _include are set), causing the section to be automatically merged to the referenced section.

Parameters

  • section – an odML Section. If section is None, link or include will be resolved instead.

  • strict – Bool value to indicate whether the attributes of affected child Properties except their ids and values have to be identical to be merged. Default is True.

merge_check(source_section, strict=True)

Recursively checks whether a source Section and all its children can be merged with self and all its children as destination and raises a ValueError if any of the Section attributes definition and reference differ in source and destination.

Parameters

  • source_section – an odML Section.

  • strict – If True, definition and reference attributes of any merged Sections as well as most attributes of merged Properties on the same tree level in source and destination have to be identical.

property name
new_id(oid=None)

new_id sets the id of the current object to a RFC 4122 compliant UUID. If an id was provided, it is assigned if it is RFC 4122 UUID format compliant. If no id was provided, a new UUID is generated and assigned. :param oid: UUID string as specified in RFC 4122.

property oid

The uuid for the section. Required for entity creation and comparison, saving and loading.

property parent

The parent section, the parent document or None

pprint(indent=2, max_depth=1, max_length=80, current_depth=0)

Pretty print method to visualize Section-Property trees.

Parameters

  • indent – number of leading spaces for every child Section or Property.

  • max_length – maximum number of characters printed in one line.

  • current_depth – number of hierarchical levels printed from the starting Section.

property properties

The list of all properties contained in this section

property props

The list of all properties contained in this section; NIXpy format style alias for ‘properties’.

property reference
remove(obj)

Remove a Section or a Property from the respective child-lists of the current Section and sets the parent attribute of the handed in object to None. Raises a ValueError if the object is not a Section or a Property or if the object is not contained in the child-lists.

Parameters

obj – Section or Property object.

reorder(new_index)

Move this object in its parent child-list to the position new_index.

Returns

The old index at which the object was found.

property repository

A URL to a terminology.

property sections

The list of all child-sections of this section

type = None
unmerge(section)

Clean up a merged section by removing objects that are totally equal to the linked object

Property

class odml.property.BaseProperty(name=None, values=None, parent=None, unit=None, uncertainty=None, reference=None, definition=None, dependency=None, dependency_value=None, dtype=None, value_origin=None, oid=None, value=None)

An odML Property

append(obj, strict=True)

Append a single value to the list of stored values. Method will raise a ValueError if the passed value cannot be converted to the current dtype.

Parameters

  • obj – the additional value.

  • strict – a Bool that controls whether dtypes must match. Default is True.

clean()

Stub that doesn’t do anything for this class

clone(keep_id=False)

Clone this property to copy it independently to another document. By default the id of the cloned object will be set to a different uuid.

Parameters

keep_id – If this attribute is set to True, the uuid of the object will remain unchanged.

Returns

The cloned property

property definition
property dependency
property dependency_value
property document

Returns the Document object in which this object is contained

property dtype

The data type of the value. Check odml.DType for supported data types.

export_leaf()

Export only the path from this property to the root. Include all properties of parent sections.

extend(obj, strict=True)

Extend the list of values stored in this property by the passed values. Method will raise a ValueError, if values cannot be converted to the current dtype. One can also pass another Property to append all values stored in that one. In this case units must match!

Parameters

  • obj – single value, list of values or a Property.

  • strict – a Bool that controls whether dtypes must match. Default is True.

format()
get_merged_equivalent()

Return the merged object (i.e. if the parent section is linked to another one, return the corresponding property of the linked section) or None.

get_path()

Return the absolute path to this object.

get_terminology_equivalent()

Returns the equivalent object in an terminology (should there be one defined) or None

property id

The uuid for the property.

merge(other, strict=True)

Merges the Property ‘other’ into self, if possible. Information will be synchronized. By default the method will raise a ValueError when the information in this property and the passed property are in conflict.

Parameters

  • other – an odML Property.

  • strict – Bool value to indicate whether types should be implicitly converted even when information may be lost. Default is True, i.e. no conversion, and a ValueError will be raised if types or other attributes do not match. If a conflict arises with strict=False, the attribute value of self will be kept, while the attribute value of other will be lost.

merge_check(source, strict=True)

Checks whether a source Property can be merged with self as destination and raises a ValueError if the values of source and destination are not compatible. With parameter strict=True a ValueError is also raised, if any of the attributes unit, definition, uncertainty, reference or value_origin and dtype differ in source and destination.

Parameters

  • source – an odML Property.

  • strict – If True, the attributes dtype, unit, uncertainty, definition, reference and value_origin of source and destination must be identical.

property name
new_id(oid=None)

new_id sets the object id of the current object to an RFC 4122 compliant UUID. If an id was provided, it is assigned if it is RFC 4122 UUID format compliant. If no id was provided, a new UUID is generated and assigned. :param oid: UUID string as specified in RFC 4122.

property oid

The uuid for the property. Required for entity creation and comparison, saving and loading.

property parent

The section containing this property.

pprint(indent=2, max_length=80, current_depth=- 1)

Pretty print method to visualize Properties and Section-Property trees.

Parameters

  • indent – number of leading spaces for every child Property.

  • max_length – maximum number of characters printed in one line.

  • current_depth – number of hierarchical levels printed from the starting Section.

property reference
remove(value)

Remove a value from this property. Only the first encountered occurrence of the passed in value is removed from the properties list of values.

property uncertainty
property unit
unmerge(other)

Stub that doesn’t do anything for this class.

property value

Deprecated alias of ‘values’. Will be removed with the next minor release.

property value_origin
value_str(index=0)

Used to access typed data of the value at a specific index position as a string.

property values

Returns the value(s) stored in this property. Method always returns a list that is a copy (!) of the stored value. Changing this list will NOT change the property. For manipulation of the stored values use the append, extend, and direct access methods (using brackets).

For example: >>> p = odml.Property(“prop”, values=[1, 2, 3]) >>> print(p.values) [1, 2, 3] >>> p.values.append(4) >>> print(p.values) [1, 2, 3]

Individual values can be accessed and manipulated like this: >>> print(p[0]) [1] >>> p[0] = 4 >>> print(p[0]) [4]

The values can be iterated e.g. with a loop: >>> for v in p.values: >>> print(v) 4 2 3