gentry API Documentation

GitHub repo

gentry is a Python package for representing and manipulating generic tree structures with support for extensible child groups, visitor patterns, and convenient representations in the form of Markdown with Mermaid diagrams.

This is the API Documentation for the classes defined in gentry.tree

class Tree

A basic Tree object has one attribute children which is a defaultdict.
The keys are group names, the values are lists of Tree objects.
If the children argument is given, it must be a defaultdict or it will be converted to one.
If any keys to the children dict are also in the groups set, these keys can also be used as attributes to directly access the values in the children dictionary.
This setup allows for mixin classes and generic tools like a visitor to rely on the presence of a children dict that doesn't change if a Tree class is inherited, yet allow for a more semantically meaningful way of accessing groups of children in derived classes.

__init__(self, label, children=None, properties=None, *args, **kwargs)

Initialize a Tree node.

  • label (str): The label for this node.
  • children (defaultdict|dict|None): Optional. A mapping from group names to lists of child Tree nodes. If None, an empty defaultdict is used.
  • properties (dict|None): Optional. Arbitrary properties for this node.
  • *args, **kwargs: Additional arguments for multiple inheritance.

Any keyword arguments that are defined in _groups will be added as an entry in _children.
It is an error to pass a groups of children both as keyword argument and as part of the children argument.

__getattr__(self, name)

Called when the default attribute access fails.
If the attribute name is in the _groups set, return the corresponding list of children from _children.
Otherwise, raise AttributeError.

  • name (str): The attribute name.
  • Returns: list[Tree]: The list of child nodes for the group.
  • Raises: AttributeError: If the attribute is not found and is also not a group.
__setattr__(self, name, value)

Called when an attribute assignment is attempted.
If the attribute name is in _groups, set the corresponding group in _children to the given value, which must be a list. Otherwise, set the attribute normally.

  • name (str): The attribute name.
  • value: The value to assign.
  • Raises: AttributeError: If assigning a non-list to a group attribute.
__repr__(self)

Return a string representation of the Tree node.
Returns: str: The string representation.

is_leaf(self)

Check if the node is a leaf (i.e., has no children in any group).
Returns: bool: True if the node has no children, False otherwise.

class Visitor

__init__(self, root, strict=False)

Initialize the Visitor.

  • root (Tree): The root node to start visiting from.
  • strict (bool): If True, require exact visitor method matches for each node type.

visit(self)

Start the visiting process from the root node.
Returns: The result of visiting the root node.

_get_visitor(self, tree)

Find the appropriate visitor method for the given tree node.
When we visit a node the name of the visitor node will be constructed from the class name and the lower case class name of the visitor class. So if our Visitor derived class is called Validator and we encounter an instance of Person, the visitor we will be looking for is _do_validator_Person.
If that method cannot be found, we will look for a generic visitor _do_validator(), unless the visitor class was instantiated with strict=True.
If no visitor method was found, we follow the method resolution order to see if we can find one in one of the superclasses.

  • tree (Tree): The node to find a visitor for.
  • Returns: Callable: The visitor method.
  • Raises: NotImplementedError: If no suitable visitor method is found.
_visit(self, tree)

Recursively visit the tree in a bottom-up (children first) manner.

  • tree (Tree): The node to visit.
  • Returns: dict: A dictionary containing the results for this node and its children.

class Count(Visitor)

_do_count(self, tree)

Visitor method for counting a single node.

  • tree (Tree): The node being counted.
  • Returns: int: Always returns 1 for each node.

_sum(d) (static method)

Recursively sum up all integer values in a nested structure of dicts and lists.

  • d: The nested structure (dict, list, or int).
  • Returns: int: The total sum of all integers found.

count(self)

Count the total number of nodes in the tree.
Returns: int: The total node count.