graphtage.plist

A graphtage.Filetype for parsing, diffing, and rendering Apple plist files.

plist classes

PLIST

class graphtage.plist.PLIST

Bases: graphtage.Filetype

The Apple PLIST filetype.

__init__()

Initializes the PLIST file type.

By default, PLIST associates itself with the “plist” and “application/x-plist” MIME types.

build_tree(path: str, options: Optional[graphtage.BuildOptions] = None) graphtage.TreeNode

Builds an intermediate representation tree from a file of this Filetype.

Parameters
  • path – Path to the file to parse

  • options – An optional set of options for building the tree

Returns

The root tree node of the provided file

Return type

TreeNode

build_tree_handling_errors(path: str, options: Optional[graphtage.BuildOptions] = None) Union[str, graphtage.TreeNode]

Same as Filetype.build_tree(), but it should return a human-readable error string on failure.

This function should never throw an exception.

Parameters
  • path – Path to the file to parse

  • options – An optional set of options for building the tree

Returns

On success, the root tree node, or a string containing the error message on failure.

Return type

Union[str, TreeNode]

get_default_formatter() graphtage.plist.PLISTFormatter

Returns the default formatter for printing files of this type.

PLISTFormatter

class graphtage.plist.PLISTFormatter(*args, **kwargs)

Bases: graphtage.GraphtageFormatter

DEFAULT_INSTANCE: Formatter[T] = <graphtage.plist.PLISTFormatter object>

A default instance of this formatter, automatically instantiated by the FormatterChecker metaclass.

__init__()
static __new__(cls, *args, **kwargs) graphtage.formatter.Formatter[graphtage.formatter.T]

Instantiates a new formatter.

This automatically instantiates and populates Formatter.sub_formatters and sets their parent to this new formatter.

get_formatter(item: graphtage.formatter.T) Optional[Callable[[graphtage.printer.Printer, graphtage.formatter.T], Any]]

Looks up a formatter for the given item using this formatter as a base.

Equivalent to:

get_formatter(item.__class__, base_formatter=self)
is_partial: bool = False
parent: Optional[Formatter[T]] = None

The parent formatter for this formatter instance.

This is automatically populated by Formatter.__new__() and should never be manually modified.

print(printer: graphtage.printer.Printer, *args, **kwargs)

Prints the given node or edit.

Parameters
  • printer – The printer to which to write.

  • node_or_edit – The node or edit to print.

  • with_edits – If :keyword:True, print any edits associated with the node.

Note

The protocol for determining how a node or edit should be printed is very complex due to its extensibility. See the Printing Protocol for a detailed description.

print_BoolNode(printer, node: graphtage.BoolNode)
print_FloatNode(printer: graphtage.printer.Printer, node: graphtage.FloatNode)
print_IntegerNode(printer: graphtage.printer.Printer, node: graphtage.IntegerNode)
print_LeafNode(printer: graphtage.printer.Printer, node: graphtage.LeafNode)
print_PLISTNode(printer: graphtage.printer.Printer, node: graphtage.plist.PLISTNode)
print_StringNode(printer: graphtage.printer.Printer, node: graphtage.StringNode)
property root: graphtage.formatter.Formatter[graphtage.formatter.T]

Returns the root formatter.

sub_format_types: Sequence[Type[Formatter[T]]] = [<class 'graphtage.plist.PLISTSequenceFormatter'>]

A list of formatter types that should be used as sub-formatters in the Formatting Protocol.

sub_formatters: List[Formatter[T]] = []

The list of instantiated formatters corresponding to Formatter.sub_format_types.

This list is automatically populated by Formatter.__new__() and should never be manually modified.

static write_obj(printer: graphtage.printer.Printer, obj)

PLISTNode

class graphtage.plist.PLISTNode(root: graphtage.TreeNode)

Bases: graphtage.ContainerNode

__init__(root: graphtage.TreeNode)
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() List[graphtage.TreeNode]

The children of this node.

Equivalent to:

list(self)
dfs() Iterator[graphtage.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: graphtage.TreeNode) Union[graphtage.EditedTreeNode, graphtage.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]

edit_modifiers: Optional[List[Callable[[graphtage.TreeNode, graphtage.TreeNode], Optional[graphtage.Edit]]]] = None
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.

classmethod edited_type() Type[Union[graphtage.EditedTreeNode, graphtage.T]]

Dynamically constructs a new class that is both a TreeNode and an EditedTreeNode.

The edited type’s member variables are populated by the result of TreeNode.editable_dict() of the TreeNode it wraps:

new_node.__dict__ = dict(wrapped_tree_node.editable_dict())
Returns

A class that is both a TreeNode and an EditedTreeNode. Its constructor accepts a TreeNode that it will wrap.

Return type

Type[Union[EditedTreeNode, T]]

edits(node: graphtage.TreeNode) graphtage.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_edits(node: graphtage.TreeNode) Iterator[graphtage.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() Union[graphtage.EditedTreeNode, graphtage.T]

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

This is equivalent to:

return self.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]

print(printer: graphtage.printer.Printer)

Prints this node.

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

PLISTSequenceFormatter

class graphtage.plist.PLISTSequenceFormatter(*args, **kwargs)

Bases: graphtage.sequences.SequenceFormatter

DEFAULT_INSTANCE: Formatter[T] = <graphtage.plist.PLISTSequenceFormatter object>

A default instance of this formatter, automatically instantiated by the FormatterChecker metaclass.

__init__()

Initializes a sequence formatter.

Parameters
  • start_symbol – The symbol to print at the start of the sequence.

  • end_symbol – The symbol to print at the end of the sequence.

  • delimiter – A delimiter to print between items.

  • delimiter_callback

    A callback for when a delimiter is to be printed. If omitted, this defaults to:

    lambda p: p.write(delimiter)
    

static __new__(cls, *args, **kwargs) graphtage.formatter.Formatter[graphtage.formatter.T]

Instantiates a new formatter.

This automatically instantiates and populates Formatter.sub_formatters and sets their parent to this new formatter.

edit_print(printer: graphtage.printer.Printer, edit: graphtage.Edit)

Called when the edit for an item is to be printed.

If the SequenceNode being printed either is not edited or has no edits, then the edit passed to this function will be a Match(child, child, 0).

This implementation simply delegates the print to the Formatting Protocol:

self.print(printer, edit)
get_formatter(item: graphtage.formatter.T) Optional[Callable[[graphtage.printer.Printer, graphtage.formatter.T], Any]]

Looks up a formatter for the given item using this formatter as a base.

Equivalent to:

get_formatter(item.__class__, base_formatter=self)
is_partial: bool = True

This is a partial formatter; it will not be automatically used in the Formatting Protocol.

item_newline(printer: graphtage.printer.Printer, is_first: bool = False, is_last: bool = False)

Called before each node is printed.

This is also called one extra time after the last node, if there is at least one node printed.

The default implementation is simply:

printer.newline()
items_indent(printer: graphtage.printer.Printer) graphtage.printer.Printer

Returns a Printer context with an indentation.

This is called as:

with self.items_indent(printer) as p:

immediately after the self.start_symbol is printed, but before any of the items have been printed.

This default implementation is equivalent to:

return printer.indent()
parent: Optional[Formatter[T]] = None

The parent formatter for this formatter instance.

This is automatically populated by Formatter.__new__() and should never be manually modified.

print(printer: graphtage.printer.Printer, node_or_edit: Union[graphtage.TreeNode, graphtage.Edit], with_edits: bool = True)

Prints the given node or edit.

Parameters
  • printer – The printer to which to write.

  • node_or_edit – The node or edit to print.

  • with_edits – If :keyword:True, print any edits associated with the node.

Note

The protocol for determining how a node or edit should be printed is very complex due to its extensibility. See the Printing Protocol for a detailed description.

print_KeyValuePairNode(printer: graphtage.printer.Printer, node: graphtage.KeyValuePairNode)
print_ListNode(printer: graphtage.printer.Printer, *args, **kwargs)
print_MappingNode(printer: graphtage.printer.Printer, *args, **kwargs)
print_MultiSetNode(printer: graphtage.printer.Printer, *args, **kwargs)
print_SequenceNode(printer: graphtage.printer.Printer, node: graphtage.sequences.SequenceNode)

Formats a sequence node.

The protocol for this function is as follows:

  • Print self.start_symbol

  • With the printer returned by self.items_indent:
    • For each edit in the sequence (or just a sequence of graphtage.Match for each child, if the node is not edited):
      • Call self.item_newline(printer, is_first=index == 0)

      • Call self.edit_print(printer, edit)

  • If at least one edit was printed, then call self.item_newline(printer, is_last=True)

  • Print self.start_symbol

property root: graphtage.formatter.Formatter[graphtage.formatter.T]

Returns the root formatter.

sub_format_types: Sequence[Type[Formatter[T]]] = ()

A list of formatter types that should be used as sub-formatters in the Formatting Protocol.

sub_formatters: List[Formatter[T]] = []

The list of instantiated formatters corresponding to Formatter.sub_format_types.

This list is automatically populated by Formatter.__new__() and should never be manually modified.

plist functions

build_tree

graphtage.plist.build_tree(path: str, options: Optional[graphtage.BuildOptions] = None, *args, **kwargs) graphtage.plist.PLISTNode

Constructs a PLIST tree from an PLIST file.