sec_parser.semantic_tree ======================== .. py:module:: sec_parser.semantic_tree .. autoapi-nested-parse:: The semantic_tree subpackage focuses on storing and manipulating Semantic Elements in a tree data structure. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/sec_parser/semantic_tree/nesting_rules/index /autoapi/sec_parser/semantic_tree/render_/index /autoapi/sec_parser/semantic_tree/semantic_tree/index /autoapi/sec_parser/semantic_tree/tree_builder/index /autoapi/sec_parser/semantic_tree/tree_node/index Classes ------- .. autoapisummary:: sec_parser.semantic_tree.AbstractNestingRule sec_parser.semantic_tree.AlwaysNestAsChildRule sec_parser.semantic_tree.AlwaysNestAsParentRule sec_parser.semantic_tree.NestSameTypeDependingOnLevelRule sec_parser.semantic_tree.SemanticTree sec_parser.semantic_tree.TreeBuilder sec_parser.semantic_tree.TreeNode Functions --------- .. autoapisummary:: sec_parser.semantic_tree.render Package Contents ---------------- .. py:class:: AbstractNestingRule(*, exclude_parents: set[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]] | None = None, exclude_children: set[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]] | None = None) Bases: :py:obj:`abc.ABC` AbstractNestingRule is a base class for defining rules for nesting semantic elements. Each rule should ideally mention at most one or two types of semantic elements to reduce coupling and complexity. In case of conflicts between rules, they should be resolved through parameters like exclude_parents and exclude_children. .. py:attribute:: _exclude_parents :value: None .. py:attribute:: _exclude_children :value: None .. py:method:: should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) -> bool .. py:method:: _should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) -> bool :abstractmethod: .. py:class:: AlwaysNestAsChildRule(cls: type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement], /, *, exclude_parents: set[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]] | None = None, exclude_children: set[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]] | None = None) Bases: :py:obj:`AbstractNestingRule` AbstractNestingRule is a base class for defining rules for nesting semantic elements. Each rule should ideally mention at most one or two types of semantic elements to reduce coupling and complexity. In case of conflicts between rules, they should be resolved through parameters like exclude_parents and exclude_children. .. py:attribute:: _cls .. py:method:: _should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) -> bool .. py:class:: AlwaysNestAsParentRule(cls: type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement], /, *, exclude_parents: set[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]] | None = None, exclude_children: set[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]] | None = None) Bases: :py:obj:`AbstractNestingRule` AbstractNestingRule is a base class for defining rules for nesting semantic elements. Each rule should ideally mention at most one or two types of semantic elements to reduce coupling and complexity. In case of conflicts between rules, they should be resolved through parameters like exclude_parents and exclude_children. .. py:attribute:: _cls .. py:method:: _should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) -> bool .. py:class:: NestSameTypeDependingOnLevelRule(*, exclude_parents: set[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]] | None = None, exclude_children: set[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]] | None = None) Bases: :py:obj:`AbstractNestingRule` AbstractNestingRule is a base class for defining rules for nesting semantic elements. Each rule should ideally mention at most one or two types of semantic elements to reduce coupling and complexity. In case of conflicts between rules, they should be resolved through parameters like exclude_parents and exclude_children. .. py:method:: _should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) -> bool .. py:function:: render(tree: list[sec_parser.semantic_tree.tree_node.TreeNode] | sec_parser.semantic_tree.tree_node.TreeNode | sec_parser.semantic_tree.semantic_tree.SemanticTree | list[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement], *, pretty: bool | None = True, ignored_types: tuple[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement], Ellipsis] | None = None, char_display_limit: int | None = None, verbose: bool = False, _nodes: list[sec_parser.semantic_tree.tree_node.TreeNode] | None = None, _level: int = 0, _prefix: str = '', _is_root: bool = True) -> str render function is used to visualize the structure of the semantic tree. It is primarily used for debugging purposes. .. py:class:: SemanticTree(root_nodes: list[sec_parser.semantic_tree.tree_node.TreeNode]) .. py:attribute:: _root_nodes .. py:method:: __iter__() -> collections.abc.Iterator[sec_parser.semantic_tree.tree_node.TreeNode] Iterate over the root nodes of the tree. .. py:method:: __len__() -> int .. py:property:: nodes :type: collections.abc.Iterator[sec_parser.semantic_tree.tree_node.TreeNode] Get all nodes in the semantic tree. This includes the root nodes and all their descendants. .. py:method:: render(*, pretty: bool | None = True, ignored_types: tuple[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement], Ellipsis] | None = None, char_display_limit: int | None = None, verbose: bool = False) -> str Render the semantic tree as a human-readable string. Syntactic sugar for a more convenient usage of `render`. .. py:method:: print(*, pretty: bool | None = True, ignored_types: tuple[type[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement], Ellipsis] | None = None, char_display_limit: int | None = None, verbose: bool = False, line_limit: int | None = None) -> None Print the semantic tree as a human-readable string. Syntactic sugar for a more convenient usage of `render`. .. py:class:: TreeBuilder(get_rules: Callable[[], list[sec_parser.semantic_tree.nesting_rules.AbstractNestingRule]] | None = None) Builds a semantic tree from a list of semantic elements. Why Use a Tree Structure? ========================= Using a tree data structure allows for easier and more robust filtering of sections. With a tree, you can select specific branches to filter, making it straightforward to identify section boundaries. This approach is more maintainable and robust compared to attempting the same operations on a flat list of elements. Overview: ========= 1. Takes a list of semantic elements. 2. Applies nesting rules to these elements. Customization: ============== The nesting process is customizable through a list of rules. These rules determine how new elements should be nested under existing ones. Advanced Customization: ======================= You can supply your own set of rules by providing a callable to `get_rules`, which should return a list of `AbstractNestingRule` instances. .. py:attribute:: get_rules .. py:method:: get_default_rules() -> list[sec_parser.semantic_tree.nesting_rules.AbstractNestingRule] :staticmethod: .. py:method:: build(elements: list[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]) -> sec_parser.semantic_tree.semantic_tree.SemanticTree .. py:method:: _find_parent_node(new_node: sec_parser.semantic_tree.tree_node.TreeNode, stack: list[sec_parser.semantic_tree.tree_node.TreeNode], rules: list[sec_parser.semantic_tree.nesting_rules.AbstractNestingRule]) -> sec_parser.semantic_tree.tree_node.TreeNode | None .. py:method:: _should_nest_under(child_node: sec_parser.semantic_tree.tree_node.TreeNode, parent_node: sec_parser.semantic_tree.tree_node.TreeNode, rules: list[sec_parser.semantic_tree.nesting_rules.AbstractNestingRule]) -> bool .. py:class:: TreeNode(semantic_element: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, *, parent: TreeNode | None = None, children: collections.abc.Iterable[TreeNode] | None = None) The TreeNode class is a fundamental part of the semantic tree structure. Each TreeNode represents a node in the tree. It holds a reference to a semantic element, maintains a list of its child nodes, and a reference to its parent node. This class provides methods for managing the tree structure, such as adding and removing child nodes. Importantly, these methods ensure logical consistency as children/parents are being changed. For example, if a parent is removed from a child, the child is automatically removed from the parent. .. py:attribute:: _semantic_element .. py:attribute:: _children :type: list[TreeNode] :value: [] .. py:attribute:: _parent :type: TreeNode | None :value: None .. py:property:: parent :type: TreeNode | None .. py:property:: semantic_element :type: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement .. py:property:: children :type: list[TreeNode] .. py:method:: add_child(child: TreeNode) -> None .. py:method:: add_children(children: collections.abc.Iterable[TreeNode]) -> None .. py:method:: remove_child(child: TreeNode) -> None .. py:method:: has_child(child: TreeNode) -> bool .. py:method:: get_descendants() -> collections.abc.Iterator[TreeNode] .. py:method:: __repr__() -> str .. py:property:: text :type: str Property text is a passthrough to the SemanticElement text property. .. py:method:: get_source_code(*, pretty: bool = False) -> str get_source_code is a passthrough to the SemanticElement method.