API

Mixins

class abstracttree.mixins.BinaryDownTree[source]

Bases: DownTree

Binary-tree with links to children.

property children: Sequence[TNode]: Children of this node.

property descendants: View of descendants of this node.

property nodes: View of this node and its descendants.

class abstracttree.mixins.BinaryTree[source]

Bases: BinaryDownTree, Tree

Binary-tree with links to children and to parent.

class abstracttree.mixins.DownTree[source]

Bases: AbstractTree

Abstract class for tree classes with children but no parent.

abstract property children: Collection[TNode]: Children of this node.

property descendants: View of descendants of this node.

property is_leaf: bool: Whether this node is a leaf (does not have children).

property leaves: View of leaves from this node.

property levels: View of this node and descendants by level.

property nodes: View of this node and its descendants.

transform(f: Callable[[TNode], TMutDownNode], keep=None) → TMutDownNode[source]: Create new tree where each node of self is transformed by f.

class abstracttree.mixins.MutableDownTree[source]

Bases: DownTree

Abstract class for mutable tree with children.

abstract add_child(node: TNode)[source]: Add node to children.

add_children(children: Iterable[TNode])[source]: Add multiple nodes to children.

abstract remove_child(node: TNode)[source]: Remove node from children.

class abstracttree.mixins.MutableTree[source]

Bases: Tree, MutableDownTree

Abstract class for mutable tree with children and parent.

detach() → TNode[source]: Remove parent if any and return self.

class abstracttree.mixins.Tree[source]

Bases: UpTree, DownTree

Abstract class for tree classes with access to children and parents.

property siblings: View of siblings of this node.

Generics

class abstracttree.generics.DownTreeLike[source]

Bases: object

Any object that has an identifiable parent and/or identifiable children.

class abstracttree.generics.MappingItem(key, value)

Bases: tuple

key: Alias for field number 0

value: Alias for field number 1

class abstracttree.generics.TreeLike[source]

Bases: object

Any object that has an identifiable parent.

abstracttree.generics.children(tree: DT) → Collection[DT][source]
abstracttree.generics.children(coll: Collection)
abstracttree.generics.children(tree: DT) → Collection[DT]
abstracttree.generics.children(tree: DT) → Collection[DT]
abstracttree.generics.children(tree: DT) → Collection[DT]
abstracttree.generics.children(cls: type)
abstracttree.generics.children(pth: Path | Path)
abstracttree.generics.children(pth: Path | Path)
abstracttree.generics.children(node: AST)
abstracttree.generics.children(group: Exception)
abstracttree.generics.children(element: Element): Returns children of any downtreelike-object.

abstracttree.generics.label(node: object) → str[source]

abstracttree.generics.label(coll: Collection)

abstracttree.generics.label(cls: type)

abstracttree.generics.label(pth: Path | Path)

abstracttree.generics.label(pth: PathLike)

abstracttree.generics.label(node: AST)

abstracttree.generics.label(group: Exception)

abstracttree.generics.label(element: Element)

Return a string representation of this node.

This representation should always represent just the Node. If the node has parents or children these should be omitted.

abstracttree.generics.nid(node: Any)[source]

abstracttree.generics.nid(pth: PathLike)

Unique idenitifier for node.

Usually the same as id, but can be overwritten for classes that act as delegates.

abstracttree.generics.parent(tree: T) → T | None[source]
abstracttree.generics.parent(pth: Path | Path)
abstracttree.generics.parent(pth: Path | Path): Returns parent of any treelike-object.

abstracttree.generics.parents(tree: T) → Sequence[T][source]
abstracttree.generics.parents(cls: type): Like parent(tree) but return value as a sequence.

abstracttree.generics.root(node: T) → T[source]
abstracttree.generics.root(_: type) → type
abstracttree.generics.root(pth: Path | Path)
abstracttree.generics.root(pth: Path | Path): Find the root of a node in a tree.

Export

class abstracttree.export.LiteralText[source]: Bases: str

abstracttree.export.plot_tree(tree: ~abstracttree.generics.DownTreeLike, ax=None, formatter: ~collections.abc.Callable[[~abstracttree.generics.DownTreeLike], str] | str = <function label>, keep=MaxDepth(depth=5), annotate_args=None)[source]: Plot the tree using matplotlib (if installed).

abstracttree.export.print_tree(tree, formatter=<function label>, *, style: str | ~abstracttree.export.Style = None, keep=None)[source]: Print this tree. Shortcut for print(to_string(tree)).

abstracttree.export.to_dot(tree: ~abstracttree.generics.DownTreeLike, file=None, keep=MaxDepth(depth=5), node_name: str | ~collections.abc.Callable[[~abstracttree.export.TNode], str] | None = None, node_label: str | ~collections.abc.Callable[[~abstracttree.export.TNode], str] | None = <function label>, node_shape: str | tuple[str, str] | ~collections.abc.Callable[[~abstracttree.export.TNode], str | tuple[str, str]] = None, node_attributes: ~collections.abc.Mapping[str, ~typing.Any] | ~collections.abc.Callable[[~abstracttree.export.TNode], ~collections.abc.Mapping[str, ~typing.Any]] = None, edge_attributes: ~collections.abc.Mapping[str, ~typing.Any] | ~collections.abc.Callable[[~abstracttree.export.TNode, ~abstracttree.export.TNode], ~collections.abc.Mapping[str, ~typing.Any]] = None, graph_attributes: ~collections.abc.Mapping[str, ~typing.Any] = None)[source]: Export to graphviz.

abstracttree.export.to_image(tree: DownTreeLike, file=None, how='dot', *args, **kwargs)[source]

Export to image. Uses graphviz(dot) or mermaid.

If file is str or Path, save file under given name. If file is None (default), return image as bytes. If file is writable (binary), write to it.

abstracttree.export.to_latex(tree: ~abstracttree.generics.DownTreeLike, file=None, keep=MaxDepth(depth=5), node_label: str | ~collections.abc.Callable[[~abstracttree.export.TNode], str] | None = <function label>, node_shape: str | tuple[str, str] | ~collections.abc.Callable[[~abstracttree.export.TNode], str | tuple[str, str]] = None, leaf_distance: str | None = '2em', level_distance: str | None = None, node_options: ~collections.abc.Iterable[str | ~collections.abc.Callable[[~abstracttree.export.TNode], str]] = (), picture_options: ~collections.abc.Iterable[str | ~collections.abc.Callable[[~abstracttree.export.TNode], str]] = (), graph_direction: str = 'right', indent: str | int = 4, align='center')[source]

Export to latex (experimental).

Make sure to put \usepackage{tikz} in your preamble. Does not wrap output in a figure environment.

abstracttree.export.to_mermaid(tree: ~abstracttree.generics.DownTreeLike, file=None, keep=MaxDepth(depth=5), node_name: str | ~collections.abc.Callable[[~abstracttree.export.TNode], str] | None = None, node_label: str | ~collections.abc.Callable[[~abstracttree.export.TNode], str] | None = <function label>, node_shape: str | tuple[str, str] | ~collections.abc.Callable[[~abstracttree.export.TNode], str | tuple[str, str]] = 'box', edge_arrow: str | ~collections.abc.Callable[[~abstracttree.export.TNode, ~abstracttree.export.TNode], str] = '-->', graph_direction: str = 'TD')[source]: Export to mermaid.

abstracttree.export.to_pillow(tree: DownTreeLike, **kwargs)[source]: Convert tree to pillow-format (uses graphviz on the background).

abstracttree.export.to_reportlab(tree: DownTreeLike, **kwargs)[source]: Convert tree to drawing for use with reportlab package.

abstracttree.export.to_string(tree: ~abstracttree.generics.DownTreeLike, formatter: ~collections.abc.Callable[[object], str] | str | None = <function label>, *, file=None, style: str | ~abstracttree.export.Style = 'square', keep=None)[source]: Converts tree to a string in a pretty format.

Predicates

class abstracttree.predicates.MaxDepth(depth: int)[source]

Bases: Predicate

Limit iteration to a certain depth

Can be passed to keep argument of methods such as tree.iter_tree(). >>> from littletree import Node >>> tree = Node(identifier=’root’).path.create([‘a’, ‘b’, ‘c’, ‘d’]).root >>> [node.identifier for node in tree.nodes.preorder(keep=MaxDepth(3))] [‘root’, ‘a’, ‘b’, ‘c’]

class abstracttree.predicates.Predicate[source]: Bases: Callable[[T, NodeItem], bool]

class abstracttree.predicates.PredicateIntersection(*preds)[source]: Bases: Predicate

class abstracttree.predicates.PredicateUnion(*preds)[source]: Bases: Predicate

class abstracttree.predicates.PreventCycles[source]

Bases: Predicate

Prevent looping cyclic trees.

It might yield nodes more than once, but will not repeat children. This is mostly useful when trying to plot cyclic trees.

class abstracttree.predicates.RemoveDuplicates[source]

Bases: Predicate

Remove duplicates in case of cycles or multiparent trees.

Adapters

class abstracttree.adapters.HeapTree(heap: MutableSequence[D] = None, index: int = 0)[source]

Bases: BinaryTree

Provides a tree interface to a heap.

Mainly useful for visualisation purposes. >>> from abstracttree import print_tree >>> import heapq >>> tree = HeapTree() >>> for n in range(5, 0, -1): >>> heapq.heappush(tree.heap, n) >>> print_tree(tree) 0 → 1 ├─ 1 → 2 │ ├─ 3 → 5 │ └─ 4 → 4 └─ 2 → 3

property children: Collection[HeapTree]: Children of this node.

property nid: Unique number that represents this node.

property parent: HeapTree | None: Parent of this node or None if root.

class abstracttree.adapters.TreeAdapter(value: TreeLike, _parent=None)[source]

Bases: Tree

static child_func(tree: DT) → Collection[DT]: Returns children of any downtreelike-object.

property children: Sequence[T]: Children of this node.

static label_func(node: object) → str

Return a string representation of this node.

This representation should always represent just the Node. If the node has parents or children these should be omitted.

property nid: int: Unique number that represents this node.

property parent: T | None: Parent of this node or None if root.

static parent_func(tree: T) → T | None: Returns parent of any treelike-object.

abstracttree.adapters.as_tree(obj: T, children: Callable[[T], Iterable[T]] = None, parent: Callable[[T], T | None] = None, label: Callable[[T], str] = None) → TreeAdapter[source]

Convert any object to a tree.

Functions can be passed to control how the conversion should be done. The original object can be accessed by using the value attribute.

abstracttree.adapters.convert_tree(tree: DownTreeLike, required_type=typing.Type[~T]) → T[source]

Convert a TreeLike to a powerful Tree.

If needed, it uses a TreeAdapter.

Route

class abstracttree.route.Route(*anchors: T)[source]

Bases: Iterable[T]

Representation of a route trough adjacent nodes in the tree.

Two nodes are adjacent if they have a parent-child relationship. The route will be as short as possible, but it will visit the anchor points in order.

add_anchor(anchor: T)[source]

Add a node to the route.

The node should belong to the same tree as any existing anchor nodes.

property anchors: Collection[T]: View of the anchor nodes.

count() → int: How many nodes are on route?

property edges: View of all edges that make up the route.

property lca: T | None: Find node that is the common ancestor of nodes on path.

property nodes: View of all nodes that make up the route.

Utils

abstracttree.utils.eqv(n1: DT, n2: DT) → bool[source]

Whether two nodes are equivalent.

For nodes to be equivalent, they need to have the same nid and be of the same type. The result is almost the same as n1 is n2, but can be overridden for adapters, symlinks etc.