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

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

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

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

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

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

Table of Contents

Previous topic

Next topic

This Page

odML-Base Classes¶

Document¶

Section¶

Property¶