Tutorial

Status and compatibility information

The original implementation is done in python 3.5 and it is tested under python 3.5 and 3.9. It should work in all python 3 environments.

The actual development status is Beta. The planned featureset is implemented. Work effort goes in the moment in testing, bugfixing and the creation of the documentation.

Using the itertree package

To understand the full functionality of itertree the user should have a look on the related examples which can be found in the example folder of itertree.

In this chapter we try to dive in the functions of itertree in a clear structured way. The user might look in the class description of the modules too. But the huge number of methods in the iTree class might be very confusing. And we hope this chapter orders the things in a much better way.

Construction of an itertree

The first step in the construction of a itertree is to instance the The main itertree class.

Instance the iTree object:

>>>item1=iTree('item1') # itertree item with the tag 'item1'
>>>item2=iTree('item2', data={'mykey':1}) # instance a iTree-object with data content (defined as a dict)
>>>item3=iTreeTemporary('temp_item') # instance a temporary iTree-object
>>>item4=iTreeLink('linked_item', data={'mykey':2}, link_file_path='dt.itz',link_key_path=iTreeTagIdx(child',0),load_links=True) # instance a iTree-object containing a link

iTreeTemporary objects can filtered out and when dumping the whole iTree into a file the iTreeTemporary items will be ignored.

In case a link is set by using the iTreeLink class will integrate the childs of the linked iTree-objects as it’s own childs into the tree. The iTree object can have own properties like temporary or own data. But it cannot contain own children. Operations that try to manipulate the children structure will fail in this case.

To add or manipulate the children of an item we have several possibilities. The following direct operations are recommended for structural manipulations in the tree:

>>>root=iTree('root')
>>>root.append(iTree('child')) # append a child
>>>root[0]=iTree('newchild') # replace the child with index 0
>>>del root[iTreeTagIdx('newchild',0)] # deletes the child with matching iTreeTagIdx

Additionally a huge set of methods is available for structural manipulations related to the children of a item.

The addition of iTrees is possible the result contains always the properties of the first added item and the children of the second added item are appended by creating a copy.

>>> a=iTree('a',data={'mykey':1},subtree=[iTree('a1'),iTree('a2')])
>>> b=iTree('b',subtree=[iTree('b1'),iTree('b2')])
>>> c=a+b
>>> c
iTree("'a'", data="{'mykey': 1}", subtree=[iTree("'a1'"), iTree("'a2'"), iTree("'b1'"), iTree("'b2'")])

Multiplication of a iTree is possible too the result is a list of iTree copies of the original one.

itree_list=iTree('a')*1000 # creates a list of 1000 copies of the original iTree
>>> root=iTree('root')
>>> root.extend(itree_list) # we can extend an existing iTree with the list (add 1000 identical children)
True

item access

The items in the iTree can be accessed via __getitem__() method:

The TagIdx class is used to address items that contains the same tag. The second argument of the TagIdx is the index that the item has in the related tag-family. But we can also give multiple indexes or a slice. As the given example shows is the result of not unique targets always an iterator object.

iTree other structure related commands

iTree compare items

Because the __eq__() method (== opertor) is internally used for same item object findings we really compare here based on the python object id. Therefore for the comparison of two non identical objects the equal() method should be used.

Based on the iTree length the comparison operators <; <=; >; >= are available too.

iTree properties

As we will see later on some properties of the iTree object can be modified by the related methods. Warning:: The user should NEVER modify any of the given properties directly. Especially the not discussed private properties (marked with the beginning underline). Direct modifications will normally lead into inconsistencies of the iTree object!

The iTree object contains the following general properties:

Item identification properties:

As shown in the last example hashable objects can be used as tags for the itertree items to be stored in the iTree object. Even for those kind of tag objects it is possible to store multiple items with the same tag. In the example the enumeration inside the tag family can be seen in the index enumeration in the TagIdx object.

Beside those structural properties the iTree objects contains some more properties that might be modified by the related methods.

Different than the data the coupled_obj is just a pointer to another python object. E.g. by this you might couple the iTree to a graphical user interface object e.g. an item in a hypertreelist or it can be used to couple the itree object to an item in a mapping dictionary. The property couple_obj is not managed by the iTree object it’s just a place to store the information. In file exports or string exports this information will not be considered.

iTree data related methods

This is the data property. The property contains the iData objects which behaves in general like a dict. But there are two execpetions that must be considered: * The (__NOKEY__) key is an implizit key that will be used in case the user gives only one value (no_key) to the d_set() method. Then the given parameter will be stored in the (__NOKEY__) item of the dict. * In case a dict item contains a iDataModel object the given value in iTree.d_set() will be checked against the data model.

To manipulate data you can use the functions of the iTree.data object or can use the quick access functions in iTree object ( methods related to data access have all the prefix “d_” ):

Do not replace the iTree.data object with another object (iTree.data is just a property which is linking into the internal structure). You will destroy a part of the functionality, use iTree.data.clear() and iTree.data.update() instead.

iTree iterators and queries

The standard iterator for iTrees delivers all children beside this we have same special iterators that contain filter possibilities.

Beside the classical iterators we have the more query related find methods:

For filter creation we have some helper classes (itree_filter.py)

Depending on the data stored in the iTree.data object the user might create own filters. In general just a method must be created that takes the item as an argument and that delivers True in case of athe match and False in case of no match. We have also a base class (super-class) of the given filters available which might be used for own filters too.

The fitering in iTree is very effective and quick. As an example one might execute the example script itree_usage_example1.py where the itertree.Filter.iTFilterData object is used.

iTree formatted output

iTree file storage

The file storage methods and the rendering methods are initialized by:

This method is implizit executed and set to the default serializing functions of itertree. The user might load his own functionalities explicit by using this method or he might overload the iTree class and the init_serializer() method with his own functionality.

iTree helpers classes

In the itertree helper module we have some helper classes that can be used to construct specific iTree objects.

We have the following helper classes available:

The other classes in itree_helpers are used internally in the iTree object and might be less interesting for the user.

Addinionally the user might have also a look in the the othe itertree modules like itertree_data.py or itertree_filter.py. Especially the class iTDataModel might be a good starting point for own data model definitions as it is also shown in examples/itertree_data_model.py.