graphtage.ast

Generic node types for representing abstract syntax trees.

ast classes

Assignment

class graphtage.ast.Assignment(*args, **kwargs)

Bases: DataClassNode

A node representing an assignment.

__init__(*args, **kwargs): Be careful extending __init__; consider using DataClassNode.post_init() instead.

add_edit_modifier(modifier: Callable[[TreeNode, TreeNode], Edit | None])

all_children_are_leaves() → bool

Tests whether all of the children of this container are leaves.

Equivalent to:

all(c.is_leaf for c in self)

Returns:: True if all children are leaves.
Return type:: bool

calculate_total_size() → int

Calculates the size of this node. This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

children() → Sequence[TreeNode]

The children of this node.

Equivalent to:

list(self)

copy() → T: Creates a deep copy of this node

copy_from(children: Iterable[TreeNode]) → T: Constructs a new instance of this tree node from a list of its children

dfs() → Iterator[TreeNode]

Performs a depth-first traversal over all of this node’s descendants.

self is always included and yielded first.

This implementation is equivalent to:

stack = [self]
while stack:
    node = stack.pop()
    yield node
    stack.extend(reversed(node.children()))

diff(node: TreeNode) → EditedTreeNode | T

Performs a diff against the provided node.

Parameters:: node – The node against which to perform the diff.
Returns:: An edited version of this node with all edits being completed.
Return type:: Union[EditedTreeNode, T]

editable_dict() → Dict[str, Any]

Copies self.__dict__, calling TreeNode.editable_dict() on any TreeNode objects therein.

This is equivalent to:

ret = dict(self.__dict__)
if not self.is_leaf:
    for key, value in ret.items():
        if isinstance(value, TreeNode):
            ret[key] = value.make_edited()
return ret

This is used by TreeNode.make_edited().

property edited: bool

Returns whether this node has been edited.

The default implementation returns False, whereas EditedTreeNode.edited() returns True.

edits(node: TreeNode) → Edit

Calculates the best edit to transform this node into the provided node.

Parameters:: node – The node to which to transform.
Returns:: The best possible edit.
Return type:: Edit

get_all_edit_contexts(node: TreeNode) → Iterator[Tuple[Tuple[TreeNode, ...], Edit]]

Returns an iterator over all edit contexts that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over pairs of paths from node to the edited node, as well as its edit. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Tuple[Tuple[“TreeNode”, …], Edit]

get_all_edits(node: TreeNode) → Iterator[Edit]

Returns an iterator over all edits that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over edits. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Edit]

property is_leaf: bool

Container nodes are never leaves, even if they have no children.

Returns:: False
Return type:: bool

items() → Iterator[Tuple[str, TreeNode]]

make_edited() → EditedTreeNode | T

Returns a new, copied instance of this node that is also an instance of EditedTreeNode.

This is equivalent to:

return self.__class__.edited_type()(self)

Returns:: A copied version of this node that is also an instance of EditedTreeNode and thereby mutable.
Return type:: Union[EditedTreeNode, T]

property parent: TreeNode | None

The parent node of this node, or None if it has no parent.

The setter for this property should only be called by the parent node setting itself as the parent of its child.

ContainerNode subclasses automatically set this property for all of their children. However, if you define a subclass of TreeNode does not extend off of ContainerNode and for which len(self.children()) > 0, then each child’s parent must be set.

post_init()

Callback called after this class’s members have been initialized.

This callback should not call super().post_init(). Each superclass’s post_init() will be automatically called in order of the __mro__.

print(printer: Printer): Prints this node.

print_parent_context(printer: Printer, for_child: TreeNode)

Prints the context for the given child node.

For example, if this node represents a list and the child is the element at index 3, then “[3]” might be printed.

The child is expected to be one of this node’s children, but this is not validated.

The default implementation prints nothing.

targets: ListNode

to_obj()

Returns a pure Python representation of this node.

For example, a node representing a list, like graphtage.ListNode, should return a Python list. A node representing a mapping, like graphtage.MappingNode, should return a Python dict. Container nodes should recursively call TreeNode.to_obj() on all of their children.

This is used solely for the providing objects to operate on in the commandline expressions evaluation, for options like –match-if and –match-unless.

property total_size: int

The size of this node.

This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

The first time this property is called, its value will be set and memoized by calling TreeNode.calculate_total_size().

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

value: TreeNode

Call

class graphtage.ast.Call(*args, **kwargs)

Bases: DataClassNode

A node representing a function call.

__init__(*args, **kwargs): Be careful extending __init__; consider using DataClassNode.post_init() instead.

add_edit_modifier(modifier: Callable[[TreeNode, TreeNode], Edit | None])

all_children_are_leaves() → bool

Tests whether all of the children of this container are leaves.

Equivalent to:

all(c.is_leaf for c in self)

Returns:: True if all children are leaves.
Return type:: bool

args: CallArguments

calculate_total_size() → int

Calculates the size of this node. This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

children() → Sequence[TreeNode]

The children of this node.

Equivalent to:

list(self)

copy() → T: Creates a deep copy of this node

copy_from(children: Iterable[TreeNode]) → T: Constructs a new instance of this tree node from a list of its children

dfs() → Iterator[TreeNode]

Performs a depth-first traversal over all of this node’s descendants.

self is always included and yielded first.

This implementation is equivalent to:

stack = [self]
while stack:
    node = stack.pop()
    yield node
    stack.extend(reversed(node.children()))

diff(node: TreeNode) → EditedTreeNode | T

Performs a diff against the provided node.

Parameters:: node – The node against which to perform the diff.
Returns:: An edited version of this node with all edits being completed.
Return type:: Union[EditedTreeNode, T]

editable_dict() → Dict[str, Any]

Copies self.__dict__, calling TreeNode.editable_dict() on any TreeNode objects therein.

This is equivalent to:

ret = dict(self.__dict__)
if not self.is_leaf:
    for key, value in ret.items():
        if isinstance(value, TreeNode):
            ret[key] = value.make_edited()
return ret

This is used by TreeNode.make_edited().

property edited: bool

Returns whether this node has been edited.

The default implementation returns False, whereas EditedTreeNode.edited() returns True.

edits(node: TreeNode) → Edit

Calculates the best edit to transform this node into the provided node.

Parameters:: node – The node to which to transform.
Returns:: The best possible edit.
Return type:: Edit

func: TreeNode

get_all_edit_contexts(node: TreeNode) → Iterator[Tuple[Tuple[TreeNode, ...], Edit]]

Returns an iterator over all edit contexts that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over pairs of paths from node to the edited node, as well as its edit. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Tuple[Tuple[“TreeNode”, …], Edit]

get_all_edits(node: TreeNode) → Iterator[Edit]

Returns an iterator over all edits that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over edits. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Edit]

property is_leaf: bool

Container nodes are never leaves, even if they have no children.

Returns:: False
Return type:: bool

items() → Iterator[Tuple[str, TreeNode]]

kwargs: CallKeywords

make_edited() → EditedTreeNode | T

Returns a new, copied instance of this node that is also an instance of EditedTreeNode.

This is equivalent to:

return self.__class__.edited_type()(self)

Returns:: A copied version of this node that is also an instance of EditedTreeNode and thereby mutable.
Return type:: Union[EditedTreeNode, T]

property parent: TreeNode | None

The parent node of this node, or None if it has no parent.

The setter for this property should only be called by the parent node setting itself as the parent of its child.

ContainerNode subclasses automatically set this property for all of their children. However, if you define a subclass of TreeNode does not extend off of ContainerNode and for which len(self.children()) > 0, then each child’s parent must be set.

post_init()

Callback called after this class’s members have been initialized.

This callback should not call super().post_init(). Each superclass’s post_init() will be automatically called in order of the __mro__.

print(printer: Printer): Prints this node.

print_parent_context(printer: Printer, for_child: TreeNode)

Prints the context for the given child node.

For example, if this node represents a list and the child is the element at index 3, then “[3]” might be printed.

The child is expected to be one of this node’s children, but this is not validated.

The default implementation prints nothing.

to_obj()

Returns a pure Python representation of this node.

For example, a node representing a list, like graphtage.ListNode, should return a Python list. A node representing a mapping, like graphtage.MappingNode, should return a Python dict. Container nodes should recursively call TreeNode.to_obj() on all of their children.

This is used solely for the providing objects to operate on in the commandline expressions evaluation, for options like –match-if and –match-unless.

property total_size: int

The size of this node.

This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

The first time this property is called, its value will be set and memoized by calling TreeNode.calculate_total_size().

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

CallArguments

class graphtage.ast.CallArguments(nodes: Iterable[T], allow_list_edits: bool = True, allow_list_edits_when_same_length: bool = True)

Bases: ListNode

__init__(nodes: Iterable[T], allow_list_edits: bool = True, allow_list_edits_when_same_length: bool = True)

Initializes a List node.

Parameters:

nodes – The set of nodes in this list.
allow_list_edits – Whether to consider removal and insertion when editing this list.
allow_list_edits_when_same_length – Whether to consider removal and insertion when comparing this list to another list of the same length.

__iter__() → Iterator[TreeNode]

Iterates over this sequence’s child nodes.

This is equivalent to:

return iter(self._children)

__len__() → int

The number of children of this sequence.

This is equivalent to:

return len(self._children)

add_edit_modifier(modifier: Callable[[TreeNode, TreeNode], Edit | None])

all_children_are_leaves() → bool

Tests whether all of the children of this container are leaves.

Equivalent to:

all(c.is_leaf for c in self)

Returns:: True if all children are leaves.
Return type:: bool

calculate_total_size()

Calculates the total size of this sequence.

This is equivalent to:

return sum(c.total_size for c in self)

children() → Sequence[TreeNode]

The children of this node.

Equivalent to:

list(self)

property container_type: Type[Tuple[T, ...]]

The container type required by graphtage.sequences.SequenceNode

Returns:: tuple
Return type:: Type[Tuple[T, …]]

copy() → T: Creates a deep copy of this node

copy_from(children: Iterable[TreeNode]) → C: Constructs a new instance of this tree node from a list of its children

dfs() → Iterator[TreeNode]

Performs a depth-first traversal over all of this node’s descendants.

self is always included and yielded first.

This implementation is equivalent to:

stack = [self]
while stack:
    node = stack.pop()
    yield node
    stack.extend(reversed(node.children()))

diff(node: TreeNode) → EditedTreeNode | T

Performs a diff against the provided node.

Parameters:: node – The node against which to perform the diff.
Returns:: An edited version of this node with all edits being completed.
Return type:: Union[EditedTreeNode, T]

editable_dict() → Dict[str, Any]

Copies self.__dict__, calling TreeNode.editable_dict() on all children.

This is equivalent to:

ret = dict(self.__dict__)
ret['_children'] = self.container_type(n.make_edited() for n in self)
return ret

This is used by SequenceNode.make_edited().

property edited: bool

Returns whether this node has been edited.

The default implementation returns False, whereas EditedTreeNode.edited() returns True.

edits(node: TreeNode) → Edit

Calculates the best edit to transform this node into the provided node.

Parameters:: node – The node to which to transform.
Returns:: The best possible edit.
Return type:: Edit

get_all_edit_contexts(node: TreeNode) → Iterator[Tuple[Tuple[TreeNode, ...], Edit]]

Returns an iterator over all edit contexts that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over pairs of paths from node to the edited node, as well as its edit. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Tuple[Tuple[“TreeNode”, …], Edit]

get_all_edits(node: TreeNode) → Iterator[Edit]

Returns an iterator over all edits that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over edits. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Edit]

property is_leaf: bool

Container nodes are never leaves, even if they have no children.

Returns:: False
Return type:: bool

make_edited() → EditedTreeNode | T

Returns a new, copied instance of this node that is also an instance of EditedTreeNode.

This is equivalent to:

return self.__class__.edited_type()(self)

Returns:: A copied version of this node that is also an instance of EditedTreeNode and thereby mutable.
Return type:: Union[EditedTreeNode, T]

property parent: TreeNode | None

The parent node of this node, or None if it has no parent.

The setter for this property should only be called by the parent node setting itself as the parent of its child.

ContainerNode subclasses automatically set this property for all of their children. However, if you define a subclass of TreeNode does not extend off of ContainerNode and for which len(self.children()) > 0, then each child’s parent must be set.

print(printer: Printer)

Prints a sequence node.

By default, sequence nodes are printed like lists:

SequenceFormatter('[', ']', ',').print(printer, self)

print_parent_context(printer: Printer, for_child: TreeNode)

Prints the context for the given child node.

For example, if this node represents a list and the child is the element at index 3, then “[3]” might be printed.

The child is expected to be one of this node’s children, but this is not validated.

The default implementation prints nothing.

to_obj()

Returns a pure Python representation of this node.

For example, a node representing a list, like graphtage.ListNode, should return a Python list. A node representing a mapping, like graphtage.MappingNode, should return a Python dict. Container nodes should recursively call TreeNode.to_obj() on all of their children.

This is used solely for the providing objects to operate on in the commandline expressions evaluation, for options like –match-if and –match-unless.

property total_size: int

The size of this node.

This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

The first time this property is called, its value will be set and memoized by calling TreeNode.calculate_total_size().

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

CallKeywords

class graphtage.ast.CallKeywords(items: Iterable[T], auto_match_keys: bool = True)

Bases: DictNode

__contains__(item: TreeNode)

Tests whether the given item is a key in this mapping.

The implementation is equivalent to:

return any(k == item for k, _ in self.items())

Note

This implementation runs in worst-case linear time in the size of the mapping.

Parameters:: item – The key of the item sought.
Returns:: True if the key exists in this mapping.
Return type:: bool

__getitem__(item: TreeNode) → KeyValuePairNode

Looks up a key/value pair item from this mapping by its key.

The implementation is equivalent to:

for kvp in self:
    if kvp.key == item:
        return kvp
raise KeyError(item)

Note

This implementation runs in worst-case linear time in the size of the mapping.

Parameters:: item – The key of the key/value pair that is sought.
Returns:: The first key/value pair found with key item.
Return type:: KeyValuePairNode
Raises:: KeyError – If the key is not found.

__init__(items: Iterable[T], auto_match_keys: bool = True)

add_edit_modifier(modifier: Callable[[TreeNode, TreeNode], Edit | None])

all_children_are_leaves() → bool

Tests whether all of the children of this container are leaves.

Equivalent to:

all(c.is_leaf for c in self)

Returns:: True if all children are leaves.
Return type:: bool

calculate_total_size()

Calculates the size of this node. This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

children() → Sequence[TreeNode]

The children of this node.

Equivalent to:

list(self)

property container_type: Type[HashableCounter[T]]

Returns the container type used to store SequenceNode._children.

This is used for performing a deep copy of this node in the SequenceNode.editable_dict() function.

copy() → T: Creates a deep copy of this node

copy_from(children: Iterable[T]) → C: Constructs a new instance of this tree node from a list of its children

dfs() → Iterator[TreeNode]

Performs a depth-first traversal over all of this node’s descendants.

self is always included and yielded first.

This implementation is equivalent to:

stack = [self]
while stack:
    node = stack.pop()
    yield node
    stack.extend(reversed(node.children()))

diff(node: TreeNode) → EditedTreeNode | T

Performs a diff against the provided node.

Parameters:: node – The node against which to perform the diff.
Returns:: An edited version of this node with all edits being completed.
Return type:: Union[EditedTreeNode, T]

editable_dict() → Dict[str, Any]

Copies self.__dict__, calling TreeNode.editable_dict() on all children.

This is equivalent to:

ret = dict(self.__dict__)
ret['_children'] = self.container_type(n.make_edited() for n in self)
return ret

This is used by SequenceNode.make_edited().

property edited: bool

Returns whether this node has been edited.

The default implementation returns False, whereas EditedTreeNode.edited() returns True.

edits(node: TreeNode) → Edit

Calculates the best edit to transform this node into the provided node.

Parameters:: node – The node to which to transform.
Returns:: The best possible edit.
Return type:: Edit

classmethod from_dict(source_dict: Dict[LeafNode, TreeNode]) → T

Constructs a DictNode from a mapping of LeafNode to TreeNode.

Parameters:: source_dict – The source mapping.
Returns:: The resulting DictNode.
Return type:: DictNode

get_all_edit_contexts(node: TreeNode) → Iterator[Tuple[Tuple[TreeNode, ...], Edit]]

Returns an iterator over all edit contexts that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over pairs of paths from node to the edited node, as well as its edit. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Tuple[Tuple[“TreeNode”, …], Edit]

get_all_edits(node: TreeNode) → Iterator[Edit]

Returns an iterator over all edits that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over edits. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Edit]

property is_leaf: bool

Container nodes are never leaves, even if they have no children.

Returns:: False
Return type:: bool

items() → Iterator[Tuple[TreeNode, TreeNode]]

Iterates over the key/value pairs in this mapping, similar to dict.items().

The implementation is equivalent to:

for kvp in self:
    yield kvp.key, kvp.value

since MappingNode.__iter__() returns an iterator over graphtage.KeyValuePairNode.

make_edited() → EditedTreeNode | T

Returns a new, copied instance of this node that is also an instance of EditedTreeNode.

This is equivalent to:

return self.__class__.edited_type()(self)

Returns:: A copied version of this node that is also an instance of EditedTreeNode and thereby mutable.
Return type:: Union[EditedTreeNode, T]

classmethod make_key_value_pair_node(key: LeafNode, value: TreeNode, allow_key_edits: bool = True) → KeyValuePairNode

property parent: TreeNode | None

The parent node of this node, or None if it has no parent.

The setter for this property should only be called by the parent node setting itself as the parent of its child.

ContainerNode subclasses automatically set this property for all of their children. However, if you define a subclass of TreeNode does not extend off of ContainerNode and for which len(self.children()) > 0, then each child’s parent must be set.

print(printer: Printer)

Prints a sequence node.

By default, sequence nodes are printed like lists:

SequenceFormatter('[', ']', ',').print(printer, self)

print_parent_context(printer: Printer, for_child: TreeNode)

Prints the context for the given child node.

For example, if this node represents a list and the child is the element at index 3, then “[3]” might be printed.

The child is expected to be one of this node’s children, but this is not validated.

The default implementation prints nothing.

to_obj() → Dict[Any, Any]

Returns a pure Python representation of this node.

For example, a node representing a list, like graphtage.ListNode, should return a Python list. A node representing a mapping, like graphtage.MappingNode, should return a Python dict. Container nodes should recursively call TreeNode.to_obj() on all of their children.

This is used solely for the providing objects to operate on in the commandline expressions evaluation, for options like –match-if and –match-unless.

property total_size: int

The size of this node.

This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

The first time this property is called, its value will be set and memoized by calling TreeNode.calculate_total_size().

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

Import

class graphtage.ast.Import(names: ListNode, from_name: StringNode)

Bases: DataClassNode

__init__(names: ListNode, from_name: StringNode): Be careful extending __init__; consider using DataClassNode.post_init() instead.

add_edit_modifier(modifier: Callable[[TreeNode, TreeNode], Edit | None])

all_children_are_leaves() → bool

Tests whether all of the children of this container are leaves.

Equivalent to:

all(c.is_leaf for c in self)

Returns:: True if all children are leaves.
Return type:: bool

calculate_total_size() → int

Calculates the size of this node. This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

children() → Sequence[TreeNode]

The children of this node.

Equivalent to:

list(self)

copy() → T: Creates a deep copy of this node

copy_from(children: Iterable[TreeNode]) → T: Constructs a new instance of this tree node from a list of its children

dfs() → Iterator[TreeNode]

Performs a depth-first traversal over all of this node’s descendants.

self is always included and yielded first.

This implementation is equivalent to:

stack = [self]
while stack:
    node = stack.pop()
    yield node
    stack.extend(reversed(node.children()))

diff(node: TreeNode) → EditedTreeNode | T

Performs a diff against the provided node.

Parameters:: node – The node against which to perform the diff.
Returns:: An edited version of this node with all edits being completed.
Return type:: Union[EditedTreeNode, T]

editable_dict() → Dict[str, Any]

Copies self.__dict__, calling TreeNode.editable_dict() on any TreeNode objects therein.

This is equivalent to:

ret = dict(self.__dict__)
if not self.is_leaf:
    for key, value in ret.items():
        if isinstance(value, TreeNode):
            ret[key] = value.make_edited()
return ret

This is used by TreeNode.make_edited().

property edited: bool

Returns whether this node has been edited.

The default implementation returns False, whereas EditedTreeNode.edited() returns True.

edits(node: TreeNode) → Edit

Calculates the best edit to transform this node into the provided node.

Parameters:: node – The node to which to transform.
Returns:: The best possible edit.
Return type:: Edit

from_name: StringNode

get_all_edit_contexts(node: TreeNode) → Iterator[Tuple[Tuple[TreeNode, ...], Edit]]

Returns an iterator over all edit contexts that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over pairs of paths from node to the edited node, as well as its edit. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Tuple[Tuple[“TreeNode”, …], Edit]

get_all_edits(node: TreeNode) → Iterator[Edit]

Returns an iterator over all edits that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over edits. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Edit]

property is_leaf: bool

Container nodes are never leaves, even if they have no children.

Returns:: False
Return type:: bool

items() → Iterator[Tuple[str, TreeNode]]

make_edited() → EditedTreeNode | T

Returns a new, copied instance of this node that is also an instance of EditedTreeNode.

This is equivalent to:

return self.__class__.edited_type()(self)

Returns:: A copied version of this node that is also an instance of EditedTreeNode and thereby mutable.
Return type:: Union[EditedTreeNode, T]

names: ListNode

property parent: TreeNode | None

The parent node of this node, or None if it has no parent.

The setter for this property should only be called by the parent node setting itself as the parent of its child.

ContainerNode subclasses automatically set this property for all of their children. However, if you define a subclass of TreeNode does not extend off of ContainerNode and for which len(self.children()) > 0, then each child’s parent must be set.

post_init()

Callback called after this class’s members have been initialized.

This callback should not call super().post_init(). Each superclass’s post_init() will be automatically called in order of the __mro__.

print(printer: Printer): Prints this node.

print_parent_context(printer: Printer, for_child: TreeNode)

Prints the context for the given child node.

For example, if this node represents a list and the child is the element at index 3, then “[3]” might be printed.

The child is expected to be one of this node’s children, but this is not validated.

The default implementation prints nothing.

to_obj()

Returns a pure Python representation of this node.

For example, a node representing a list, like graphtage.ListNode, should return a Python list. A node representing a mapping, like graphtage.MappingNode, should return a Python dict. Container nodes should recursively call TreeNode.to_obj() on all of their children.

This is used solely for the providing objects to operate on in the commandline expressions evaluation, for options like –match-if and –match-unless.

property total_size: int

The size of this node.

This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

The first time this property is called, its value will be set and memoized by calling TreeNode.calculate_total_size().

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

KeywordArgument

class graphtage.ast.KeywordArgument(key: LeafNode, value: TreeNode, allow_key_edits: bool = True)

Bases: KeyValuePairNode

__eq__(other)

Tests whether this key/value pair equals another.

Equivalent to:

isinstance(other, KeyValuePair) and self.key == other.key and self.value == other.value

Parameters:: other – The object to test.
Returns:: True if this key/value pair is equal to other.
Return type:: bool

__init__(key: LeafNode, value: TreeNode, allow_key_edits: bool = True)

Creates a new key/value pair node.

Parameters:

key – The key of the pair.
value – The value of the pair.
allow_key_edits – If False, only consider matching against another key/value pair node if it has the same key.

__lt__(other)

Compares this key/value pair to another.

If other is also an instance of KeyValuePairNode, return:

(self.key < other.key) or (self.key == other.key and self.value < other.value)

otherwise, return:

self.key < other

Parameters:: other – The object to which to compare.
Returns:: True if this key/value pair is smaller than other.
Return type:: bool

add_edit_modifier(modifier: Callable[[TreeNode, TreeNode], Edit | None])

all_children_are_leaves() → bool

Tests whether all of the children of this container are leaves.

Equivalent to:

all(c.is_leaf for c in self)

Returns:: True if all children are leaves.
Return type:: bool

calculate_total_size()

Calculates the size of this node. This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

children() → Tuple[LeafNode, TreeNode]

The children of this node.

Equivalent to:

list(self)

copy() → T: Creates a deep copy of this node

copy_from(children: Iterable[TreeNode]) → T: Constructs a new instance of this tree node from a list of its children

dfs() → Iterator[TreeNode]

Performs a depth-first traversal over all of this node’s descendants.

self is always included and yielded first.

This implementation is equivalent to:

stack = [self]
while stack:
    node = stack.pop()
    yield node
    stack.extend(reversed(node.children()))

diff(node: TreeNode) → EditedTreeNode | T

Performs a diff against the provided node.

Parameters:: node – The node against which to perform the diff.
Returns:: An edited version of this node with all edits being completed.
Return type:: Union[EditedTreeNode, T]

editable_dict() → Dict[str, Any]

Copies self.__dict__, calling TreeNode.editable_dict() on any TreeNode objects therein.

This is equivalent to:

ret = dict(self.__dict__)
if not self.is_leaf:
    for key, value in ret.items():
        if isinstance(value, TreeNode):
            ret[key] = value.make_edited()
return ret

This is used by TreeNode.make_edited().

property edited: bool

Returns whether this node has been edited.

The default implementation returns False, whereas EditedTreeNode.edited() returns True.

edits(node: TreeNode) → Edit

Calculates the best edit to transform this node into the provided node.

Parameters:: node – The node to which to transform.
Returns:: The best possible edit.
Return type:: Edit

get_all_edit_contexts(node: TreeNode) → Iterator[Tuple[Tuple[TreeNode, ...], Edit]]

Returns an iterator over all edit contexts that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over pairs of paths from node to the edited node, as well as its edit. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Tuple[Tuple[“TreeNode”, …], Edit]

get_all_edits(node: TreeNode) → Iterator[Edit]

Returns an iterator over all edits that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over edits. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Edit]

property is_leaf: bool

Container nodes are never leaves, even if they have no children.

Returns:: False
Return type:: bool

make_edited() → EditedTreeNode | T

Returns a new, copied instance of this node that is also an instance of EditedTreeNode.

This is equivalent to:

return self.__class__.edited_type()(self)

Returns:: A copied version of this node that is also an instance of EditedTreeNode and thereby mutable.
Return type:: Union[EditedTreeNode, T]

property parent: TreeNode | None

The parent node of this node, or None if it has no parent.

The setter for this property should only be called by the parent node setting itself as the parent of its child.

ContainerNode subclasses automatically set this property for all of their children. However, if you define a subclass of TreeNode does not extend off of ContainerNode and for which len(self.children()) > 0, then each child’s parent must be set.

print(printer: Printer)

Prints this node.

This default implementation prints the key in blue, followed by a bright white “: “, followed by the value.

print_parent_context(printer: Printer, for_child: TreeNode)

Prints the context for the given child node.

For example, if this node represents a list and the child is the element at index 3, then “[3]” might be printed.

The child is expected to be one of this node’s children, but this is not validated.

The default implementation prints nothing.

to_obj()

Returns a pure Python representation of this node.

For example, a node representing a list, like graphtage.ListNode, should return a Python list. A node representing a mapping, like graphtage.MappingNode, should return a Python dict. Container nodes should recursively call TreeNode.to_obj() on all of their children.

This is used solely for the providing objects to operate on in the commandline expressions evaluation, for options like –match-if and –match-unless.

property total_size: int

The size of this node.

This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

The first time this property is called, its value will be set and memoized by calling TreeNode.calculate_total_size().

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

Module

class graphtage.ast.Module(nodes: Iterable[T], allow_list_edits: bool = True, allow_list_edits_when_same_length: bool = True)

Bases: ListNode

__init__(nodes: Iterable[T], allow_list_edits: bool = True, allow_list_edits_when_same_length: bool = True)

Initializes a List node.

Parameters:

nodes – The set of nodes in this list.
allow_list_edits – Whether to consider removal and insertion when editing this list.
allow_list_edits_when_same_length – Whether to consider removal and insertion when comparing this list to another list of the same length.

__iter__() → Iterator[TreeNode]

Iterates over this sequence’s child nodes.

This is equivalent to:

return iter(self._children)

__len__() → int

The number of children of this sequence.

This is equivalent to:

return len(self._children)

add_edit_modifier(modifier: Callable[[TreeNode, TreeNode], Edit | None])

all_children_are_leaves() → bool

Tests whether all of the children of this container are leaves.

Equivalent to:

all(c.is_leaf for c in self)

Returns:: True if all children are leaves.
Return type:: bool

calculate_total_size()

Calculates the total size of this sequence.

This is equivalent to:

return sum(c.total_size for c in self)

children() → Sequence[TreeNode]

The children of this node.

Equivalent to:

list(self)

property container_type: Type[Tuple[T, ...]]

The container type required by graphtage.sequences.SequenceNode

Returns:: tuple
Return type:: Type[Tuple[T, …]]

copy() → T: Creates a deep copy of this node

copy_from(children: Iterable[TreeNode]) → C: Constructs a new instance of this tree node from a list of its children

dfs() → Iterator[TreeNode]

Performs a depth-first traversal over all of this node’s descendants.

self is always included and yielded first.

This implementation is equivalent to:

stack = [self]
while stack:
    node = stack.pop()
    yield node
    stack.extend(reversed(node.children()))

diff(node: TreeNode) → EditedTreeNode | T

Performs a diff against the provided node.

Parameters:: node – The node against which to perform the diff.
Returns:: An edited version of this node with all edits being completed.
Return type:: Union[EditedTreeNode, T]

editable_dict() → Dict[str, Any]

Copies self.__dict__, calling TreeNode.editable_dict() on all children.

This is equivalent to:

ret = dict(self.__dict__)
ret['_children'] = self.container_type(n.make_edited() for n in self)
return ret

This is used by SequenceNode.make_edited().

property edited: bool

Returns whether this node has been edited.

The default implementation returns False, whereas EditedTreeNode.edited() returns True.

edits(node: TreeNode) → Edit

Calculates the best edit to transform this node into the provided node.

Parameters:: node – The node to which to transform.
Returns:: The best possible edit.
Return type:: Edit

get_all_edit_contexts(node: TreeNode) → Iterator[Tuple[Tuple[TreeNode, ...], Edit]]

Returns an iterator over all edit contexts that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over pairs of paths from node to the edited node, as well as its edit. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Tuple[Tuple[“TreeNode”, …], Edit]

get_all_edits(node: TreeNode) → Iterator[Edit]

Returns an iterator over all edits that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over edits. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Edit]

property is_leaf: bool

Container nodes are never leaves, even if they have no children.

Returns:: False
Return type:: bool

make_edited() → EditedTreeNode | T

Returns a new, copied instance of this node that is also an instance of EditedTreeNode.

This is equivalent to:

return self.__class__.edited_type()(self)

Returns:: A copied version of this node that is also an instance of EditedTreeNode and thereby mutable.
Return type:: Union[EditedTreeNode, T]

property parent: TreeNode | None

The parent node of this node, or None if it has no parent.

The setter for this property should only be called by the parent node setting itself as the parent of its child.

ContainerNode subclasses automatically set this property for all of their children. However, if you define a subclass of TreeNode does not extend off of ContainerNode and for which len(self.children()) > 0, then each child’s parent must be set.

print(printer: Printer)

Prints a sequence node.

By default, sequence nodes are printed like lists:

SequenceFormatter('[', ']', ',').print(printer, self)

print_parent_context(printer: Printer, for_child: TreeNode)

Prints the context for the given child node.

For example, if this node represents a list and the child is the element at index 3, then “[3]” might be printed.

The child is expected to be one of this node’s children, but this is not validated.

The default implementation prints nothing.

to_obj()

Returns a pure Python representation of this node.

For example, a node representing a list, like graphtage.ListNode, should return a Python list. A node representing a mapping, like graphtage.MappingNode, should return a Python dict. Container nodes should recursively call TreeNode.to_obj() on all of their children.

This is used solely for the providing objects to operate on in the commandline expressions evaluation, for options like –match-if and –match-unless.

property total_size: int

The size of this node.

This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

The first time this property is called, its value will be set and memoized by calling TreeNode.calculate_total_size().

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

Subscript

class graphtage.ast.Subscript(*args, **kwargs)

Bases: DataClassNode

A node representing an object subscript (i.e., the [] operator)

__init__(*args, **kwargs): Be careful extending __init__; consider using DataClassNode.post_init() instead.

add_edit_modifier(modifier: Callable[[TreeNode, TreeNode], Edit | None])

all_children_are_leaves() → bool

Tests whether all of the children of this container are leaves.

Equivalent to:

all(c.is_leaf for c in self)

Returns:: True if all children are leaves.
Return type:: bool

calculate_total_size() → int

Calculates the size of this node. This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

children() → Sequence[TreeNode]

The children of this node.

Equivalent to:

list(self)

copy() → T: Creates a deep copy of this node

copy_from(children: Iterable[TreeNode]) → T: Constructs a new instance of this tree node from a list of its children

dfs() → Iterator[TreeNode]

Performs a depth-first traversal over all of this node’s descendants.

self is always included and yielded first.

This implementation is equivalent to:

stack = [self]
while stack:
    node = stack.pop()
    yield node
    stack.extend(reversed(node.children()))

diff(node: TreeNode) → EditedTreeNode | T

Performs a diff against the provided node.

Parameters:: node – The node against which to perform the diff.
Returns:: An edited version of this node with all edits being completed.
Return type:: Union[EditedTreeNode, T]

editable_dict() → Dict[str, Any]

Copies self.__dict__, calling TreeNode.editable_dict() on any TreeNode objects therein.

This is equivalent to:

ret = dict(self.__dict__)
if not self.is_leaf:
    for key, value in ret.items():
        if isinstance(value, TreeNode):
            ret[key] = value.make_edited()
return ret

This is used by TreeNode.make_edited().

property edited: bool

Returns whether this node has been edited.

The default implementation returns False, whereas EditedTreeNode.edited() returns True.

edits(node: TreeNode) → Edit

Calculates the best edit to transform this node into the provided node.

Parameters:: node – The node to which to transform.
Returns:: The best possible edit.
Return type:: Edit

get_all_edit_contexts(node: TreeNode) → Iterator[Tuple[Tuple[TreeNode, ...], Edit]]

Returns an iterator over all edit contexts that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over pairs of paths from node to the edited node, as well as its edit. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Tuple[Tuple[“TreeNode”, …], Edit]

get_all_edits(node: TreeNode) → Iterator[Edit]

Returns an iterator over all edits that will transform this node into the provided node.

Parameters:: node – The node to which to transform this one.
Returns:: An iterator over edits. Note that this iterator will automatically explode any CompoundEdit in the sequence.
Return type:: Iterator[Edit]

property is_leaf: bool

Container nodes are never leaves, even if they have no children.

Returns:: False
Return type:: bool

items() → Iterator[Tuple[str, TreeNode]]

make_edited() → EditedTreeNode | T

Returns a new, copied instance of this node that is also an instance of EditedTreeNode.

This is equivalent to:

return self.__class__.edited_type()(self)

Returns:: A copied version of this node that is also an instance of EditedTreeNode and thereby mutable.
Return type:: Union[EditedTreeNode, T]

property parent: TreeNode | None

The parent node of this node, or None if it has no parent.

The setter for this property should only be called by the parent node setting itself as the parent of its child.

ContainerNode subclasses automatically set this property for all of their children. However, if you define a subclass of TreeNode does not extend off of ContainerNode and for which len(self.children()) > 0, then each child’s parent must be set.

post_init()

Callback called after this class’s members have been initialized.

This callback should not call super().post_init(). Each superclass’s post_init() will be automatically called in order of the __mro__.

print(printer: Printer): Prints this node.

print_parent_context(printer: Printer, for_child: TreeNode)

Prints the context for the given child node.

For example, if this node represents a list and the child is the element at index 3, then “[3]” might be printed.

The child is expected to be one of this node’s children, but this is not validated.

The default implementation prints nothing.

slice: TreeNode

to_obj()

Returns a pure Python representation of this node.

For example, a node representing a list, like graphtage.ListNode, should return a Python list. A node representing a mapping, like graphtage.MappingNode, should return a Python dict. Container nodes should recursively call TreeNode.to_obj() on all of their children.

This is used solely for the providing objects to operate on in the commandline expressions evaluation, for options like –match-if and –match-unless.

property total_size: int

The size of this node.

This is an arbitrary, immutable value that is used to calculate the bounded costs of edits on this node.

The first time this property is called, its value will be set and memoized by calling TreeNode.calculate_total_size().

Returns:: An arbitrary integer representing the size of this node.
Return type:: int

value: TreeNode