graphtage.yaml¶

A graphtage.Filetype for parsing, diffing, and rendering YAML files.

yaml classes¶

YAML¶

class graphtage.yaml.YAML¶

Bases: graphtage.Filetype

The YAML filetype.

__init__()¶

Initializes the YAML file type.

By default, YAML associates itself with the “yaml”, “application/x-yaml”, “application/yaml”, “text/yaml”, “text/x-yaml”, and “text/vnd.yaml” 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.yaml.YAMLFormatter ¶: Returns the default formatter for printing files of this type.

YAMLDictFormatter¶

class graphtage.yaml.YAMLDictFormatter(*args, **kwargs)¶

Bases: graphtage.sequences.SequenceFormatter

DEFAULT_INSTANCE: graphtage.formatter.Formatter[T] = <graphtage.yaml.YAMLDictFormatter object>¶

__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[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: T) → Optional[Callable[[graphtage.printer.Printer, 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¶

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)¶

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[graphtage.formatter.Formatter[T]] = None¶

print(printer: graphtage.printer.Printer, node_or_edit: Union[TreeNode, 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_MappingNode(*args, **kwargs)¶

print_MultiSetNode(*args, **kwargs)¶

print_SequenceNode(*args, **kwargs)¶

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¶: Returns the root formatter.

sub_format_types: Sequence[Type[graphtage.formatter.Formatter[T]]] = [<class 'graphtage.yaml.YAMLKeyValuePairFormatter'>]¶

sub_formatters: List[graphtage.formatter.Formatter[T]] = []¶

YAMLFormatter¶

class graphtage.yaml.YAMLFormatter(*args, **kwargs)¶

Bases: graphtage.GraphtageFormatter

DEFAULT_INSTANCE: graphtage.formatter.Formatter[T] = <graphtage.yaml.YAMLFormatter object>¶

__init__()¶: Initialize self. See help(type(self)) for accurate signature.

static __new__(cls, *args, **kwargs) → graphtage.formatter.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: T) → Optional[Callable[[graphtage.printer.Printer, 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[graphtage.formatter.Formatter[T]] = None¶

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_ContainerNode(printer: graphtage.printer.Printer, node: graphtage.ContainerNode)¶

Prints a graphtage.ContainerNode.

This is a fallback to permit the printing of custom containers, like graphtage.xml.XMLElement.

print_LeafNode(printer: graphtage.printer.Printer, node: graphtage.LeafNode)¶

property root¶: Returns the root formatter.

sub_format_types: Sequence[Type[graphtage.formatter.Formatter[T]]] = [<class 'graphtage.yaml.YAMLStringFormatter'>, <class 'graphtage.yaml.YAMLDictFormatter'>, <class 'graphtage.yaml.YAMLListFormatter'>]¶

sub_formatters: List[graphtage.formatter.Formatter[T]] = []¶

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

YAMLKeyValuePairFormatter¶

class graphtage.yaml.YAMLKeyValuePairFormatter(*args, **kwargs)¶

Bases: graphtage.GraphtageFormatter

DEFAULT_INSTANCE: graphtage.formatter.Formatter[T] = <graphtage.yaml.YAMLKeyValuePairFormatter object>¶

__init__()¶: Initialize self. See help(type(self)) for accurate signature.

static __new__(cls, *args, **kwargs) → graphtage.formatter.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: T) → Optional[Callable[[graphtage.printer.Printer, 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¶

parent: Optional[graphtage.formatter.Formatter[T]] = None¶

print(printer: graphtage.printer.Printer, node_or_edit: Union[TreeNode, 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)¶

property root¶: Returns the root formatter.

sub_format_types: Sequence[Type[graphtage.formatter.Formatter[T]]] = ()¶

sub_formatters: List[graphtage.formatter.Formatter[T]] = []¶

YAMLListFormatter¶

class graphtage.yaml.YAMLListFormatter(*args, **kwargs)¶

Bases: graphtage.sequences.SequenceFormatter

DEFAULT_INSTANCE: graphtage.formatter.Formatter[T] = <graphtage.yaml.YAMLListFormatter object>¶

__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[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: T) → Optional[Callable[[graphtage.printer.Printer, 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¶

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)¶

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[graphtage.formatter.Formatter[T]] = None¶

print(printer: graphtage.printer.Printer, node_or_edit: Union[TreeNode, 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_ListNode(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¶: Returns the root formatter.

sub_format_types: Sequence[Type[graphtage.formatter.Formatter[T]]] = ()¶

sub_formatters: List[graphtage.formatter.Formatter[T]] = []¶

YAMLStringFormatter¶

class graphtage.yaml.YAMLStringFormatter(*args, **kwargs)¶

Bases: graphtage.StringFormatter

DEFAULT_INSTANCE: graphtage.formatter.Formatter[T] = <graphtage.yaml.YAMLStringFormatter object>¶

__init__()¶: Initialize self. See help(type(self)) for accurate signature.

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

Instantiates a new formatter.

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

context(printer: graphtage.printer.Printer)¶

escape(c: str) → str ¶

String escape.

This function is called once for each character in the string.

Returns: The escaped version of c, or c itself if no escaping is required.
Return type: str

get_formatter(item: T) → Optional[Callable[[graphtage.printer.Printer, 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)

has_newline = False¶

is_partial: bool = True¶

is_quoted: bool = False¶

parent: Optional[graphtage.formatter.Formatter[T]] = None¶

print(printer: graphtage.printer.Printer, node_or_edit: Union[TreeNode, 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_StringEdit(printer: graphtage.printer.Printer, edit: graphtage.StringEdit)¶

print_StringNode(printer: graphtage.printer.Printer, node: graphtage.StringNode)¶

property root¶: Returns the root formatter.

sub_format_types: Sequence[Type[graphtage.formatter.Formatter[T]]] = ()¶

sub_formatters: List[graphtage.formatter.Formatter[T]] = []¶

write_char(printer: graphtage.printer.Printer, c: str, index: int, num_edits: int, removed=False, inserted=False)¶

Writes a character to the printer.

Note

This function calls graphtage.StringFormatter.escape(); classes extending graphtage.StringFormatter should also call graphtage.StringFormatter.escape() when reimplementing this function.

Note

There is no need to specially format characters that have been removed or inserted; the printer will have already automatically been configured to format them prior to the call to StringFormatter.write_char().

Parameters

printer – The printer to which to write the character.
c – The character to write.
index – The index of the character in the string.
num_edits – The total number of characters that will be printed.
removed – Whether this character was removed from the source string.
inserted – Whether this character is inserted into the source string.

write_end_quote(printer: graphtage.printer.Printer, edit: graphtage.StringEdit)¶: Prints an ending quote for the string, if necessary

write_start_quote(printer: graphtage.printer.Printer, edit: graphtage.StringEdit)¶: Prints a starting quote for the string, if necessary

yaml functions¶

build_tree¶

graphtage.yaml.build_tree(path: str, options: Optional[graphtage.BuildOptions] = None, *args, **kwargs) → graphtage.TreeNode ¶: Constructs a YAML tree from an YAML file.