package¶

Augmented tree items¶

Abstract Base Classes¶

class augmentedtree.AnAugmentedTreeItem¶

Bases: abc.ABC

It is mandatory to implement this abstract basic class for any kind of augmented tree item. This class defines the minimal, necessary set of properties and methods for a tree item within a two column tree view (like it is presented using print_atree).

class augmentedtree.AnAugmentedCollection¶

Bases: augmentedtree.abstractbaseclasses.AnAugmentedTreeItem

In addition to AnAugmentedTreeItem a tree item resembling a sequence or mapping has to implement __getitem__, __setitem__ and outervalues.

Base tree item classes¶

class augmentedtree.ATreeItem(real_key=None, **kwargs)¶

Bases: augmentedtree.abstractbaseclasses.AnAugmentedTreeItem

ATreeItem set the entry point for subclassing AnAugmentedTreeItem for usage with augment_datastructure. It also implements properties and methods for convenience. Properties and methods which has to be overwritten will raise NotImplementedErrors.

Raises:	`TypeError` – This class cannot be instantiated directly. It has to be sub-classed.

children¶

Access to the children (tree items) this tree item possess. Also obligatory for a brasic QT implementation.

Returns:	Sequence Sequence of AnAugmentedTreeItem

has_primekey(key: Union[int, str]) → bool¶

Returns it the tree item has a child with the requested key. Basic implementation for QT, where it’s called hasKey().

Parameters:	key (Union[int, str]) – Requested key.
Returns:	bool

primekey¶

Represents the key this tree item is associated within its parent container. Also it is the first columns (left) value within a 2-column view (like when using print_atree()).

Returns:	Union[int, str]

primename¶

Represents the value this tree item is associated with. Also it is the second columns (right) value within a 2-column view (like when using print_atree()).

Returns:	Any

primevalue¶

The ‘real’ value/nested data this tree item is representing.

Returns:	Any

real_key¶

The real key within the nested data.

Returns:	Union[int, str]

class augmentedtree.ACollectionTreeItem(primarykey: Union[augmentedtree.core.KeyLink, str, int] = None, primaryname: Union[augmentedtree.core.KeyLink, str, int] = None, primaryvalue: Union[Sequence[T_co], collections.abc.Mapping] = None, real_key: str = None, **kwargs)¶

Bases: augmentedtree.abstractbaseclasses.AnAugmentedCollection, augmentedtree.treeitems.ATreeItem

outervalues¶

Returns this tree items origin nested data, which is considered to represent this tree items values. These doesn’t need to be identical to primevalue, but primevalue always contains the values visible to the outside.

Returns:	Any

Tree item classes¶

class augmentedtree.ValueTreeItem(primarykey=None, **metadata)¶: Bases: augmentedtree.treeitems.ATreeItem

class augmentedtree.SequenceTreeItem(primarykey=None, primaryname=None, primaryvalue=None, real_key=None, **kwargs)¶: Bases: collections.abc.MutableSequence, augmentedtree.treeitems.ACollectionTreeItem

class augmentedtree.MappingTreeItem(primarykey=None, primaryname=None, primaryvalue=None, outervaluekey=None, metadatakeys=None, real_key=None, field_types: Dict[str, Callable] = None, meta_attributes=None, keypairs: dict = None)¶: Bases: collections.abc.Mapping, augmentedtree.treeitems.ACollectionTreeItem

class augmentedtree.AugmentedTree(data: Union[augmentedtree.abstractbaseclasses.AnAugmentedCollection, Mapping[KT, VT_co], Sequence[T_co]], use_schemas: bool = True, pathmap: augmentedtree.treeitemselection.PathMap = None)¶

Bases: augmentedtree.abstractbaseclasses.AnAugmentedTreeItem

This class is the recommended entry for augmenting nested data.

Parameters:	data (Union[Mapping, Sequence]) – Augments this given data. use_schemas (bool) – As default registered schemas are used. If turned to false this tree will represent the pure data structure.

augmentedtree.augment_datastructure(nested_data: Union[Sequence[T_co], Mapping[KT, VT_co]], parent: augmentedtree.abstractbaseclasses.AnAugmentedCollection = None, augmentclasses: Dict[str, augmentedtree.abstractbaseclasses.AnAugmentedTreeItem] = None, use_schemas: bool = True)¶

Augments nested data with AnAugmentedTreeItem.

Parameters:

nested_data (Union[Sequence, Mapping]) – nested data to be augmented with AnAugmentedTreeItem.
parent (AnAugmentedCollection, optional) – parent of the given nested_data
augmentclasses (Dict[str, AnAugmentedTreeItem], optional) – AnAugmentedTreeItem-classes to be used for augmentation
use_schemas (bool, optional) – Defines whether schemas should be used or not. Default = True; schemas are used.

Returns:

AnAugmentedTreeItem

augmentedtree.print_atree(treeitem: augmentedtree.abstractbaseclasses.AnAugmentedTreeItem, additional_columns: List[T] = None, show_hidden=False, indent=' ', prefix='')¶

Pretty prints a tree in a simple manner.

Notes

if the item is within a Sequence the separator between primekey and primename will be a dot ‘.’; else a colon ‘:’
by using schemas the default indexing by integers of Sequences can be changed to key-names of a Mapping.

Parameters:	treeitem (AnAugmentedTreeItem) – Tree item to be printed. additional_columns (str) – Additional columns which should be shown. show_hidden (bool) – If True leading underline keys will be shown. Default = False indent (str) – Indentation characters which will be used. prefix (str) – Additional string with which line begins.

class augmentedtree.LeafType¶: An enumeration.

Selecting values¶

By default the methods select() and where() of AugmentedTree and AugmentedItemSelection interprets any given path component as an UNIX file pattern. To use regular expressions instead, these path components can be wrapped with RegularExpressionPart.

class augmentedtree.RegularExpressionPart¶

class augmentedtree.AugmentedItemSelection(data: Union[augmentedtree.abstractbaseclasses.AnAugmentedCollection, Mapping[KT, VT_co], Sequence[T_co]], use_schemas: bool = True, pathmap: Optional[augmentedtree.treeitemselection.PathMap] = None)¶: Bases: augmentedtree.tree.AugmentedTree

Enhancement of Mappings by schemas¶

augmentedtree.use_mappingtree_schema(schema: Dict[KT, VT], override_existing: bool = False)¶

Registers a (JSON-)schema for a MappingTreeItem for global use.

Raises:	`ValueError` – If a schema with the same identifier is already registered.
Parameters:	schema (Dict) – (JSON-)schema to be registered. override_existing (bool) – If True and existing registered schema with the same id will be overridden.

augmentedtree.use_mappingtree_schemas(*schemas, override_existing: bool = False)¶

Registers (JSON-)schemas for a MappingTreeItem for global use.

Raises:	`ValueError` – If a schema with the same identifier is already registered.
Parameters:	schemas (List[Dict]) – (JSON-)schemas to be registered. override_existing (bool) – If True and existing registered schema with the same id will be overridden.

class augmentedtree.MappingSchema¶

PRIMARYKEY = 'atree_primekey'¶: Defines the field from which value should be used as primekey of the MappingTreeItem.

PRIMARYNAME = 'atree_primename'¶: Defines the field from which value should be used as primename of the MappingTreeItem.

OUTERVALUES = 'atree_outervalues'¶: Defines the field from which value should be used as primename of the MappingTreeItem.

METAFIELDKEYS = 'atree_metafieldkeys'¶: Defines the keys of a Mapping item which should be treated as ‘metadata’ of this item. ‘metadata’ is hidden within the augmented default view.

IDENTIFIER = 'atree_mappingschema'¶

This field defines the unique schema identifier by an tuple of (key, value), which has to be found within the Mapping item.

Optionally if the field only contains a string, it is assumed the Mapping item contains this MappingTree.SCHEMA_IDENTIFIER as a key of an value with a unique name.

META_ATTRIBUTES = 'atree.meta_attributes'¶

class augmentedtree.MappingSchemaBuilder¶

static construct(identifier: Union[str, Tuple[str, str]], primarykey: Optional[str] = None, primaryname: Optional[str] = None, outervalues_key: Optional[str] = None, metafieldkeys: Optional[List[str]] = None, additional_metafieldkeys: Optional[List[str]] = None, meta_attributes: Optional[List[str]] = None) → dict¶

Construct a schema for MappingTreeItems.

Notes

If identifier is a single string the mapping to be used by this schema needs a field with the key MappingSchema.IDENTIFIER.
A mapping item can use outervalues or metafieldkeys therefore outervalues_key always suppress metafieldkeys and additional_metafieldkeys.
The identifiers resulting key, primarykey and primaryname are default metafieldkeys if supplied. The metafieldkeys overrides the default behavior.
With additional_metafieldkeys additional keys can be defined.

Parameters:	identifier (Union[str, Tuple[str, str]]) – A single string or a tuple/list with 2 strings defines an identifier. primarykey (Optional[str]) – Defines which key of the mapping should be used as the tree items primekey. primaryname (Optional[str]) – Defines which key of the mapping should be used as the tree items primename. outervalues_key (Optional[str]) – Defines the key, which contains the tree items children/values resulting in a ‘nested-mapping’ tree item. metafieldkeys (Optional[List[str]]) – Defines the keys, which will be considered as metadata. All other entries within the mapping will be considered as a child/value. additional_metafieldkeys – Additional keys to metafieldkeys. meta_attributes (Optional[List[str]]) – Defines which values will be used as meta attributes for selection via the where method.
Returns:	A schema for MappingTreeItem(s).
Return type:	dict

Tree path related¶

class augmentedtree.core.TreePath(real_path: Union[str, List[str]] = '', augmented_path: Union[str, List[str]] = '', meta_attributes: List[T] = None)¶

join(real_path: Union[str, List[str]] = '', augmented_path: Union[str, List[str]] = '', meta_attributes: List[T] = None) → augmentedtree.core.TreePath¶

Joins the path parts and returns a new AugmentedTreePath.

Notes

If parameter treepath is given, all parameters are overriden by it.

Parameters:	real_path (Union[str, List[str]]) – Real path within the nested data structure of the augmented tree items. augmented_path (Union[str, List[str]]) – Path defined by the augmentation; if no schemas are used identical to real_path meta_attributes (List) – Associations of this path part.
Returns:	Path within augmented tree.
Return type:	TreePath

augmentedtree.core.normalize_path_of_tree(*treepath)¶

Normalized a path (str) or parts of a path (List[str]) to ‘/a/path/like/this’.

Parameters:	*treepath – A single tree path part or multiple tree path parts.
Returns:	Normalized path ‘/like/this/example’.
Return type:	str

>>> normalize_path_of_tree("//to/many/delimiters///everywhere//")
'/to/many/delimiters/everywhere'
>>> normalize_path_of_tree("missing/front/delimiter")
'/missing/front/delimiter'
>>> normalize_path_of_tree("/this/path/is/correct")
'/this/path/is/correct'
>>> normalize_path_of_tree("/unwanted/delimiter/at/the/end/")
'/unwanted/delimiter/at/the/end'
>>> normalize_path_of_tree(None)
''
>>> normalize_path_of_tree([])
''

>>> normalize_path_of_tree("//to", "/many/delimiters//", "/everywhere//")
'/to/many/delimiters/everywhere'
>>> normalize_path_of_tree("missing", "front/delimiter")
'/missing/front/delimiter'
>>> normalize_path_of_tree("this", "path", "is/correct")
'/this/path/is/correct'
>>> normalize_path_of_tree("unwanted", "delimiter", "at/the/end/")
'/unwanted/delimiter/at/the/end'
>>> normalize_path_of_tree("invalid", "type", [], "within/the/path")
'/invalid/type/within/the/path'
>>> normalize_path_of_tree(None)
''
>>> normalize_path_of_tree([])
''