polymerist.genutils.trees

Generic functionality for tree-like data structures. Based on the anytree module (https://github.com/c0fec0de/anytree)

Submodules

• polymerist.genutils.trees.treebase
• polymerist.genutils.trees.treecopy
• polymerist.genutils.trees.treeviz

Exceptions

MissingPrerequisitePackage

Raised when a package dependency cannot be found and the user should be alerted with install instructions

Classes

NodeCorrespondence

Abstract base for implementing how to build an anytree Node tree for an arbitrary class

Functions

modules_installed(→ bool)	Check whether one or more modules are all present
compile_tree_factory(→ Callable[[T, Optional[int], ...)	Factory method for producing a tree-generating function from a NodeCorrespondence
get_node_attrs(→ dict[str, Any])	Return a dict of all attributes set on a Node
copy_tree(→ anytree.node.Node)	Create a copy of an anytree Node hierarchy. Can provide filters and stop criteria to exclude nodes or whole branches
tree_to_networkx(→ anytree.node.Node)	Produces a networkx.DiGraph representation on an anytree Tree
treestr(, childiter, Iterable[anytree.Node]] = list, ...)	Return a printable string representation of a tree from a root Node, reminiscent of GNU tree

Package Contents

polymerist.genutils.trees.modules_installed(*module_names: list[str]) → bool

Check whether one or more modules are all present Will only return true if ALL specified modules are found

Parameters:

module_names (**str*) – Any number of module names, passed as a comma-separated sequence of strings

Returns:

all_modules_found – Whether or not all modules were found to be installed in the current working environment

Return type:

bool

exception polymerist.genutils.trees.MissingPrerequisitePackage(importing_package_name: str, use_case: str, install_link: str, dependency_name: str, dependency_name_formal: str | None = None)

Bases: Exception

Raised when a package dependency cannot be found and the user should be alerted with install instructions

class polymerist.genutils.trees.NodeCorrespondence

Bases: abc.ABC, Generic[T]

Abstract base for implementing how to build an anytree Node tree for an arbitrary class

abstractmethod name(obj: T) → str

Define how to obtain a string name

abstractmethod has_children(obj: T) → bool

Define how to check if an object can produce children in the first place before attempting to do so

abstractmethod children(obj: T) → Iterable[T] | None

Define how to obtain node children from an instance Should return NoneType if the instance is “leaf-like”

polymerist.genutils.trees.compile_tree_factory(node_corresp: NodeCorrespondence[T], class_alias: str | None = None, obj_attr_name: str | None = None, exclude_mixin: polymerist.genutils.filters.Filter[T] | None = None) → Callable[[T, int | None, polymerist.genutils.filters.Filter[T] | None], anytree.node.Node]

Factory method for producing a tree-generating function from a NodeCorrespondence

Parameters:

• node_corresp (NodeCorrespondence[T]) – Definition of a correpondence between an arbitrary type and a Tree Node

• class_alias (str (optional)) – Name of the corresponding class to inject into docstring If not provided, will default to the __name__ of the class wrapped by node_corresp

• obj_attr_name (str (optional)) – The name of the Node attribute to which a copy of the class instance should be bound If not provided, will default to the value of class_alias

• exclude_mixin (Filter[T] (optional)) – An optional “master” filter to mix into any

Returns:

compile_tree – Factory function which takes an instance of type T, builds a Tree from it, and returns the root Node

Return type:

Callable[[T, Optional[int], Optional[Filter[T]]], Node]

polymerist.genutils.trees.get_node_attrs(node: anytree.node.Node, attr_filter: polymerist.genutils.filters.Filter[str] | None = None, include_name: bool = False) → dict[str, Any]

Return a dict of all attributes set on a Node

Parameters:

• node (Node) – An anytree.node.Node object

• attr_filter (Filter[str] (optional), default lambda x : True) – An optional criterion to decide whether an attribute should be kept Should be a function which accepts a single string arg and returns a bool

  Return value of True will include an attribute in the return, while value or False will exclude it If None, will default to always True (i.e. no attributes will be screened out)

• include_name (bool, deafult False) – Whether to include the required “name” attribute of a Node in the returned dict Useful to exclude when copying nodes to avoid redundancy By default False (i.e. “name” will be excluded from the returned attributes)

Returns:

node_attrs – A dictionary keyed by attribute name whose values are the values set for repective Node attributes

Return type:

dict[str, Any]

polymerist.genutils.trees.copy_tree(root: anytree.node.Node, stop: polymerist.genutils.filters.Filter[anytree.node.Node] | None = None, attr_filter: polymerist.genutils.filters.Filter[str] | None = None) → anytree.node.Node

Create a copy of an anytree Node hierarchy. Can provide filters and stop criteria to exclude nodes or whole branches

Parameters:

• root (Node) – An anytree.node.Node object which is the root of a tree-like hierarchy

• stop (Filter[Node] (optional), default None) – An optional criterion to decide when to stop traversing the tree to be copied Should be a function which accepts a single Node arg and returns a bool

  This criterion is inclusive, i.e. a Node matching this criterion will NOT be included in the copied tree, nor will any of its children or their children, recursively

  Return value of True will exclude all subsequent nodes on a branch, while value of True will proceed with iteration and copying If None, will default to always False (i.e. no extra stop conditions, full tree will be copied)

• attr_filter (Filter[str] (optional), default lambda x : True) – An optional criterion to decide whether an attribute should be kept Should be a function which accepts a single string arg and returns a bool

  Return value of True will include an attribute in the return, while value or False will exclude it If None, will default to always True (i.e. no attributes will be screened out)

Returns:

root_new – The root Node of the copied tree structure

Return type:

Node

polymerist.genutils.trees.tree_to_networkx(root: anytree.node.Node, stop: polymerist.genutils.filters.Filter[anytree.node.Node] | None = None, attr_filter: polymerist.genutils.filters.Filter[str] | None = None) → anytree.node.Node

Produces a networkx.DiGraph representation on an anytree Tree

Parameters:

• root (Node) – An anytree.node.Node object which is the root of a tree-like hierarchy

• stop (Filter[Node] (optional), default None) – An optional criterion to decide when to stop traversing the tree to be copied Should be a function which accepts a single Node arg and returns a bool

  Return value of True will exclude all subsequent nodes on a branch, while value of True will proceed with iteration and copying If None, will default to always False (i.e. no extra stop conditions, full tree will be copied)

  This criterion is inclusive, i.e. a Node matching this criterion will NOT be included in the copied tree, nor will any of its children or their children, recursively

• attr_filter (Filter[str] (optional), default lambda x : True) – An optional criterion to decide whether an attribute should be kept Should be a function which accepts a single string arg and returns a bool

  Return value of True will include an attribute in the return, while value or False will exclude it If None, will default to always True (i.e. no attributes will be screened out)

Returns:

nx_tree – A networkx directed graph object

Return type:

diGraph

polymerist.genutils.trees.treestr(root: anytree.Node, attr: str = 'name', style: str | anytree.render.AbstractStyle = ContStyle(), childiter: Callable[[tuple[anytree.Node]], Iterable[anytree.Node]] = list, maxlevel: int = None) → str

Return a printable string representation of a tree from a root Node, reminiscent of GNU tree