# -*- coding: utf-8 import collections import uuid from . import base from . import format from . import terminology from .doc import BaseDocument # this is supposedly ok, as we only use it for an isinstance check from .property import BaseProperty # it MUST however not be used to create any Property objects from .tools.doc_inherit import inherit_docstring, allow_inherit_docstring @allow_inherit_docstring class BaseSection(base.Sectionable): """ An odML Section """ type = None reference = None # the *import* property _link = None _include = None _merged = None _format = format.Section def __init__(self, name=None, type=None, parent=None, definition=None, reference=None, repository=None, link=None, include=None, oid=None): # Sets _sections Smartlist and _repository to None, so run first. super(BaseSection, self).__init__() self._props = base.SmartList(BaseProperty) try: if oid is not None: self._id = str(uuid.UUID(oid)) else: self._id = str(uuid.uuid4()) except ValueError as e: print(e) self._id = str(uuid.uuid4()) # Use id if no name was provided. if not name: name = self._id self._parent = None self._name = name self._definition = definition self._reference = reference self._repository = repository self._link = link self._include = include # this may fire a change event, so have the section setup then self.type = type self.parent = parent def __repr__(self): return "Section[%d|%d] {name = %s, type = %s, id = %s}" % (len(self._sections), len(self._props), self._name, self.type, self.id) def __iter__(self): """ Iterate over each section and property contained in this section """ for section in self._sections: yield section for prop in self._props: yield prop def __len__(self): """ Number of children (sections AND properties) """ return len(self._sections) + len(self._props) @property def oid(self): """ The uuid for the section. Required for entity creation and comparison, saving and loading. """ return self.id @property def id(self): """ The uuid for the section. """ return self._id def new_id(self, 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. """ if oid is not None: self._id = str(uuid.UUID(oid)) else: self._id = str(uuid.uuid4()) @property def name(self): return self._name @name.setter def name(self, new_value): if self.name == new_value: return curr_parent = self.parent if hasattr(curr_parent, "sections") and new_value in curr_parent.sections: raise KeyError("Object with the same name already exists!") self._name = new_value @property def include(self): """ The same as :py:attr:`odml.section.BaseSection.link`, except that include specifies an arbitrary url instead of a local path within the same document """ return self._include @include.setter def include(self, new_value): if self._link is not None: raise TypeError("%s.include: You can either set link or include, " "but not both." % repr(self)) if not new_value: self._include = None self.clean() return if '#' in new_value: url, path = new_value.split('#', 1) else: url, path = new_value, None terminology.deferred_load(url) if self.parent is None: self._include = new_value return term = terminology.load(url) new_section = term.get_section_by_path( path) if path is not None else term.sections[0] if self._include is not None: self.clean() self._include = new_value # strict needs to be False, otherwise finalizing a document will # basically always fail. self.merge(new_section, strict=False) @property def link(self): """ 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. """ return self._link @link.setter def link(self, new_value): if self._include is not None: raise TypeError("%s.link: You can either set link or include," " but not both." % repr(self)) if self.parent is None: # we cannot possibly know where the link goes self._link = new_value return if not new_value: self._link = None self.clean() return # raises exception if path cannot be found new_section = self.get_section_by_path(new_value) if self._link is not None: self.clean() self._link = new_value # strict needs to be False, otherwise finalizing a document will # basically always fail. self.merge(new_section, strict=False) @property def definition(self): """ Name Definition of the section """ if hasattr(self, "_definition"): return self._definition else: return None @definition.setter def definition(self, new_value): if new_value == "": new_value = None self._definition = new_value @definition.deleter def definition(self): del self._definition @property def reference(self): return self._reference @reference.setter def reference(self, new_value): if new_value == "": new_value = None self._reference = new_value # API (public) # # properties @property def properties(self): """ The list of all properties contained in this section """ return self._props @property def props(self): """ The list of all properties contained in this section; NIXpy format style alias for 'properties'.""" return self._props @property def sections(self): """ The list of all child-sections of this section """ return self._sections @property def parent(self): """ The parent section, the parent document or None """ return self._parent @parent.setter def parent(self, new_parent): if new_parent is None and self._parent is None: return elif new_parent is None and self._parent is not None: self._parent.remove(self) self._parent = None elif self._validate_parent(new_parent): if self._parent is not None: self._parent.remove(self) self._parent = new_parent self._parent.append(self) else: raise ValueError( "odml.Section.parent: passed value is not of consistent type!" "\nodml.Document or odml.Section expected") def _validate_parent(self, new_parent): if isinstance(new_parent, BaseDocument) or \ isinstance(new_parent, BaseSection): return True return False def get_repository(self): """ Returns the repository responsible for this section, which might not be the *repository* attribute, but may be inherited from a parent section / the document """ if self._repository is None and self.parent is not None: return self.parent.get_repository() return super(BaseSection, self).repository @base.Sectionable.repository.setter def repository(self, url): base.Sectionable.repository.fset(self, url) @inherit_docstring def get_terminology_equivalent(self): repo = self.get_repository() if repo is None: return None term = terminology.load(repo) if term is None: return None return term.find_related(type=self.type) def get_merged_equivalent(self): """ Return the merged object or None """ return self._merged def append(self, obj): """ Method adds single Sections and Properties to the respective child-lists of the current Section. :param obj: Section or Property object. """ if isinstance(obj, BaseSection): self._sections.append(obj) obj._parent = self elif isinstance(obj, BaseProperty): self._props.append(obj) obj._parent = self elif isinstance(obj, collections.Iterable) and not isinstance(obj, str): raise ValueError("odml.Section.append: " "Use extend to add a list of Sections or Properties.") else: raise ValueError("odml.Section.append: " "Can only append Sections or Properties.") def extend(self, obj_list): """ Method adds Sections and Properties to the respective child-lists of the current Section. :param obj_list: Iterable containing Section and Property entries. """ if not isinstance(obj_list, collections.Iterable): raise TypeError("'%s' object is not iterable" % type(obj_list).__name__) # Make sure only Sections and Properties with unique names will be added. for obj in obj_list: if not isinstance(obj, BaseSection) and not isinstance(obj, BaseProperty): raise ValueError("odml.Section.extend: " "Can only extend sections and properties.") elif isinstance(obj, BaseSection) and obj.name in self.sections: raise KeyError("odml.Section.extend: " "Section with name '%s' already exists." % obj.name) elif isinstance(obj, BaseProperty) and obj.name in self.properties: raise KeyError("odml.Section.extend: " "Property with name '%s' already exists." % obj.name) for obj in obj_list: self.append(obj) def insert(self, 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. :param position: index at which the object should be inserted. :param obj: Section or Property object. """ if isinstance(obj, BaseSection): if obj.name in self.sections: raise ValueError("odml.Section.insert: " "Section with name '%s' already exists." % obj.name) self._sections.insert(position, obj) obj._parent = self elif isinstance(obj, BaseProperty): if obj.name in self.properties: raise ValueError("odml.Section.insert: " "Property with name '%s' already exists." % obj.name) self._props.insert(position, obj) obj._parent = self else: raise ValueError("Can only insert sections and properties") def remove(self, 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. :param obj: Section or Property object. """ if isinstance(obj, BaseSection): self._sections.remove(obj) obj._parent = None elif isinstance(obj, BaseProperty): self._props.remove(obj) obj._parent = None else: raise ValueError("Can only remove sections and properties") def clone(self, 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. :param children: If True, also clone child sections and properties recursively. :param keep_id: If this attribute is set to True, the uuids of the Section and all child objects will remain unchanged. :return: The cloned Section. """ obj = super(BaseSection, self).clone(children, keep_id) if not keep_id: obj.new_id() obj._props = base.SmartList(BaseProperty) if children: for p in self._props: obj.append(p.clone(keep_id)) return obj def contains(self, 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. :param obj: Section or Property object. """ if isinstance(obj, BaseSection): return super(BaseSection, self).contains(obj) elif isinstance(obj, BaseProperty): for i in self._props: if obj.name == i.name: return i else: raise ValueError("odml.Section.contains:" "Section or Property object expected.") def merge_check(self, 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. :param source_section: an odML Section. :param 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. """ if strict and self.definition is not None and source_section.definition is not None: self_def = ''.join(map(str.strip, self.definition.split())).lower() other_def = ''.join(map(str.strip, source_section.definition.split())).lower() if self_def != other_def: raise ValueError( "odml.Section.merge: src and dest definitions do not match!") if strict and self.reference is not None and source_section.reference is not None: self_ref = ''.join(map(str.strip, self.reference.lower().split())) other_ref = ''.join(map(str.strip, source_section.reference.lower().split())) if self_ref != other_ref: raise ValueError( "odml.Section.merge: src and dest references are in conflict!") # Check all the way down the rabbit hole / Section tree. for obj in source_section: mine = self.contains(obj) if mine is not None: mine.merge_check(obj, strict) def merge(self, section=None, strict=True): """ Merges this section with another *section*. See also: :py:attr:`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. :param section: an odML Section. If section is None, *link* or *include* will be resolved instead. :param 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. """ if section is None: # for the high level interface if self._link is not None: self.link = self._link elif self._include is not None: self.include = self._include return # Check all the way down the tree if the destination source and # its children can be merged with self and its children since # there is no rollback in case of a downstream merge error. self.merge_check(section, strict) if self.definition is None and section.definition is not None: self.definition = section.definition if self.reference is None and section.reference is not None: self.reference = section.reference for obj in section: mine = self.contains(obj) if mine is not None: mine.merge(obj, strict) else: mine = obj.clone() mine._merged = obj self.append(mine) self._merged = section @inherit_docstring def clean(self): if self._merged is not None: self.unmerge(self._merged) super(BaseSection, self).clean() def unmerge(self, section): """ Clean up a merged section by removing objects that are totally equal to the linked object """ if self == section: raise RuntimeError("cannot unmerge myself?") removals = [] for obj in section: mine = self.contains(obj) if mine is None: continue if mine == obj: removals.append(mine) else: mine.unmerge(obj) for obj in removals: self.remove(obj) # The path may not be valid anymore, so make sure to update it # however this does not reflect changes happening while the section # is unmerged if self._link is not None: # TODO get_absolute_path, # TODO don't change if the section can # still be reached using the old link self._link = self.get_relative_path(section) self._merged = None @property def is_merged(self): """ Returns True if the section is merged with another one (e.g. through :py:attr:`odml.section.BaseSection.link` or :py:attr:`odml.section.BaseSection.include`) The merged object can be accessed through the *_merged* attribute. """ return self._merged is not None @property def can_be_merged(self): """ Returns True if either a *link* or an *include* attribute is specified """ return self._link is not None or self._include is not None def _reorder(self, childlist, new_index): l = childlist old_index = l.index(self) # 2 cases: insert after old_index / insert before if new_index > old_index: new_index += 1 l.insert(new_index, self) if new_index < old_index: del l[old_index + 1] else: del l[old_index] return old_index def reorder(self, new_index): """ Move this object in its parent child-list to the position *new_index*. :return: The old index at which the object was found. """ if not self.parent: raise ValueError("odml.Section.reorder: " "Section has no parent, cannot reorder in parent list.") return self._reorder(self.parent.sections, new_index) def create_property(self, name, value=None, dtype=None, oid=None): """ Create a new property that is a child of this section. :param name: The name of the property. :param value: Some data value, it can be a single value or a list of homogeneous values. :param 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. :param oid: object id, UUID string as specified in RFC 4122. If no id is provided, an id will be generated and assigned. :return: The new property. """ prop = BaseProperty(name=name, value=value, dtype=dtype, oid=oid) prop.parent = self return prop def pprint(self, indent=2, max_depth=1, max_length=80, current_depth=0): """ Pretty print method to visualize Section-Property trees. :param indent: number of leading spaces for every child Section or Property. :param max_length: maximum number of characters printed in one line. :param current_depth: number of hierarchical levels printed from the starting Section. """ spaces = " " * (current_depth * indent) sec_str = "{} {} [{}]".format(spaces, self.name, self.type) print(sec_str) for p in self.props: p.pprint(current_depth=current_depth, indent=indent, max_length=max_length) if max_depth == -1 or current_depth < max_depth: for s in self.sections: s.pprint(current_depth=current_depth+1, max_depth=max_depth, indent=indent, max_length=max_length) elif max_depth == current_depth: child_sec_indent = spaces + " " * indent more_indent = spaces + " " * (current_depth + 2 * indent) for s in self.sections: print("{} {} [{}]\n{}[...]".format(child_sec_indent, s.name, s.type, more_indent))