graphtage.toml

toml classes

TOML

class graphtage.toml.TOML

Bases: Filetype

The TOML filetype.

__init__()

Initializes the TOML filetype.

TOML identifies itself with the MIME types application/toml and text/toml.

build_tree(path: str, options: BuildOptions | None = None) → TreeNode: Equivalent to build_tree()

build_tree_handling_errors(path: str, options: BuildOptions | None = None) → str | 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:

str | TreeNode

default_instance: Filetype = <graphtage.toml.TOML object>

get_default_formatter() → JSONFormatter: Returns the default formatter for printing files of this type.

TOMLFormatter

class graphtage.toml.TOMLFormatter(*args, **kwargs)

Bases: GraphtageFormatter

DEFAULT_INSTANCE: Formatter[T] = <graphtage.toml.TOMLFormatter object>: A default instance of this formatter, automatically instantiated by the FormatterChecker metaclass.

__init__()

static __new__(cls, *args, **kwargs) → Formatter[T]

Instantiates a new formatter.

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

_print_node(printer: Printer, node: TreeNode)

Hands a node to its formatter, suppressing that node’s edit for the duration of the call.

Whether to print node’s edit was already settled by GraphtageFormatter.print(), so any re-entrant call for the same node must print the bare node. See _NODES_BEING_PRINTED.

Parameters:

printer – The printer to which to write.
node – The node to print.

get_formatter(item: T) → Callable[[Printer, T], Any] | None

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

Equivalent to:

get_formatter(item.__class__, base_formatter=self)

property inline_tables: TOMLInlineTableFormatter

The sub-formatter for a mapping that has nowhere to write a [table] header.

The Formatting Protocol resolves a formatter from a node’s type alone, and a mapping written as a section and a mapping written inline are the same type, so this formatter selects between the two itself.

is_partial: bool = False

parent: Formatter[T] | None = None

The parent formatter for this formatter instance.

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

print(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. This is also implied to be :keyword:False while the node’s own formatter is on the stack, so that a formatter delegating the same node to a sibling formatter does not print its edit twice.

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: Printer, node: KeyValuePairNode)

print_LeafNode(printer: Printer, node: LeafNode)

print_MappingNode(printer: Printer, node: MappingNode)

property root: Formatter[T]: Returns the root formatter.

sub_format_types: Sequence[type[Formatter[T]]] = (<class 'graphtage.toml.TOMLTableFormatter'>, <class 'graphtage.toml.TOMLListFormatter'>, <class 'graphtage.toml.TOMLStringFormatter'>, <class 'graphtage.toml.TOMLInlineTableFormatter'>): 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.

property tables: TOMLTableFormatter: The sub-formatter for a mapping that is written as a [table] section.

write_key_value_pair(printer: Printer, node: KeyValuePairNode)

Writes key = value, without the newline that ends a line of a table body.

Parameters:

printer – The printer to which to write.
node – The key/value pair to write.

TOMLInlineTableFormatter

class graphtage.toml.TOMLInlineTableFormatter(*args, **kwargs)

Bases: SequenceFormatter

A sub-formatter for mappings that have nowhere to write a [table] header.

A mapping only gets a header when it is reached by walking down from the document root. One that appears in a value position has no such header available: the replaced side of an edit is printed inside the key = value line it belongs to, and a mapping nested in a list is printed inside the list. Both are written as TOML inline tables, {key = value, ...}, so that the value stays attached to its key.

DEFAULT_INSTANCE: Formatter[T] = <graphtage.toml.TOMLInlineTableFormatter object>: A default instance of this formatter, automatically instantiated by the FormatterChecker metaclass.

__init__()

Initializes the TOML inline table formatter.

Equivalent to:

super().__init__('{', '}', ',')

static __new__(cls, *args, **kwargs) → Formatter[T]

Instantiates a new formatter.

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

_print_node(printer: Printer, node: TreeNode)

Hands a node to its formatter, suppressing that node’s edit for the duration of the call.

Whether to print node’s edit was already settled by GraphtageFormatter.print(), so any re-entrant call for the same node must print the bare node. See _NODES_BEING_PRINTED.

Parameters:

printer – The printer to which to write.
node – The node to print.

delimiter_callback: Callable[[Printer], Any]

edit_print(printer: Printer, edit: 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) → Callable[[Printer, T], Any] | None

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: Printer, is_first: bool = False, is_last: bool = False): Separates two entries with a single space, since an inline table is written on one line.

items_indent(printer: Printer) → Printer: Returns printer itself, since an inline table writes no newline for an indent to apply to.

parent: Formatter[T] | None = None

The parent formatter for this formatter instance.

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

print(printer: Printer, node_or_edit: 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. This is also implied to be :keyword:False while the node’s own formatter is on the stack, so that a formatter delegating the same node to a sibling formatter does not print its edit twice.

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: Printer, node: KeyValuePairNode)

Prints one entry of an inline table.

This is TOMLFormatter.write_key_value_pair() without the newline that ends a top-level key = value line, which would otherwise break the inline table across lines.

print_MappingNode(*args, **kwargs)

Prints a graphtage.MappingNode.

Equivalent to:

super().print_SequenceNode(*args, **kwargs)

print_SequenceNode(*args, **kwargs)

Prints a non-mapping sequence.

This delegates to the parent formatter’s implementation:

self.parent.print(*args, **kwargs)

which should invoke TOMLFormatter.print(), thereby delegating to the TOMLListFormatter in instances where an inline table contains a list.

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

TOMLListFormatter

class graphtage.toml.TOMLListFormatter(*args, **kwargs)

Bases: SequenceFormatter

A sub-formatter for TOML lists.

DEFAULT_INSTANCE: Formatter[T] = <graphtage.toml.TOMLListFormatter object>: A default instance of this formatter, automatically instantiated by the FormatterChecker metaclass.

__init__()

Initializes the TOML list formatter.

Equivalent to:

super().__init__('[', ']', ',')

static __new__(cls, *args, **kwargs) → Formatter[T]

Instantiates a new formatter.

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

_print_node(printer: Printer, node: TreeNode)

Hands a node to its formatter, suppressing that node’s edit for the duration of the call.

Whether to print node’s edit was already settled by GraphtageFormatter.print(), so any re-entrant call for the same node must print the bare node. See _NODES_BEING_PRINTED.

Parameters:

printer – The printer to which to write.
node – The node to print.

delimiter_callback: Callable[[Printer], Any]

edit_print(printer: Printer, edit: 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) → Callable[[Printer, T], Any] | None

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: 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: 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: Formatter[T] | None = None

The parent formatter for this formatter instance.

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

print(printer: Printer, node_or_edit: 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. This is also implied to be :keyword:False while the node’s own formatter is on the stack, so that a formatter delegating the same node to a sibling formatter does not print its edit twice.

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(*args, **kwargs)

Prints a graphtage.ListNode.

Equivalent to:

super().print_SequenceNode(*args, **kwargs)

print_SequenceNode(*args, **kwargs)

Prints a non-List sequence.

This delegates to the parent formatter’s implementation:

self.parent.print(*args, **kwargs)

which should invoke TOMLFormatter.print(), thereby delegating to the TOMLInlineTableFormatter in instances where a list contains a dict.

print_UnorderedListNode(*args, **kwargs)

Prints a graphtage.ListNode.

Equivalent to:

super().print_SequenceNode(*args, **kwargs)

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

TOMLStringFormatter

class graphtage.toml.TOMLStringFormatter(*args, **kwargs)

Bases: StringFormatter

A TOML formatter for strings.

DEFAULT_INSTANCE: Formatter[T] = <graphtage.toml.TOMLStringFormatter object>: A default instance of this formatter, automatically instantiated by the FormatterChecker metaclass.

__init__()

static __new__(cls, *args, **kwargs) → Formatter[T]

Instantiates a new formatter.

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

_print_node(printer: Printer, node: TreeNode)

Hands a node to its formatter, suppressing that node’s edit for the duration of the call.

Whether to print node’s edit was already settled by GraphtageFormatter.print(), so any re-entrant call for the same node must print the bare node. See _NODES_BEING_PRINTED.

Parameters:

printer – The printer to which to write.
node – The node to print.

context(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) → Callable[[Printer, T], Any] | None

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

is_quoted: bool = False

parent: 'Formatter[T]' | None = None

The parent formatter for this formatter instance.

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

print(printer: Printer, node_or_edit: 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. This is also implied to be :keyword:False while the node’s own formatter is on the stack, so that a formatter delegating the same node to a sibling formatter does not print its edit twice.

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: Printer, edit: StringEdit)

print_StringNode(printer: Printer, node: StringNode)

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

write_char(printer: Printer, c: str | int, 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: Printer, edit: StringEdit): Prints an ending quote for the string, if necessary

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

TOMLTableFormatter

class graphtage.toml.TOMLTableFormatter(*args, **kwargs)

Bases: SequenceFormatter

A sub-formatter for a TOML document and for every [table] section within it.

Every pair is written through SequenceFormatter.print_SequenceNode(), which is where an inserted or removed pair is wrapped in its edit markup. A pair that becomes a section of its own is held back until the rest of its table has been written, because TOML reads every key = value line that follows a header as part of that header’s table.

DEFAULT_INSTANCE: Formatter[T] = <graphtage.toml.TOMLTableFormatter object>: A default instance of this formatter, automatically instantiated by the FormatterChecker metaclass.

__init__()

Initializes the TOML table formatter.

Equivalent to:

super().__init__('', '', '')

static __new__(cls, *args, **kwargs) → Formatter[T]

Instantiates a new formatter.

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

_print_node(printer: Printer, node: TreeNode)

Hands a node to its formatter, suppressing that node’s edit for the duration of the call.

Whether to print node’s edit was already settled by GraphtageFormatter.print(), so any re-entrant call for the same node must print the bare node. See _NODES_BEING_PRINTED.

Parameters:

printer – The printer to which to write.
node – The node to print.

delimiter_callback: Callable[[Printer], Any]

edit_print(printer: Printer, edit: Edit)

Writes one pair of a table, holding back any pair that becomes a [table] section of its own.

Parameters:

printer – The printer to which to write.
edit – The edit for the pair, which is a graphtage.Match when the table is not edited.

get_formatter(item: T) → Callable[[Printer, T], Any] | None

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: Printer, is_first: bool = False, is_last: bool = False): Writes nothing, since every line of a table body already ends itself.

items_indent(printer: Printer) → Printer: Returns printer itself, since TOML does not indent a table body under its header.

parent: Formatter[T] | None = None

The parent formatter for this formatter instance.

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

print(printer: Printer, node_or_edit: 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. This is also implied to be :keyword:False while the node’s own formatter is on the stack, so that a formatter delegating the same node to a sibling formatter does not print its edit twice.

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: Printer, node: KeyValuePairNode)

Writes one entry of a table, either as a key = value line or as a [table] section of its own.

Parameters:

printer – The printer to which to write.
node – The key/value pair to write.

print_MappingNode(printer: Printer, node: MappingNode)

Writes a TOML document, or one [table] section and the sections nested within it.

Parameters:

printer – The printer to which to write.
node – The document root, or the value of the pair that names this section.

print_SequenceNode(*args, **kwargs)

Prints a non-mapping sequence.

This delegates to the parent formatter’s implementation:

self.parent.print(*args, **kwargs)

which should invoke TOMLFormatter.print(), thereby delegating to the TOMLListFormatter in instances where a table contains a list.

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

write_header(printer: Printer)

Writes the [dotted.name] header of the section that is currently being written.

Parameters:: printer – The printer to which to write.

toml functions

build_tree

graphtage.toml.build_tree(path: str, options: BuildOptions | None) → TreeNode

is_table

graphtage.toml.is_table(kvp: KeyValuePairNode) → bool

Returns whether a key/value pair is written as a [table] section rather than as key = value.

Only a pair whose value is a mapping can have a section of its own, and only if no edit replaces that mapping with a value of another type. A section body has nowhere to write such a replacement, so classifying the pair as a section would drop its edit from the output entirely.

Parameters:: kvp – The key/value pair to classify.
Returns:: True if kvp is written as its own [table] section, and False if it is written inline as key = value.
Return type:: bool

key_value_pairs

graphtage.toml.key_value_pairs(mapping: MappingNode) → Iterator[KeyValuePairNode]

Iterates over a mapping’s key/value pairs, including any that an edit inserts into it.

Parameters:: mapping – The mapping whose pairs to enumerate.
Returns:: Every pair the mapping renders. An inserted pair belongs to the other document, so it is not among the mapping’s own children.
Return type:: Iterator[KeyValuePairNode]

toml_dumps

graphtage.toml.toml_dumps(obj) → str

writes_own_section

graphtage.toml.writes_own_section(mapping: MappingNode) → bool

Returns whether a mapping is written as a section of its own rather than only as a name prefix.

A mapping whose every pair is itself a [table] writes nothing between its own header and the first header below it, so the header is omitted and the sub-tables carry the whole dotted name. An empty mapping still needs a header of its own, since it would otherwise leave no trace in the output.

Parameters:: mapping – The mapping to classify.
Returns:: True if mapping writes a header and a body of its own.
Return type:: bool