graphtage.json

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

json classes

JSON

class graphtage.json.JSON

Bases: Filetype

The JSON file type.

__init__()

Initializes the JSON file type.

By default, JSON associates itself with the “json”, “application/json”, “application/x-javascript”, “text/javascript”, “text/x-javascript”, and “text/x-json” MIME types.

build_tree(path: str, options: BuildOptions | None = None) → 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: 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.json.JSON object>
get_default_formatter() → JSONFormatter

Returns the default formatter for printing files of this type.

JSON5

class graphtage.json.JSON5

Bases: Filetype

The JSON5 file type.

__init__()

Initializes the JSON5 file type.

By default, JSON5 associates itself with the “json5”, “application/json5”, and “text/x-json5” MIME types.

build_tree(path: str, options: BuildOptions | None = None) → 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: 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.json.JSON5 object>
get_default_formatter() → JSONFormatter

Returns the default formatter for printing files of this type.

JSONDictFormatter

class graphtage.json.JSONDictFormatter(*args, **kwargs)

Bases: SequenceFormatter

A sub-formatter for JSON dicts.

DEFAULT_INSTANCE: Formatter[T] = <graphtage.json.JSONDictFormatter 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) → 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.

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 dict items.

A joined dict keeps all of its items on one line, separated by a single space so that the result reads as {"a": 1, "b": 2} rather than {"a": 1,"b": 2}.

items_indent(printer: Printer) → Printer

Returns the printer context in which the dict items are printed.

A joined dict emits no newlines of its own, so indenting its items would have no visible effect on the dict itself while still adding a level of indentation to any nested sequence that does break across lines.

Returns:

printer itself if the dict is joined, otherwise printer.indent().

Return type:

Printer

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

Prints a graphtage.MappingNode.

Equivalent to:

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

Prints a graphtage.MultiSetNode.

Equivalent to:

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

Prints a non-Dict sequence.

This delegates to the parent formatter’s implementation:

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

which should invoke JSONFormatter.print(), thereby delegating to the JSONListFormatter in instances where a dict 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.

JSONFormatter

class graphtage.json.JSONFormatter(*args, **kwargs)

Bases: GraphtageFormatter

The default JSON formatter.

DEFAULT_INSTANCE: Formatter[T] = <graphtage.json.JSONFormatter 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)
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, 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_ContainerNode(printer: Printer, node: ContainerNode)

Prints a graphtage.ContainerNode.

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

print_KeyValuePairNode(printer: Printer, node: KeyValuePairNode)

Prints a graphtage.KeyValuePairNode.

By default, the key is printed in blue, followed by a bright “: “, followed by the value.

print_LeafNode(printer: Printer, node: LeafNode)

Prints a graphtage.LeafNode.

This is equivalent to:

printer.write(json.dumps(node.object))
print_XMLElement(printer: Printer, node: XMLElement)
property root: Formatter[T]

Returns the root formatter.

sub_format_types: Sequence[type[Formatter[T]]] = (<class 'graphtage.json.JSONStringFormatter'>, <class 'graphtage.json.JSONListFormatter'>, <class 'graphtage.json.JSONDictFormatter'>)

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.

JSONListFormatter

class graphtage.json.JSONListFormatter(*args, **kwargs)

Bases: SequenceFormatter

A sub-formatter for JSON lists.

DEFAULT_INSTANCE: Formatter[T] = <graphtage.json.JSONListFormatter object>

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

__init__()

Initializes the JSON 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.

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 list items.

A joined list keeps all of its items on one line, separated by a single space so that the result reads as [1, 2, 3] rather than [1,2,3].

items_indent(printer: Printer) → Printer

Returns the printer context in which the list items are printed.

A joined list emits no newlines of its own, so indenting its items would have no visible effect on the list itself while still adding a level of indentation to any nested sequence that does break across lines.

Returns:

printer itself if the list is joined, otherwise printer.indent().

Return type:

Printer

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 JSONFormatter.print(), thereby delegating to the JSONDictFormatter 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.

JSONStringFormatter

class graphtage.json.JSONStringFormatter(*args, **kwargs)

Bases: StringFormatter

A JSON formatter for strings.

DEFAULT_INSTANCE: Formatter[T] = <graphtage.json.JSONStringFormatter 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

This is equivalent to:

printer.write(json.dumps(c)[1:-1])
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, _)

Prints an ending quote for the string

write_start_quote(printer: Printer, _)

Prints a starting quote for the string

json functions

build_tree

graphtage.json.build_tree(python_obj: int | float | bool | str | bytes | list | dict, options: BuildOptions | None = None, force_leaf_node: bool = False) → TreeNode

Builds a Graphtage tree from an arbitrary Python object.

Parameters:

  • python_obj – The object from which to build the tree.

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

  • force_leaf_node – If True, assume that python_obj is not a list() or dict().

Returns:

The resulting tree.

Return type:

TreeNode

Raises: