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.

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)¶: Clones 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=None, type='n.s.', oid=None, definition=None, reference=None, repository=None, link=None, include=None)¶

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

Parameters:

name – The name of the section to create. If the name is not provided, the object id of the Section is assigned as its name. Section name is a required attribute.
type – String providing a grouping description for similar Sections. Section type is a required attribute and will be set to the string ‘n.s.’ by default.
oid – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned.
definition – String defining this Section.
reference – A reference (e.g. an URL) to an external definition of the Section.
repository – URL to a repository in which the Section is defined.
link – Specifies a soft link, i.e. a path within the document.
include – Specifies an arbitrary URL. Can only be used if link is not set.

Returns:

The new section.

date¶: The date the document was created.

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)¶

Returns the first subsection named key of type type.

Parameters:	key – string to search against an odML objects name. type – type of an odML object. findAll – include further matches after the first one in the result. include_subtype – splits an objects type at ‘/’ and matches the parts against the provided type.

find_related(key=None, type=None, children=True, siblings=True, parents=True, recursive=True, findAll=False)¶

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()¶: Returns the format class of the current object.

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

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 max_depth – number of layers in the document tree to include in the search.

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.

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

origin_file_name¶: If available, the file name from where the document has been loaded. Will not be serialized to file when saving the document.

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

repository¶: A URL to a terminology.

sections¶: The list of sections contained in this section/document.

validate()¶

Runs a validation on itself and returns the Validation object.

Returns:	odml.Validation

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='n.s.', parent=None, definition=None, reference=None, repository=None, link=None, include=None, oid=None, sec_cardinality=None, prop_cardinality=None)¶

An odML Section.

Parameters:

name – string providing the name of the Section. If the name is not provided, the object id of the Section is assigned as its name. Section name is a required attribute.
type – String providing a grouping description for similar Sections. Section type is a required attribute and will be set to the string ‘n.s.’ by default.
parent – the parent object of the new Section. If the object is not an odml.Section or an odml.Document, a ValueError is raised.
definition – String defining this Section.
reference – A reference (e.g. an URL) to an external definition of the Section.
repository – URL to a repository in which the Section is defined.
link – Specifies a soft link, i.e. a path within the document.
include – Specifies an arbitrary URL. Can only be used if link is not set.
oid – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned. An id has to be unique within an odML Document.
sec_cardinality – Section cardinality defines how many Sub-Sections are allowed for this Section. By default unlimited Sections can be set. A required number of Sections can be set by assigning a tuple of the format “(min, max)”
prop_cardinality – Property cardinality defines how many Properties are allowed for this Section. By default unlimited Properties can be set. A required number of Properties can be set by assigning a tuple of the format “(min, max)”.

append(obj)¶

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

Parameters:	obj – Section or Property object.

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, values=None, dtype=None, oid=None, value=None)¶

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

Parameters:

name – The name of the property.
values – 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.
value – Deprecated alias of ‘values’. Any content of ‘value’ is ignored, if ‘values’ is set.

Returns:

The new property.

create_section(name=None, type='n.s.', oid=None, definition=None, reference=None, repository=None, link=None, include=None)¶

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

Parameters:

name – The name of the section to create. If the name is not provided, the object id of the Section is assigned as its name. Section name is a required attribute.
type – String providing a grouping description for similar Sections. Section type is a required attribute and will be set to the string ‘n.s.’ by default.
oid – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned.
definition – String defining this Section.
reference – A reference (e.g. an URL) to an external definition of the Section.
repository – URL to a repository in which the Section is defined.
link – Specifies a soft link, i.e. a path within the document.
include – Specifies an arbitrary URL. Can only be used if link is not set.

Returns:

The new section.

definition¶: The definition of the Section.

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

export_leaf()¶

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

Returns:	cloned odml tree to the root of the current document.

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)¶

Returns the first subsection named key of type type.

Parameters:	key – string to search against an odML objects name. type – type of an odML object. findAll – include further matches after the first one in the result. include_subtype – splits an objects type at ‘/’ and matches the parts against the provided type.

find_related(key=None, type=None, children=True, siblings=True, parents=True, recursive=True, findAll=False)¶

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()¶: Returns the format class of the current object.

get_merged_equivalent()¶: Returns 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

id¶: The uuid for the section.

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.

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 max_depth – number of layers in the document tree to include in the search.

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

link¶: 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.

name¶: The name of the Section.

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.

Parameters:	oid – UUID string as specified in RFC 4122.

oid¶: The uuid for the Section. Required for entity creation and comparison, saving and loading.

parent¶: The parent Section, Document or None.

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

Pretty prints Section-Property trees for nicer visualization.

Parameters:	indent – number of leading spaces for every child Section or Property. max_depth – number of maximum child section layers to traverse and print. max_length – maximum number of characters printed in one line. current_depth – number of hierarchical levels printed from the starting Section.

prop_cardinality¶: The Property cardinality of a Section. It defines how many Properties are minimally required and how many Properties should be maximally stored. Use the ‘set_properties_cardinality’ method to set.

properties¶: The list of all properties contained in this Section,

props¶: The list of all properties contained in this Section; NIXpy format style alias for ‘properties’.

reference¶: A reference (e.g. an URL) to an external definition of the Section. :returns: The reference of the Section.

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.

repository¶: A URL to a terminology.

sec_cardinality¶: The Section cardinality of a Section. It defines how many Sections are minimally required and how many Sections should be maximally stored. Use the ‘set_sections_cardinality’ method to set.

sections¶: The list of all child-sections of this Section.

set_properties_cardinality(min_val=None, max_val=None)¶

Sets the Properties cardinality of a Section.

Parameters:	min_val – Required minimal number of values elements. None denotes no restrictions on properties elements minimum. Default is None. max_val – Allowed maximal number of values elements. None denotes no restrictions on properties elements maximum. Default is None.

set_sections_cardinality(min_val=None, max_val=None)¶

Sets the Sections cardinality of a Section.

Parameters:	min_val – Required minimal number of values elements. None denotes no restrictions on sections elements minimum. Default is None. max_val – Allowed maximal number of values elements. None denotes no restrictions on sections elements maximum. Default is None.

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, val_cardinality=None, value=None)¶

An odML Property.

If a value without an explicitly stated dtype has been provided, dtype will be inferred from the value.

Example: >>> p = Property(“property1”, “a string”) >>> p.dtype >>> str >>> p = Property(“property1”, 2) >>> p.dtype >>> int >>> p = Property(“prop”, [2, 3, 4]) >>> p.dtype >>> int

Parameters:

name – The name of the Property.
values – Some data value, it can be a single value or a list of homogeneous values.
parent – the parent object of the new Property. If the object is not an odml.Section a ValueError is raised.
unit – The unit of the stored data.
uncertainty – The uncertainty (e.g. the standard deviation) associated with a measure value.
reference – A reference (e.g. an URL) to an external definition of the value.
definition – The definition of the Property.
dependency – Another Property this Property depends on.
dependency_value – Dependency on a certain value.
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.
value_origin – Reference where the value originated from e.g. a file name.
oid – object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned. An id has to be unique within an odML Document.
val_cardinality – Value cardinality defines how many values are allowed for this Property. By default unlimited values can be set. A required number of values can be set by assigning a tuple of the format “(min, max)”.
value – Legacy code to the ‘values’ attribute. If ‘values’ is provided, any data provided via ‘value’ will be ignored.

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

definition¶

Returns the definition of the Property:

dependency¶: Another Property this Property depends on. :returns: the dependency of the Property.

dependency_value¶: Dependency on a certain value in a dependency Property. :returns: the required value to be found in a dependency Property.

document¶: Returns the Document object in which this object is contained.

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

export_leaf()¶

Export the path including all direct parents from this Property to the root of the document. Section properties are included, Subsections are not included.

Returns:	Cloned odml tree to the root of the current document.

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()¶: Returns the format class of the current object.

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

id¶: The uuid of the Property.

insert(index, obj, strict=True)¶

Insert 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. index – position of the new value strict – a Bool that controls whether dtypes must match. Default is True.

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.

name¶: The name of the Property.

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.

Parameters:	oid – UUID string as specified in RFC 4122.

oid¶: The uuid of the Property. Required for entity creation and comparison, saving and loading.

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.

reference¶: A reference (e.g. an URL) to an external definition of the value. :returns: the reference of the Property.

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.

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.

set_values_cardinality(min_val=None, max_val=None)¶

Sets the values cardinality of a Property.

Parameters:	min_val – Required minimal number of values elements. None denotes no restrictions on values elements minimum. Default is None. max_val – Allowed maximal number of values elements. None denotes no restrictions on values elements maximum. Default is None.

uncertainty¶: The uncertainty (e.g. the standard deviation) associated with the values of the Property. :returns: the uncertainty of the Property.

unit¶: The unit associated with the values of the Property. :returns: the unit of the Property.

unmerge(other)¶: Stub that doesn’t do anything for this class.

val_cardinality¶: The value cardinality of a Property. It defines how many values are minimally required and how many values should be maximally stored. Use the ‘set_values_cardinality’ method to set.

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

value_origin¶: Reference where the value originated from e.g. a file name. :returns: the value_origin of the Property.

value_str(index=0)¶: Used to access typed data of the value at a specific index position as a string.

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