itertree package

Indices and tables

Modules

The main itertree class

This code is taken from the itertree package: https://pypi.org/project/itertree/ GIT Home: https://github.com/BR1py/itertree The documentation can be found here: https://itertree.readthedocs.io/en/latest/index.html

The code is published under MIT license:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information see: https://en.wikipedia.org/wiki/MIT_License

This part of code contains the main iTree object

class itertree.itree_main.iTree(tag, data=None, subtree=None)[source]

Bases: list

This is the main class related to iTrees.

This object is the parent of a sub-tree (children, sub-children, etc.). The iTree object itself can also be a child of a parent iTree object. If this is not the case the iTree object is the root of the tree.

A iTree object can only be integrated in one tree (one parent only)!

Each iTree object contains a tag. In case your tags are stings it’s recommended to use tag strings without wildcards “*”,”?” and without the standard separators “/” and “#”. If you use these characters you might get confusing results in find, filter and match operations.

In general we allow all hashable objects to be used as a tag in the iTree objects (only search operation might be limited in this case). But we have two exceptions: We do not allow integers and TagIdx objects as tags because those objects used for direct item access.

Different than in dictionaries it is allowed to put multiple times the same tag inside the iTree. The items with the same tag are placed and ordered (enumerated) in the related tag-family. They can be reached via TagIdx objects by giving the tag, index pair (tag_idx).

Linked iTree objects will behave different. They have a read only structure (children) and they contain the children (tree) of the linked iTree. The “local” attributes like tag, data, … can be set independent from the linked item (local properties). To change the tree structure of such an object you must manipulated the source object and reload the link.

Additionally a iTree object can contain:

data - a iTData object to store any kind of python objects
couple - you can couple the object to another one by giving a pointer
is_temporary - you can mark it as temporary. Those iTree items behave like normal ones. But they will not be considered during encoding for storage, etc.

There are different ways to access the children and sub-children in the tree of a iTree object.

The standard access for single items is via itree_obj[] (__getitem__()) call.

More complex access is available via find() and findall() methods. Have a look in the documentation related to each method.

The delivery of access related operations in the iTree objects is for unique targets an iTree object and for multi target operations an iterator over the matching items. We don’t deliver something like a list.

If really needed an iterator can be easily converted into a list by list() method but this may take a long time for huge iterators. The iterator should only be used in the final step of the operation. It’s recommended to have a look into itertools for better usage of the delivered iterators.

The design of the object is made to have best possible performance even that it is pure python. For more details you may run the performance tests in the test section (But you might have to install additional packages run the comparisons and to get the full picture.)

The function related to iterations iter; iter_children and find_all can be used with an item_filter. By this mechanism you can create queries regarding any property in an iTree.

To initialize the class the following parameters are available

Parameters

tag – tag string or hashable object used for the iTree identification
data – data dict or item to be stored in the node
subtree –
The subtree is a iterable structure that contains sub-items (iTree objects) that should be the children of this iTree.

Warning

subtree: In case the given iTree objects have already a parent an implicit copy will be made.

init_serializer(force=False, exporter=None, importer=None, serializer=None, renderer=None) → None[source]

Method sets the exchange environment that should be used. If you leave the parameters as default, the standard objects will be used.

Note

The method logic is called only one time the first time serializing is needed.

Parameters

force – False (Default) - do not reload in case we have already loaded the items
exporter – exporter object for file export of iTree (dump, dumps)
importer – importer object in ces a file import is done (load, loads)
serializer – Object serializer (especially needed for data objects!)
renderer – A renderer for pretty print output of the iTree object

Returns

None

sort(*arg, **kwargs)[source]: sort operation is not supported, method exists just because super class supports it. Here a TypeError will be raised.

property data

delivers the data-attribute object of the item

Returns: data object of the item

d_set(*args, **kwargs)[source]

set function for a data-attribute

In case the standard iTData object is used we have:

Parameters

key – give key under which the data will be stored, in case data is None the first key parameter is taken as data object and it is stored in the “__NOKEY__” item
value – data value the object that should be stored in the data structure of this iTree

Returns

None

d_get(key=('__iTree_NOKEY__',), return_type=0)[source]

get function for a data attribute

In case the standard iTData object is used we have:

Parameters: key – key under which the data is stored, in case no key is given the “__NOKEY__” item will be returned
Returns: data attribute object

d_update(*args, **kwargs)[source]

update function data-attribute

In case the standard iTData object is used we have:

Parameters

key – give key under which the data will be stored, in case data is None the first key parameter is taken as data object and it is stored in the “__NOKEY__” item
value – data value the object that should be stored in the data structure of this iTree

Returns

None

d_check(value, key=('__iTree_NOKEY__',))[source]

check if the given data-item can be stored under the given key. The check make only sense in case there is a iTreeDataModel or matching object is already stored under the key

Exception

check will raise an iDataValueError or iDataTypeError exception in case the value is not matching in case given key is not found a KeyError will be raised

Parameters

value – data value the object that should be checked
key – give key under which contains the DataModel, in case key is not given the “__NOKEY__” item will be used

Returns

valid value

d_pop(*args, **kwargs)[source]

data related pop (will delete the given key from data-attribute)

Returns: deleted value

d_del(*args, **kwargs)[source]

data related del (will delete the given key)

Returns: deleted value

property parent

property contains the parent item

Returns: iTree parent object (or None in case no parent exists)

property is_root

is this item a root item (has no parent)

Returns: True/False

property root

property delivers the root item of the tree

Returns: iTree root item

property is_read_only

In contrast to iTreeReadOnly class this is False

Returns: False

property is_temporary

In contrast to iTreeTemporary class this is False

Returns: False

property is_placeholder

In contrast to iTreePlaceholder class this is False

Returns: False

property is_linked

In contrast to iTreeLinked class this is False

Returns: False

property link_item

in case we have “covered” a linked item this property delivers the original linked item (mainly for internal use)

Returns: None - no linked item iTreeLink object the covered item

property pre_item

delivers the pre item (predecessor) of this object

Returns: iTree predecessor or None (no match)

property post_item

delivers the post item (successor)

Returns: iTree successor or None (no match)

property depth_up

delivers the distance (number of levels) to the root element of the tree

Returns: integer

property max_depth_down

delivers the max_depth in the direction of the children

Returns: integer maximal children depth

property idx_path

delivers the a list of indexes from the root to this item

Returns: list of index integers (here we do not deliver an iterator)

property tag_idx_path

delivers the a list of TagIdx objects from the root to this item

Returns: list of TagIdx (here we do not deliver an iterator)

property tag_idx

Get the TagIdx object related to this object (contains the tag and the index of the object in the tag-family)

Returns: TagIdx

property tag

This objects tag

Returns: tag object

property idx

Index of this object in the iTree

Returns: integer index

property coupled_object

The iTree object can be couple with another python object. The pointer to the object is stored and can be reached via this property. (E.g. this can be helpful when connecting the iTree with a visual element (tree-list item) in a GUI)

Returns: pointer to coupled object

set_coupled_object(coupled_object)[source]

User can couple this object with others with the help of this attribute .. note:: E.g. this might be an object in a GUI that are related to this item

Parameters: couple_object – object pointer to the object that should be coupled with this iTree item

equal(other, check_parent=False, check_coupled=False)[source]

compares if the data content of another item matches with this item

Parameters

other – other iTree
check_parent – check if item has same parent object too? (Default False)
check_coupled – check the couple object too? (Default False)

Returns

boolean match result (True match/False no match)

copy(*args, **kwargs)[source]

create a copy of this item

The difference in between copy and deepcopy for iTree is just that we do in deepcopy a copy of all data items too. In copy we just copy the iTData object not the items itself, they stay as pointers to the original objects.

The function is used internally in extend operations too. And we can see (profiler) that improvements in this method might have big impact.

Returns: copied iTree object

deepcopy(*args, **kwargs)[source]

create a deepcopy of this item

The difference in between copy and deepcopy for iTree is just that we do in deepcopy a copy of all data items too. In copy we just copy the iTData object not the items itself, they stay as pointers to the original objects.

Returns: deep copied new iTree object

count(item_filter=None)[source]

count the number of children that match to the given filter :: note: The operation is not very quick on huge iTrees and complicate filters!

Parameters: item_filter –
Returns: integer number of children matching to the filter

count_all(item_filter=None)[source]

count deep the number of children and sub children the element has and that match to the given filter :: note: The operation is not very quick on huge iTrees and complicate filters!

Parameters: item_filter –
Returns: integer number of children matching to the filter

get_deep(key_list)[source]

deep key access the function is a replacement for self[key_list[0]][key_list[1]]…[key_list[-1]] but you can also feed with an iterator

dives into the tree key_list=[1,0,2] -> second element level 1 -> first element level 2 -> third element level 3 -> same as self[1][0][2]

Note

Each key in the key list must target to a single item only! E.g. do not use tags here they deliver always a family iterator not a single item (the method will raise an exception). Use index integers or TagIdx objects instead

Parameters: key_list – list or iterator of keys (indexes,TagIdx, tuple(tag,index) -> only in case no tuple tags!
Returns: iTree object the key list targets

clear()[source]: deletes all children and data! All flags stay unchanged!

insert(insert_key, item)[source]

Insert an item before a specific position

Parameters

insert_key – position key (integer index or TagIdx)
item – item that should be inserted in the tree (new child)

append(item)[source]

Append the given iTree object to the tree (new last child)

Except: raise TypeError in case iTree object has already a parent
Parameters: item – iTree object to be appended
Returns: True in case append was successful

appendleft(item)[source]

Append the given iTree object to the left of the the tree (new first child)

Except: raise TypeError in case iTree object has already a parent
Parameters: item – iTree object to be appended

extend(extend_items)[source]

We extend the iTree with given items (multi append)

Note

In case the extend items have already a parent an implicit copy will be made. We do this because we might get an iTree-object as extend_items parameter and then the children will have automatically a parent even that the parent object might be a temporary one.

Parameters: extend_items – iterable object that contains iTree objects as items
Returns: True

extendleft(extend_items)[source]

We extend the iTree with given items in the beginning (multi appendleft)

Note

In case the extend items have already a parent an implicit copy will be made. We do this because we might get an iTree-object as extend_items parameter and then the children will have automatically a parent even that the parent object might be a temporary one.

Note

The extendleft() operation is a lot slower then the normal extend operation

Parameters: extend_items – iterable object that contains iTree objects as items

pop(key=- 1)[source]

pop the item out of the tree, if no key is given the last item will be popped out

Parameters: key – specific identification key for an item (integer index, TagIdx)
Returns: popped out item (parent will be set to None)

popleft()[source]

pop the first item out of the tree

Returns: popped out item (parent will be set to None)

remove(item)[source]

remove the given item out of the tree (delete the child)

Parameters: item – iTree object that should be removed from the tree
Returns: removed item will be returned (parent is set to None)

move(insert_key)[source]

move the item in another position

Parameters: insert_key – item will be insert before this key

rename(new_tag)[source]

give the item a new tag

Parameters: new_tag – new tag object string or hashable object

reverse()[source]: reverse the order of all children in the iTree object

rotate(n)[source]

rotate children of the iTree object n times (rotate 1 times means move last element to first position)

Parameters: n –

iter_all(item_filter=None, filter_or=True)[source]

main iterator for whole tree runs in top-> down order e.g.

iTree('child')
 └──iTree('sub0')
     └──iTree('sub0_0')
     └──iTree('sub0_1')
     └──iTree('sub0_2')
     └──iTree('sub0_3')
 └──iTree('sub1')
     └──iTree('sub1_0')

will be iterated like:

iTree('child')
iTree('sub0')
iTree('sub0_0')
iTree('sub0_1')
iTree('sub0_2')
iTree('sub0_3')
iTree('sub1')
iTree('sub1_0')

Parameters

item_filter – filter for filter the items you can give a filter constant or a method for filtering (should return True/False)
filter_or –
- True - we combine the filtering with or this means even if we have no match in the higher levels of the tree we will go deeper to find matches
- False - filters are combined with and which means children will only be parsed in case the parent matches also to the filter condition

Returns

iterator

iter_all_bottom_up(item_filter=None, filter_or=True)[source]

main iterator for whole tree runs in down-> top order (We start at the children and afterwards the parents: e.g.:

iTree('child')
 └──iTree('sub0')
     └──iTree('sub0_0')
     └──iTree('sub0_1')
     └──iTree('sub0_2')
     └──iTree('sub0_3')
 └──iTree('sub1')
     └──iTree('sub1_0')

Will be iterated:

iTree('sub0_0')
iTree('sub0_1')
iTree('sub0_2')
iTree('sub0_3')
iTree('sub0')
iTree('sub1_0')
iTree('sub1')
iTree('child')

Parameters

item_filter – filter method for filtering (should return True/False when fet with an item) or iTFilter object
filter_or –
- True - we combine the filtering with or this means even if we have no match in the higher levels of the tree we will go deeper to find matches
- False - filters are combined with and which means children will only be parsed in case the parent matches also to the filter condition

Returns

iterator

iter_children(item_filter=None)[source]

main iterator in children level

Parameters: item_filter – the items can be filtered by giving a filter constants or giving a filter method or iTFilter object
Returns: iterator

iter_tag_idxs(item_filter=None)[source]

iter over all children and deliver the children TagIdx

Parameters: item_filter – the items can be filtered by giving a filter constants or giving a filter method or iTFilter object
Returns: iterator over the TagIdx of the children

iter_tag_idxs_all(item_filter=None)[source]

Delivers an iterator over all items tag_idx_paths

Parameters: item_filter – the items can be filtered by giving a filter constants or giving a filter method or iTFilter object
Returns: iterator over tuples of tag_idxs_paths of all items

iter_idxs_all(item_filter=None)[source]

Delivers an iterator over all items index path tuples .. note:: This method is mainly usd for internal proposes (max_depth_down)

Parameters: item_filter – item_filter filter method might be used
Returns: iterator over tuples of index paths of all items

find_all(key_path, item_filter=None, str_path_separator='/', str_index_separator='#')[source]

The find all function works on all levels of the tree. The key_path given (e.g. a list of indexes) addresses the items into the depth first item first level, second item second level,….

The method returns always an iterator or in case of no match an empty list! If you target to unique objects you will get anyway an iterator containing this unique element.

Warning

It’s possible to create invalid recursions when constructing the key_path. In these cases the recursion depth exceeded exception will be raised by the interpreter

In case the target in the upper keys is not unique, all matches will be delivered! e.g. The operation my_tree.find_all([‘child’,’sub_child’]) takes first all items in the “child” family:

TagIdx(‘child’,0),TagIdx(‘child’,1),…TagIdx(‘child’,n) in an iterator and in the next step the function will go one level deeper and will cumulate all the ‘sub_child’ families in these items as the result:

This means we have something like this:

my_tree[TagIdx(‘child’,0)][TagIdx(‘sub_child’,0)],my_tree[TagIdx(‘child’,0)][TagIdx(‘sub_child’,1)],…,

my_tree[TagIdx(‘child’,1)][TagIdx(‘sub_child’,0)],my_tree[TagIdx(‘child’,0)][TagIdx(‘sub_child’,1)],…,

…

and in case of no match in the keys items are skipped.

Note

It’s not at all the same as: my_tree[‘child’][‘sub_child’] -> this operation will raise an exception!

Note

When addressing a single item it’s quicker (~10x faster depending on tree depth) to use the get_deep() method instead of the find_all() method.

The key_path parameter is very flexible in case of the objects you put in. We have several possibilities:

Special keys: We have the following special keys that might be used in the key_path:
- “/” default path separator (might be changed by str_path_separator parameter) If this is the first key the find_all() search will be started in the root element not in the element the method is called.
  
  Note
  
  Be careful with “//” or “/” placed not in the beginning of the path this will rollback the find_all() to the root which means anything in the key_path before this key will be ignored.
- “*”-wildcard will iterate over all children of the item
- “**”-wildcard will iterate over all items of the item. The item itself is the first element of the iterator delivered
  
  Note
  
  find_all(‘**’) creates an different iterator then iter_all() list(my_tree.find_all(‘**’)) = [my_tree] + list(my_tree.iter_all())
Warning

It’s always recommended to avoid the usage of string tags containing functional characters like “**”,”*”,”/”,”#”,”?”. E.g. In case the iTree contains a family with the tag “/” or “*” or “**” the related family will be delivered. The special functionality is blocked in this moment (for “/” you might use the str_path_separator parameter to keep the functionality). Also filtering via iTMatch objects is limited in this case.
Give normal keys like in __getitem__() method: normal keys can be:
- index integers
- tag strings
- TagIdx,TagIdxStr,TagIdxBytes
- TagMultiIdx,slices
- for index lists you must give[[1,2,3,4]] because first level will be interpreted as
- a list targeting into the depth of the tree
e.g. by index
my_tree.find_all(1) is same as my_tree[1]

my_tree.find_all(‘child’) is same as my_tree[‘child’]

my_tree.find_all(TagIdx(‘child’,1))`is same as `my_tree[TagIdx(‘child’,1)]

…
Give a list of normal keys:

e.g. by index
- `my_tree.find_all([1,2])`is same as my_tree[1][2]
- my_tree.find_all([‘child’,’sub_child’]) delivers an iterator over all “sub_child” families found
  in all “child” families
- my_tree.find_all([TagIdx(‘child’,1),TagIdx(‘sub_child’,1)])`is same as `my_tree[TagIdx(‘child’,1)][TagIdx(‘sub_child’,1)]
…
Give iTMatch() object or list of iTMatch() objects:

An iterator of all matching tags will be created the matches will be combined with the and operation. You can also use an item_filter containing the Filter.iTFilterItemTagMatch to have the same functionality. In case a list is given the find_all() function is again going one level deeper for each element in the list.

Parameters

key_path – iterable/iterator that addresses items in the tree (see above explanations and examples)
item_filter – item_filter method
str_path_separator – In case of string tags the user can give also strings that are internally casted into a list by using the str_path_separator (default=”/”) e.g.: “/child_tag/sub_child_tag” -> [“child_tag”,”sub_child_tag”]
str_index_separator – In case of string tags the user can give TgaIdx also by string definition this is the separator used to separate the index number from the tag (default=”#”) e.g. “child_tag#89” -> TagIdx(“child_tag”,89)

Returns

iterator over the matches or in case of no match found an empty list -> []

find_all2(key_path, item_filter=None, str_path_separator='/', str_index_separator='#', _initial=True)[source]

Method is outdated use find_all instead!

The find_all function targets over multiple levels of the datatree, it returns a list or iterator of the matching items!

The key_path parameter given is normally a list. This can be a list of keys or TagIdx objects. The function will search for the first item in the first level, fo next item in the next level and so on…

Absolut and relative key_paths:

If the first item is the separator (default: ‘/’) the find search is like an absolute path and we start at the root of the datatree. If the first item is different, the key_path is relative and we start from the actual item and search the children and sub-children.

Single string key_path: If the user searches for string type tags he can use a string with a separator (default: ‘/’) in between the tags (These type of key_paths will be implicit translated in a list in the function). An index separator (default = ‘#’) in between the tag and the index can also be used to identify to identify items in the tag family. If the key_path argument is already a list the single keys will not be parsed regarding the str_path_separator anymore.

HINT: Quickest find operations can be performed by giving a list containing index integers or TagIdx objects

The items can be filtered regarding specific content, for this a look into the available filer constructors: create_xxx_item_filter() might be interesting. The filter method or the filter constant can be given in the item_filter parameter

The parameters in detail:

Parameters

key_path –
single key or list of keys identification path for the item/items to be searched. Possible keys: integer - behaves like normal __getitem__() -> itree_item[key] TagIdx- behaves like normal __getitem__() -> itree_item[key] iTreeTagSlice - select a tag sliced group of sub-elements iTMatch - search pattern can be used too, but keep in mind it must deliver a unique result! Slice - a slice of indexes (like a special index list) string - will be parsed by the separators iterable list/tuple/deque,… -

run over single keys if sub_key is again an iterable it will be taken as an index list (e.g. [1,2,3] - will go deeper in the tree 1. item; 2. subitem; 3. subsubitem but [[1,2,3]] - will stay in the first level and deliver 1. item; 2. item; 3. item)
item_filter – filters the item content regarding NORMAL, TEMPORARY and LINKED flag or a given filtering method
str_path_separator – separator character in case of strings for the search levels (default: “/”)
str_index_separator – separator character for given tag indexes (default: “#”)
_initial – Internal flag that should protect against cyclic constructs

Returns

list or iterator of matching iTrees; in case of no match and empty list is returned

find(key_path, item_filter=None, default_return=None, str_path_separator='/', str_index_separator='#')[source]

The find function targets over multiple levels of the iTree, it returns single items only! This means in case the key_path targets to multiple items the default_return will be given. If the key_path targets to a family with only one item inside or the item_filter extracts only one item in a family the item will be given back as result. For multiple result utilize the find_all() method (which is slower).

Note

The method will deliver a default_return when ever in the whole key_path a match is not unique. This means iteration is stopped here and even that a deeper iteration with the defined filtering might deliver at least a unique result. To ensure to find this deeper results you must utilize the slower find_all() method.

The key_path parameter given is normally a list. This can be a list of keys or TagIdx objects. The function will search for the first item in the first level, fo next item in the next level and so on…

Absolut and relative key_paths:

If the first item is the separator (default: ‘/’) the find search is like an absolute path and we start at the root of the iTree. For compatibility reasons with find_all we accept a leading “./” (or to be exact: “.%s”#str_path_separator) as absolute path indicator. If the first item is different, the key_path is relative and we start from the actual item and search the children and sub-children.

Single string key_path: If the user searches for string type tags he can use a string with a separator (default: ‘/’) in between the tags (Those key_paths will be implicit translated in a list). An index separator (default = ‘#’) in between the tag and the index can also be used in this case. If the argument is already a list the single keys will not be parsed regarding the str_path_separator.

Note

If iTree contains tags with characters that used for separators or the all match ‘*’ character the find() result might contain that tagged item instead of the expected separated or wildcard match.

Note

Quickest find operations can be performed by giving a list containing index integers or TagIdx objects

The parameters in detail:

Parameters

key_path –
single key or list of keys identification path for the item/items to be searched. Possible keys: integer - behaves like normal __getitem__() -> itree_item[key] TagIdx- behaves like normal __getitem__() -> itree_item[key] iTreeTagSlice - select a tag sliced group of sub-elements iTMatch - search pattern can be used too, but keep in mind it must deliver a unique result! Slice - a slice of indexes (like a special index list) string - will be parsed by the separators, special string ‘*” is as interpreted as any match iterable list/tuple/deque,… -

run over single items
item_filter – filters the item content regarding NORMAL, TEMPORARY and LINKED flag or a given filtering method
default_return – object will be return in case of no match (default = None)
str_path_separator – separator character in case of strings for the search levels (default: “/”)
str_index_separator – separator character for given tag indexes (default: “#”)

Returns

iTree single item

index(item, item_filter=None)[source]

The index method allows to search for the index of the item in a parent object This is especially useful if you must use a item_filter. The delivered index is delivered relative to the given item filter!

For the item index of the item in the unfiltered tree (ALL) it’s recommended to use the idx property instead: (parent.index(item,ALL) == item.idx)

Parameters

item – item index should be delivered for
item_filter – filter integer; method can not handle filter methods yet!

Returns

index integer of the item relative to the given filter

load_links(force=False, delete_invalid_items=False)[source]

Runs ove all children and sub children in case a ITreeLink object is found the linked items are load in

Parameters

force – True - linked items will be reloaded even that they are already loaded
delete_invalid_items – In case a iTreeLink refers to an invalid item (internal exception) the related iTreeLink object will be deleted from teh tree

loads(data_str, check_hash=True, load_links=True)[source]

create an iTree object by loading from a string

If not overloaded or reinitialized the iTree Standard Serializer will be used. In this case we expect a matching JSON representation.

Parameters

data_str – source string that contains the iTree information
check_hash – True the hash of the file will be checked and the loading will be stopped if it doesn’t match False - do not check the iTree hash
load_links – True - linked iTree objects will be loaded

Returns

iTree object loaded from file

load(file_path, check_hash=True, load_links=True)[source]

create an iTree object by loading from a file

If not overloaded or reinitialized the iTree Standard Serializer will be used. In this case we expect a matching JSON representation.

Parameters

file_path – file path to the file that contains the iTree information
check_hash – True the hash of the file will be checked and the loading will be stopped if it doesn’t match False - do not check the iTree hash
load_links – True - linked iTree objects will be loaded

Returns

iTree object loaded from file

dumps(calc_hash=True)[source]

serializes the iTree object to JSON (default serializer)

Parameters: calc_hash – Tell if the hash should be calculated and stored in the header of string
Returns: serialized string (JSON in case of default serializer)

dump(target_path, pack=True, calc_hash=True, overwrite=False)[source]

serializes the iTree object to JSON (default serializer) and store it in a file

Parameters

target_path – target path of the file where the iTree should be stored in
pack – True - data will be packed via gzip before storage
calc_hash – True - create the hash information of iTree and store it in the header
overwrite – True - overwrite an existing file

Returns

True if file is stored successful

renders(item_filter=None)[source]

render the iTree into a string

Parameters: item_filter – the items can be filtered by giving a filter constants or giving a filter method or iTFilter object
Returns: Tree representation as string

render(item_filter=None)[source]

print the rendered the iTree string to the terminal

Parameters: item_filter – the items can be filtered by giving a filter constants or giving a filter method or iTFilter object

class itertree.itree_main.iTreeReadOnly(tag, data=None, subtree=None, freeze_struct_only=False)[source]

Bases: iTree

This iTree object is read only the initial parameters given cannot be changed the object remains static in the tree and can only be changed when deleted and replaced

insert(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

append(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

appendleft(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

extend(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

extendleft(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

rotate(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

reverse(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

pop(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

popleft(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

remove(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

clear()[source]

Except: PermissionError not possible on iTreeReadOnly objects

class itertree.itree_main.iTreeTemporary(tag, data=None, subtree=None)[source]

Bases: iTree

This is a temporary item that will not be considered if the iTree is saved into a file.

class itertree.itree_main.iTreeLink(tag, data=None, subtree=None, link_file_path=None, link_key_path=None, load_links=True)[source]

Bases: iTree

This class is used to define linked subtrees in a iTree object. The target source can be a subtree in another iTree related file (external links) or internal links to a subtree of the already loaded subtree.

Linking has some functional limitations so is it not allowed to link to already linked objects (we must protect iTree from circular definitions).

The iTreeLink objects supports local items which can be added additional to the linked items. Furthermore there is also a mechanism so that local items can overlay the linked items in the tree. This is done by localizing the linked items with the make_child_local() or make_self_local() method. Afterwards the item can be manipulated as a normal iTree object. Only exception is that after deleting such a overlaying item the linked item will come back into the iTree.

rotate(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

reverse(*args, **kwargs)[source]

Except: PermissionError not possible on iTreeReadOnly objects

append(item)[source]: append of items is allowed (items are appended as locals :param item: item to be appended :return:

extend(items)[source]: extend of items is allowed, items are appended as locals :param items: items to be appended (iterator) :return: None

extendleft(item)[source]

Except: PermissionError not possible on iTreeReadOnly objects

appendleft(item)[source]

Except: PermissionError not possible on iTreeReadOnly objects

insert(insert_key, item)[source]

Except: PermissionError not possible on iTreeReadOnly objects

pop(key)[source]

pop the object out of the tree (only possible on local objects)

Except: In case a linked item is selected an PermissionError is raised
Parameters: key – identification key for the child that should be popped out
Returns: popped out item (parent set to None)

popleft()[source]

pop the first child out of the tree (only possible on local object)

Except: In case a linked item is selected an PermissionError is raised
Returns: popped first item (parent set to None)

remove(item)[source]

remove the given child item out of the tree (only possible on local object)

Except: In case a linked item is selected an PermissionError is raised
Parameters: item – item to be removed from the iTree
Returns: removed item (parent set to None)

rename(item_tag)[source]

Except: PermissionError not possible on iTreeReadOnly objects

property is_link_root

Is this item the highest level linked element?

Returns: True/False

property link_root

delivers the highest level element that is linked in case item is not linked it delivers it self

Returns: highest level linked item found in the parents

property is_link_loaded

For linked iTree objects we deliver here the state of loading the links

Returns: True/False

make_self_local()[source]

make the current linked object a local object This is only possible if the parent parent is a normal iTree object -> only the first level children in a linked iTree can be made local The operation raises an SyntaxError in case it is used on a deeper level of the linked tree

Returns: None

make_child_local(key)[source]

make the item related to the given key a local object This is only possible if the parent of self is a normal iTree object -> only the first level children in a linked iTree can be made local The operation raises an SyntaxError in case it is used on a deeper level of the linked tree

Parameters: key – identification key for the child item that should be converted in a local item
Returns: None

iter_locals(add_placeholders=False)[source]

iterator that iterates only over the local elements

Parameters: add_placeholders – If this flag is set the (normally ignored) placeholder items are included in the iteration
Returns: iterator over local items

get_last_local_idx(tag)[source]

helper function which searches for local items in the tag family and delivers the last index of a local item found in the family. If no local item is found it delivers None.

iTreePlaceHolder items ignored in this operation!

Parameters: tag – tag to identify the family to be searched in
Returns: last local item idx in tag family or None (no local item found)

load_links(force=False, delete_invalid_items=False, _items=None)[source]

load all linked items

Parameters

force – False (default) - load only if not already loaded True - load even if already loaded (update)
delete_invalid_items – False (default) - in case of invalid items we will raise an exception! True - invalid items will be removed from parent no exception raised
_items – internal list parameter used for recursive calls of the function

Returns

True - success
False - load failed

clear(local_only=False)[source]

We clear the object

Parameters

local_only –

True - clear only the local items
False - clear whole object (The object is reset to the no links loaded state and locals
are deleted)

Returns

equal(other, check_parent=False, check_coupled=False, check_link=False)[source]

compares if the data content of another item matches with this item

Parameters

other – other iTree
check_parent – check the parent object too? (Default False)
check_coupled – check the couple object too? (Default False)
check_link – check the internal link variable too? (Default False)

Returns

boolean match result (True match/False no match)

class itertree.itree_main.iTreePlaceHolder(tag)[source]

Bases: iTreeReadOnly

place holder item that helps to keep items name in the overloading mechanism

itertree data classes

This code is taken from the itertree package: https://pypi.org/project/itertree/ GIT Home: https://github.com/BR1py/itertree The documentation can be found here: https://itertree.readthedocs.io/en/latest/index.html

The code is published under MIT license:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information see: https://en.wikipedia.org/wiki/MIT_License

This part of code contains the helper functions related to the iTree data attribute

exception itertree.itree_data.iTDataValueError[source]

Bases: ValueError

Exception to be raised in case a validator finds a non matching value related to the iDataModel

exception itertree.itree_data.iTDataTypeError[source]

Bases: ValueError

Exception to be raised in case a validator finds a non matching value type related to the iDataModel

class itertree.itree_data.iTDataModel(value=('__iTree_NOVALUE__',))[source]

Bases: ABC

The default iTree data model class This the interface definition for specific data model classes that might be created using this superclass

The data model checks the given value for a specific data item. So that we can ensure that the given value matches to the expectations. We can check for types, shapes (length), limits, or matching patterns.

Besides the check we can also define a default formatter for the value that is used when it is translated into a string.

(see examples/itree_data_examples.py)

property is_empty: tells if the iTreeDataModel is empty or contains a value :return:

property is_iTDataModel

get()[source]: the stored value :return: object stored in value

set(value, _it_data_model_identifier=None)[source]

put a specific value into the data model

Except

raises an iTreeValidationError in case a not matching object is given

Parameters

value – value object to be placed in the data model
_it_data_model_identifier – internal parameter used for identification of the set method in special cases, no functional impact

property value: the stored value :return: object stored in value

clear(_it_data_model_identifier=None)[source]

clears (deletes) the current value content and sets the state to “empty”

Parameters: _it_data_model_identifier – internal parameter used for identification of the set method in special cases, no functional impact
Returns: returns the value object that was stored in the iTreeDataModel

abstract validator(value)[source]

This method should check the given value.

It should raise an iDataValueError Exception with a failure explanation in case the value is not matching to the iDataModel.

..warning:: The validator in an explicit iDataModel class must always return the value itself and it must raise: the iDataValueError in case of a no matching value. It should also call the super().validator() method or at least consider that __NOVALUE__ is a no matching value.

Except: iDataValueError in case value is not matching
Parameters: value – to be checked against the model
Returns: value (which might be casted)

abstract formatter(value=None)[source]

The formatter function allows us to create a specific string representation

Especially in case of numerical values this is interesting. You can define here that an integer should be represented always as hex, bin, … or for floats you can give digits.

The formatter can be created by using the classical format options of string but for enumerations we can put here also a table, etc.

Returns: string representing the value

class itertree.itree_data.iTDataModelAny(value=('__iTree_NOVALUE__',))[source]

Bases: iTDataModel

Example iDataModel class that accepts any kind of value

validator(value)[source]

This method should check the given value.

It should raise an iDataValueError Exception with a failure explanation in case the value is not matching to the iDataModel.

..warning:: The validator in an explicit iDataModel class must always return the value itself and it must raise: the iDataValueError in case of a no matching value. It should also call the super().validator() method or at least consider that __NOVALUE__ is a no matching value.

Except: iDataValueError in case value is not matching
Parameters: value – to be checked against the model
Returns: value (which might be casted)

formatter(value=None)[source]

The formatter function allows us to create a specific string representation

Especially in case of numerical values this is interesting. You can define here that an integer should be represented always as hex, bin, … or for floats you can give digits.

The formatter can be created by using the classical format options of string but for enumerations we can put here also a table, etc.

Returns: string representing the value

class itertree.itree_data.iTData(seq=None, **kwargs)[source]

Bases: dict

Standard itertree Data management object might be overloaded or changed by the user

GET_LOOK_UP_METHOD = {0: <function iTData.<lambda>>, 1: <function iTData.<lambda>>, 2: <function iTData.<lambda>>}

update(E=None, **F)[source]

function update of multiple items if one item is invalid the whole update will be skipped and an iDataValueError exception will thrown!

In case the replace_model flag is set the model will be exchanged.

Parameters taken from builtin dict:

Update D from dict/iterable E and F. If E is present and has a .keys() method, then does: If E is present and lacks a .keys() method, then does: In either case, this is followed by:

Except

raises iDataValueError exception if a value in the given object is not matching to the data-model. The iData object will not be updated in this case.

Parameters

E –
- with .keys() method: for k in E: D[k] = E[k]
- without .keys() method: for k, v in E: D[k] = v
**F –
we run: for k in F: D[k] = F[k]
replace_models –
- True - Will replace the whole key related value (also iTDataModels are replaced)
- False (default) - All values are replaced in case of iTDataModel object the internal value will
  be replaced

copy()[source]

create a new object with same items

Returns: new object copied from self

clear() → None. Remove all items from D.[source]

pop(key=('__iTree_NOKEY__',), default=('__iTree_NOKEY__',), value_only=True)[source]

delete a stored value

Except

will case KeyError if key is not found and default is not set

Parameters

key – key where the item should be popped out
value_only – True - only value will be deleted model will be kept in iTreeData False - whole model will be popped out

Default

define the value given back in case key is not found else KeyError will be raised

Returns

deleted item or default

get(key=('__iTree_NOKEY__',), default=None, return_type=0)[source]

get a specific data item by key

Parameters

key – key of the data item (if not given __NOKEY__ is used)
default – default value that will be delivered in case of no match
_return_type – We can deliver different returns * VALUE - value object * FULL - iTreeDataModel (only if used else same as VALUE) * STR - formatted string representation of the data value

Returns

requested value

fromkeys(*args, **kwargs)[source]

create a new iData object based on given keys and optional value

real signature unknown

delete_item(key, value_only=True)[source]

delete a item by key

Except

KeyError is raised in case item key is unknown

Parameters

key – key of the data item (if not given __NOKEY__ is used!
value_only –
- True - (default) in case of iDataModel items we delete only the internal value
  not the model itself
- False - we delete the value independent from the type (also iDataModel objects)

Returns

deleted value

model_values()[source]

iterator that takes in case of iDataModel values the value out of the model, in case of non iDataModel values the value is given directly as it is

Returns: iterator

model_items()[source]

iterator that takes in case of iDataModel values the value out of the model, in case of non iDataModel values the value is given directly as it is

Returns: iterator

property is_empty: used for identification of this class :return: True

property is_no_key_only: used for identification of this class :return: True

property is_iTData

is_key_empty(key=('__iTree_NOKEY__',))[source]: Function delivers a key empty state (it delivers True in case key is absent or value is __NOVALUE__ :param key: key to be check (delault is __NOKEY__ :return: True/False

deepcopy()[source]

create a deep copy of this object

also all internal items will be copied!

Returns: new object deep copied from self

class itertree.itree_data.iTDataReadOnly(seq=None, **kwargs)[source]

Bases: iTData

Standard itertree Data management object might be overloaded or changed by the user

pop(*arg, **kwargs)[source]

delete a stored value

Except

will case KeyError if key is not found and default is not set

Parameters

key – key where the item should be popped out
value_only – True - only value will be deleted model will be kept in iTreeData False - whole model will be popped out

Default

define the value given back in case key is not found else KeyError will be raised

Returns

deleted item or default

update(*arg, **kwargs)[source]

function update of multiple items if one item is invalid the whole update will be skipped and an iDataValueError exception will thrown!

In case the replace_model flag is set the model will be exchanged.

Parameters taken from builtin dict:

Update D from dict/iterable E and F. If E is present and has a .keys() method, then does: If E is present and lacks a .keys() method, then does: In either case, this is followed by:

Except

raises iDataValueError exception if a value in the given object is not matching to the data-model. The iData object will not be updated in this case.

Parameters

E –
- with .keys() method: for k in E: D[k] = E[k]
- without .keys() method: for k, v in E: D[k] = v
**F –
we run: for k in F: D[k] = F[k]
replace_models –
- True - Will replace the whole key related value (also iTDataModels are replaced)
- False (default) - All values are replaced in case of iTDataModel object the internal value will
  be replaced

clear() → None. Remove all items from D.[source]

delete_item(key, value_only=True)[source]

delete a item by key

Except

KeyError is raised in case item key is unknown

Parameters

key – key of the data item (if not given __NOKEY__ is used!
value_only –
- True - (default) in case of iDataModel items we delete only the internal value
  not the model itself
- False - we delete the value independent from the type (also iDataModel objects)

Returns

deleted value

itertree filter classes

This code is taken from the itertree package: https://pypi.org/project/itertree/ GIT Home: https://github.com/BR1py/itertree The documentation can be found here: https://itertree.readthedocs.io/en/latest/index.html

The code is published under MIT license:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information see: https://en.wikipedia.org/wiki/MIT_License

This part of code contains the helper functions related to the iTree data attribute

exception itertree.itree_data.iTDataValueError[source]

Bases: ValueError

Exception to be raised in case a validator finds a non matching value related to the iDataModel

exception itertree.itree_data.iTDataTypeError[source]

Bases: ValueError

Exception to be raised in case a validator finds a non matching value type related to the iDataModel

class itertree.itree_data.iTDataModel(value=('__iTree_NOVALUE__',))[source]

Bases: ABC

The default iTree data model class This the interface definition for specific data model classes that might be created using this superclass

The data model checks the given value for a specific data item. So that we can ensure that the given value matches to the expectations. We can check for types, shapes (length), limits, or matching patterns.

Besides the check we can also define a default formatter for the value that is used when it is translated into a string.

(see examples/itree_data_examples.py)

property is_empty: tells if the iTreeDataModel is empty or contains a value :return:

property is_iTDataModel

get()[source]: the stored value :return: object stored in value

set(value, _it_data_model_identifier=None)[source]

put a specific value into the data model

Except

raises an iTreeValidationError in case a not matching object is given

Parameters

value – value object to be placed in the data model
_it_data_model_identifier – internal parameter used for identification of the set method in special cases, no functional impact

property value: the stored value :return: object stored in value

clear(_it_data_model_identifier=None)[source]

clears (deletes) the current value content and sets the state to “empty”

Parameters: _it_data_model_identifier – internal parameter used for identification of the set method in special cases, no functional impact
Returns: returns the value object that was stored in the iTreeDataModel

abstract validator(value)[source]

This method should check the given value.

It should raise an iDataValueError Exception with a failure explanation in case the value is not matching to the iDataModel.

..warning:: The validator in an explicit iDataModel class must always return the value itself and it must raise: the iDataValueError in case of a no matching value. It should also call the super().validator() method or at least consider that __NOVALUE__ is a no matching value.

Except: iDataValueError in case value is not matching
Parameters: value – to be checked against the model
Returns: value (which might be casted)

abstract formatter(value=None)[source]

The formatter function allows us to create a specific string representation

Especially in case of numerical values this is interesting. You can define here that an integer should be represented always as hex, bin, … or for floats you can give digits.

The formatter can be created by using the classical format options of string but for enumerations we can put here also a table, etc.

Returns: string representing the value

class itertree.itree_data.iTDataModelAny(value=('__iTree_NOVALUE__',))[source]

Bases: iTDataModel

Example iDataModel class that accepts any kind of value

validator(value)[source]

This method should check the given value.

It should raise an iDataValueError Exception with a failure explanation in case the value is not matching to the iDataModel.

..warning:: The validator in an explicit iDataModel class must always return the value itself and it must raise: the iDataValueError in case of a no matching value. It should also call the super().validator() method or at least consider that __NOVALUE__ is a no matching value.

Except: iDataValueError in case value is not matching
Parameters: value – to be checked against the model
Returns: value (which might be casted)

formatter(value=None)[source]

The formatter function allows us to create a specific string representation

Especially in case of numerical values this is interesting. You can define here that an integer should be represented always as hex, bin, … or for floats you can give digits.

The formatter can be created by using the classical format options of string but for enumerations we can put here also a table, etc.

Returns: string representing the value

class itertree.itree_data.iTData(seq=None, **kwargs)[source]

Bases: dict

Standard itertree Data management object might be overloaded or changed by the user

GET_LOOK_UP_METHOD = {0: <function iTData.<lambda>>, 1: <function iTData.<lambda>>, 2: <function iTData.<lambda>>}

update(E=None, **F)[source]

function update of multiple items if one item is invalid the whole update will be skipped and an iDataValueError exception will thrown!

In case the replace_model flag is set the model will be exchanged.

Parameters taken from builtin dict:

Update D from dict/iterable E and F. If E is present and has a .keys() method, then does: If E is present and lacks a .keys() method, then does: In either case, this is followed by:

Except

raises iDataValueError exception if a value in the given object is not matching to the data-model. The iData object will not be updated in this case.

Parameters

E –
- with .keys() method: for k in E: D[k] = E[k]
- without .keys() method: for k, v in E: D[k] = v
**F –
we run: for k in F: D[k] = F[k]
replace_models –
- True - Will replace the whole key related value (also iTDataModels are replaced)
- False (default) - All values are replaced in case of iTDataModel object the internal value will
  be replaced

copy()[source]

create a new object with same items

Returns: new object copied from self

clear() → None. Remove all items from D.[source]

pop(key=('__iTree_NOKEY__',), default=('__iTree_NOKEY__',), value_only=True)[source]

delete a stored value

Except

will case KeyError if key is not found and default is not set

Parameters

key – key where the item should be popped out
value_only – True - only value will be deleted model will be kept in iTreeData False - whole model will be popped out

Default

define the value given back in case key is not found else KeyError will be raised

Returns

deleted item or default

get(key=('__iTree_NOKEY__',), default=None, return_type=0)[source]

get a specific data item by key

Parameters

key – key of the data item (if not given __NOKEY__ is used)
default – default value that will be delivered in case of no match
_return_type – We can deliver different returns * VALUE - value object * FULL - iTreeDataModel (only if used else same as VALUE) * STR - formatted string representation of the data value

Returns

requested value

fromkeys(*args, **kwargs)[source]

create a new iData object based on given keys and optional value

real signature unknown

delete_item(key, value_only=True)[source]

delete a item by key

Except

KeyError is raised in case item key is unknown

Parameters

key – key of the data item (if not given __NOKEY__ is used!
value_only –
- True - (default) in case of iDataModel items we delete only the internal value
  not the model itself
- False - we delete the value independent from the type (also iDataModel objects)

Returns

deleted value

model_values()[source]

iterator that takes in case of iDataModel values the value out of the model, in case of non iDataModel values the value is given directly as it is

Returns: iterator

model_items()[source]

iterator that takes in case of iDataModel values the value out of the model, in case of non iDataModel values the value is given directly as it is

Returns: iterator

property is_empty: used for identification of this class :return: True

property is_no_key_only: used for identification of this class :return: True

property is_iTData

is_key_empty(key=('__iTree_NOKEY__',))[source]: Function delivers a key empty state (it delivers True in case key is absent or value is __NOVALUE__ :param key: key to be check (delault is __NOKEY__ :return: True/False

deepcopy()[source]

create a deep copy of this object

also all internal items will be copied!

Returns: new object deep copied from self

class itertree.itree_data.iTDataReadOnly(seq=None, **kwargs)[source]

Bases: iTData

Standard itertree Data management object might be overloaded or changed by the user

pop(*arg, **kwargs)[source]

delete a stored value

Except

will case KeyError if key is not found and default is not set

Parameters

key – key where the item should be popped out
value_only – True - only value will be deleted model will be kept in iTreeData False - whole model will be popped out

Default

define the value given back in case key is not found else KeyError will be raised

Returns

deleted item or default

update(*arg, **kwargs)[source]

function update of multiple items if one item is invalid the whole update will be skipped and an iDataValueError exception will thrown!

In case the replace_model flag is set the model will be exchanged.

Parameters taken from builtin dict:

Update D from dict/iterable E and F. If E is present and has a .keys() method, then does: If E is present and lacks a .keys() method, then does: In either case, this is followed by:

Except

raises iDataValueError exception if a value in the given object is not matching to the data-model. The iData object will not be updated in this case.

Parameters

E –
- with .keys() method: for k in E: D[k] = E[k]
- without .keys() method: for k, v in E: D[k] = v
**F –
we run: for k in F: D[k] = F[k]
replace_models –
- True - Will replace the whole key related value (also iTDataModels are replaced)
- False (default) - All values are replaced in case of iTDataModel object the internal value will
  be replaced

clear() → None. Remove all items from D.[source]

delete_item(key, value_only=True)[source]

delete a item by key

Except

KeyError is raised in case item key is unknown

Parameters

key – key of the data item (if not given __NOKEY__ is used!
value_only –
- True - (default) in case of iDataModel items we delete only the internal value
  not the model itself
- False - we delete the value independent from the type (also iDataModel objects)

Returns

deleted value

itertree serializing

This code is taken from the itertree package: https://pypi.org/project/itertree/ GIT Home: https://github.com/BR1py/itertree The documentation can be found here: https://itertree.readthedocs.io/en/latest/index.html

The code is published under MIT license:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information see: https://en.wikipedia.org/wiki/MIT_License

This part of code contains the standard iTree serializers (JSON and rendering)

class itertree.itree_serialize.iTStdObjSerializer[source]

Bases: object

This class converts objects to raw objects (that can be converted by standard JSON serializer) and back conversion is also included

TREE = 'iT'

DATA = 'DT'

LINK = 'LK'

TAG = 'TG'

IDX = 'IDX'

DATA_MODELL = 'DM'

DTYPE = 'TP'

DATA_CONTAINER = 'DC'

ITREE_ITEMS_DECODE = {'iT': <class 'itertree.itree_main.iTree'>, 'iTI': <class 'itertree.itree_helpers.TagIdx'>, 'iTPH': <class 'itertree.itree_main.iTreePlaceHolder'>, 'iTRO': <class 'itertree.itree_main.iTreeReadOnly'>, 'iTl': <class 'itertree.itree_main.iTreeLink'>}

ITREE_ITEMS_ENCODE = {<class 'itertree.itree_main.iTree'>: 'iT', <class 'itertree.itree_main.iTreeReadOnly'>: 'iTRO', <class 'itertree.itree_main.iTreeLink'>: 'iTl', <class 'itertree.itree_main.iTreePlaceHolder'>: 'iTPH', <class 'itertree.itree_helpers.TagIdx'>: 'iTI'}

OTHER_ITEMS_DECODE = {'D': <class 'itertree.itree_data.iTData'>, 'DR': <class 'itertree.itree_data.iTDataReadOnly'>, 'OD': <class 'collections.OrderedDict'>, 'd': <class 'dict'>}

OTHER_ITEMS_ENCODE = {<class 'dict'>: 'd', <class 'itertree.itree_data.iTData'>: 'D', <class 'itertree.itree_data.iTDataReadOnly'>: 'DR', <class 'collections.OrderedDict'>: 'OD'}

encode(o)[source]: encode the given object to a list or dict (unordered objects) :param o: object :return: list

decode(raw_o)[source]: decode the given raw_object back to the original object :param raw_o: raw_object (dict or list) :param load_links: load the links of the linked iTree objects :return: constructed object

class itertree.itree_serialize.iTStdJSONSerializer(obj_serializer=None)[source]

Bases: object

This is the standard serializer for DataTree which translates the structure into the JSON format. Users might implement there own serializers using the interface methods defined in this serializer

dumps2(o, add_header=True, calc_hash=True)[source]: new dump not yet working still in development! should be iterative and only one iteration over all items should be done (not two like in the current solution) :param o: :param add_header: :param calc_hash: :return:

dumps(o, add_header=True, calc_hash=True)[source]

In JSON the iTree object is represented in the following form Item-> dict with all properties (Special keys used) Tree structure is stored in list

Parameters

o – iTree object to be serialized
add_header – True - the header information will be added (containing Version info and hash) False - no header pure data
calc_hash – True - A sha1 hash is calculated over the data section of iTree and added in the header False - no hash will be calculated

Returns

string containing the serialized data

dump(o, file_path, pack=True, calc_hash=True, overwrite=False)[source]

Serialize iTree object into a file

Parameters

o – iTree object to be serialized
file_path – target file path where to store the data in
pack – True - gzip the data, False - do not zip
overwrite – True - an existing fie will be overwritten False (default) - in case the file exists an FileExistsError Exception will be raised
calc_hash – True - A sha1 hash is calculated over the data section of iTree and added in the header False - no hash will be calculated

Returns

None

loads(source_str, check_hash=True, load_links=True, _source=None)[source]

create an iTree object by loading from a string.

Parameters

source_str – source string that contains the iTree information
check_hash – True the hash of the file will be checked and the loading will be stopped if it doesn’t match False - do not check the iTree hash
load_links – True - linked iTree objects will be loaded
_source – Path of a loaded source file (for internal use)

Returns

iTree object loaded from file

load(file_path, check_hash=True, load_links=True)[source]

create an iTree object by loading from a file

Parameters

file_path – file path to the file that contains the iTree information
check_hash – True the hash of the file will be checked and the loading will be stopped if it doesn’t match False - do not check the iTree hash
load_links – True - linked iTree objects will be loaded

Returns

iTree object loaded from file

class itertree.itree_serialize.iTStdRenderer[source]

Bases: object

Standard renderer fr the iTree object for creating a very simple pretty print output

render2(itree_object, item_filter=None, _level=0)[source]

prints a pretty output of the iTree object

Parameters

itree_object – iTree object to be converted
item_filter – item filter method or filter-constant to filter specific items out
_level – internal parameter for recursive calls (do not use)

Returns

string containing the pretty print aoutput

renders2(itree_object, item_filter=None, _level=0)[source]

creates a pretty print string from iTree object This is the recursive version which might be a bit quicker

Parameters

itree_object – iTree object to be converted
item_filter – item filter method or filter-constant to filter specific items out
_level – internal parameter for recursive calls (do not use)

Returns

string containing the pretty print aoutput

render(itree_object, item_filter=None)[source]

creates a pretty print from iTree object and prints it stdout

Note:: Filtered renderings contains always the root object and the added children might have: confusing indentation levels because the parent elements might be filtered out

Parameters

itree_object – iTree object to be converted
item_filter – item filter method or filter-constant to filter specific items out Note:: The root of the object is not filtered and always in the outputs first line

Returns

renders(itree_object, item_filter=None)[source]

creates a pretty print string from iTree object ad returns it in a string

Note:: Filtered renderings contains always the root object and the added children might have: confusing indentation levels because the parent elements might be filtered out

Parameters

itree_object – iTree object to be converted
item_filter – item filter method or filter-constant to filter specific items out Note:: The root of the object is not filtered and always in the outputs first line

Returns

string containing the pretty print output

itertree helper classes

This code is taken from the itertree package: https://pypi.org/project/itertree/ GIT Home: https://github.com/BR1py/itertree The documentation can be found here: https://itertree.readthedocs.io/en/latest/index.html

The code is published under MIT license:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

For more information see: https://en.wikipedia.org/wiki/MIT_License

This part of code contains helper classes used in DataTree object

itertree.itree_helpers.accu_iterator(iterable, accu_method, initial_value=(None,))[source]: A method that enables itertools accumulation over a method .. note:: This method is just needed because in python <3.8 itertools accumulation has no initial parameter! :param iterable: iterable :param accu_method: accumulation method (will be fet by two parameters cumulated and new item) :return: accumulated iterator

itertree.itree_helpers.is_iterator_empty(iterator)[source]: checks if the given iterator is empty :param iterator: iterator to be checked :return: tuple (True,iterator) - empty

(False, iterator) - item inside

class itertree.itree_helpers.iTInterval(lower_limit='inf', upper_limit='inf', lower_open=True, upper_open=True, not_in=False, pre_interval=None, pre_and=False, str_def=None)[source]

Bases: object

helper class that defines an interval for range definitions in Data Models or Filters

the class contains a check if a given value is in the defined interval or not

The class might be a little bit under estimated in all the itertree functionalities but its a short but very powerful implementation of an Interval class for python.

The class contains anything you might need in case of a Interval functionality. You can given open/closed interval definitions including infinite limits. The intervals can be combined to a mathematical set via the pre_interval parameter. And the check method allows to give other limits as defined. This is especially useful for dynamically calculated limits.

The interval definition is also possible via a mathematical string like: “(1,2)” or “[10,+inf)”.

If you need a more advanced implementation you might have a look on the intervals/portion python package.

Note

For equal just set upper_limit to None (upper_open, lower_open parameter will be ignored in this case)

INF = 'inf'

property is_equal

check(value, use_limits=None, return_iterator=False)[source]

main check function :param value: value to be check if in interval or not (you might give iterables too! :param use_limits: You can replace the static limits in the interval with dynamic ones given in the check, any

nested iterable can be used here (do not use iterators!). None - use static limit (lower,_limit, upper_limit) - replace limits in highest level interval if lower_limit or

upper_limit is None the static one is used

(((lower_limit_l2,upper_limit_l2),(lower_limit_l1,upper_limit_l1)),(lower_limit_l0,upper_limit_l0)) - use nested tuples to give replacement limits to deeper levels (use None for using static ones)

Returns: True/False or iterator over single value check use any() to get a summary!

math_repr()[source]: mathematical string representation of the interval :return: string

from_str(interval_str)[source]: create the interval from a math representation string .. note:: Give inf for infinity :param interval_str: math string representation :return:

class itertree.itree_helpers.iTLink(file_path=None, key_path=None, link_item=None)[source]

Bases: object

Definition of a link to an element in another DataTree

property loaded

property is_loaded

property link_item

property file_path

property key_path

property is_iTLink

property link_tag

property link_data

property source_path

set_source_path(path)[source]

set_loaded(tag=None, data=None)[source]

dict_repr()[source]

class itertree.itree_helpers.iTMatch(pattern, combine_or=True)[source]

Bases: object

The match object is used to defined match to elements in the DtaTree used in iterations over the DataTree The defined iMatch object can be used for checks against iTree objects (mainly for checks against the tag and also for string matches e.g. for finding iTree.data.keys() or .values() in filters.

property is_iTMatch

check(item, item_filter=None)[source]

class itertree.itree_helpers.TagIdx(tag, idx)

Bases: tuple

idx: Alias for field number 1

tag: Alias for field number 0

class itertree.itree_helpers.TagIdxStr(tag_idx_str, tag_separator='#')[source]

Bases: TagIdx

Define a TagIdx by a sting with an index separator (default=’#’)

Example: “mytag#1” will be translated in the TagIdx(“mytag”,1)

Note

This makes only sense and can only be used if the tag is a string (not for other objects)

Parameters: tag_idx_str – string containing the definition

property is_TagIdxStr

class itertree.itree_helpers.TagIdxBytes(tag_idx_bytes, tag_separator=b'#')[source]

Bases: TagIdxStr

Define a TagIdx by bytes with an index separator (default=b’#’)

Example: b”mytag#1” will be translated in the TagIdx(b”mytag”,1)

Note

This makes only sense and can only be used if the tag is a byte (not for other objects)

Parameters: tag_idx_bytes – bytes containing the definition

property is_TagIdxBytes

class itertree.itree_helpers.TagMultiIdx(tag, idxs)[source]

Bases: TagIdx

Define a TagMultiIdx

Parameters

tag – item tag (can be any hashable object)
idxs –
This parameter can be: list of integer indexes any iterable or iterator containing index integers

slice object

property is_TagMultiIdx

itertree package

Indices and tables

Modules

The main itertree class

itertree data classes

itertree filter classes

itertree serializing

itertree helper classes

Subpackages