polymerist.genutils.trees ========================= .. py:module:: polymerist.genutils.trees .. autoapi-nested-parse:: Generic functionality for tree-like data structures. Based on the anytree module (https://github.com/c0fec0de/anytree) Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/polymerist/genutils/trees/treebase/index /autoapi/polymerist/genutils/trees/treecopy/index /autoapi/polymerist/genutils/trees/treeviz/index Exceptions ---------- .. autoapisummary:: polymerist.genutils.trees.MissingPrerequisitePackage Classes ------- .. autoapisummary:: polymerist.genutils.trees.NodeCorrespondence Functions --------- .. autoapisummary:: polymerist.genutils.trees.modules_installed polymerist.genutils.trees.compile_tree_factory polymerist.genutils.trees.get_node_attrs polymerist.genutils.trees.copy_tree polymerist.genutils.trees.tree_to_networkx polymerist.genutils.trees.treestr Package Contents ---------------- .. py:function:: 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 :rtype: bool .. py:exception:: MissingPrerequisitePackage(importing_package_name: str, use_case: str, install_link: str, dependency_name: str, dependency_name_formal: Optional[str] = None) Bases: :py:obj:`Exception` Raised when a package dependency cannot be found and the user should be alerted with install instructions .. py:class:: NodeCorrespondence Bases: :py:obj:`abc.ABC`, :py:obj:`Generic`\ [\ :py:obj:`T`\ ] Abstract base for implementing how to build an anytree Node tree for an arbitrary class .. py:method:: name(obj: T) -> str :abstractmethod: Define how to obtain a string name .. py:method:: has_children(obj: T) -> bool :abstractmethod: Define how to check if an object can produce children in the first place before attempting to do so .. py:method:: children(obj: T) -> Optional[Iterable[T]] :abstractmethod: Define how to obtain node children from an instance Should return NoneType if the instance is "leaf-like" .. py:function:: compile_tree_factory(node_corresp: NodeCorrespondence[T], class_alias: Optional[str] = None, obj_attr_name: Optional[str] = None, exclude_mixin: Optional[polymerist.genutils.filters.Filter[T]] = None) -> Callable[[T, Optional[int], Optional[polymerist.genutils.filters.Filter[T]]], 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 :rtype: Callable[[T, Optional[int], Optional[Filter[T]]], Node] .. py:function:: get_node_attrs(node: anytree.node.Node, attr_filter: Optional[polymerist.genutils.filters.Filter[str]] = 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 :rtype: dict[str, Any] .. py:function:: copy_tree(root: anytree.node.Node, stop: Optional[polymerist.genutils.filters.Filter[anytree.node.Node]] = None, attr_filter: Optional[polymerist.genutils.filters.Filter[str]] = 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 :rtype: Node .. py:function:: tree_to_networkx(root: anytree.node.Node, stop: Optional[polymerist.genutils.filters.Filter[anytree.node.Node]] = None, attr_filter: Optional[polymerist.genutils.filters.Filter[str]] = 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 :rtype: diGraph .. py:function:: treestr(root: anytree.Node, attr: str = 'name', style: Union[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