sec_parser.semantic_tree

The semantic_tree subpackage focuses on storing and manipulating Semantic Elements in a tree data structure.

Submodules

• sec_parser.semantic_tree.nesting_rules
• sec_parser.semantic_tree.render
• sec_parser.semantic_tree.semantic_tree
• sec_parser.semantic_tree.tree_builder
• sec_parser.semantic_tree.tree_node

Classes

AbstractNestingRule	AbstractNestingRule is a base class for defining rules for nesting
AlwaysNestAsChildRule	AbstractNestingRule is a base class for defining rules for nesting
AlwaysNestAsParentRule	AbstractNestingRule is a base class for defining rules for nesting
NestSameTypeDependingOnLevelRule	AbstractNestingRule is a base class for defining rules for nesting
SemanticTree
TreeBuilder	Builds a semantic tree from a list of semantic elements.
TreeNode	The TreeNode class is a fundamental part of the semantic tree structure.

Functions

render(→ str)

render function is used to visualize the structure of the semantic tree.

Package Contents

class sec_parser.semantic_tree.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: 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.

should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) → bool

abstract _should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) → bool

class sec_parser.semantic_tree.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: 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.

_should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) → bool

class sec_parser.semantic_tree.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: 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.

_should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) → bool

class sec_parser.semantic_tree.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: 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.

_should_be_nested_under(parent: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement, child: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement) → bool

sec_parser.semantic_tree.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.

class sec_parser.semantic_tree.SemanticTree(root_nodes: list[sec_parser.semantic_tree.tree_node.TreeNode])

__iter__() → collections.abc.Iterator[sec_parser.semantic_tree.tree_node.TreeNode]

Iterate over the root nodes of the tree.

__len__() → int

property nodes: 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.

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.

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.

class sec_parser.semantic_tree.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.

static get_default_rules() → list[sec_parser.semantic_tree.nesting_rules.AbstractNestingRule]

build(elements: list[sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement]) → sec_parser.semantic_tree.semantic_tree.SemanticTree

_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

_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

class sec_parser.semantic_tree.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.

property semantic_element: sec_parser.semantic_elements.abstract_semantic_element.AbstractSemanticElement

property children: list[TreeNode]

property parent: TreeNode | None

add_child(child: TreeNode) → None

add_children(children: collections.abc.Iterable[TreeNode]) → None

remove_child(child: TreeNode) → None

has_child(child: TreeNode) → bool

get_descendants() → collections.abc.Iterator[TreeNode]

__repr__() → str

Return repr(self).

property text: str

Property text is a passthrough to the SemanticElement text property.

get_source_code(*, pretty: bool = False) → str

get_source_code is a passthrough to the SemanticElement method.