API¶

Note

When creating and manipulating a Document, it’s important to keep in mind how the underlying yyjson library manages memory. If you modify a Document, such as removing or replacing a value, the memory for that value is not freed until the Document is destroyed. A Document isn’t meant to be kept around and constantly modified, so don’t use it as, say, a database.

class yyjson.Document¶

Bases: object

A single JSON document.

A Document can be built from a JSON-serializable Python object, a JSON document in a str, a JSON document encoded to bytes, or a Path() object to read a file from disk. Ex:

>>> Document({'a': 1, 'b': 2})
>>> Document(b'{"a": 1, "b": 2}')
>>> Document('{"a": 1, "b": 2}')
>>> Document(Path('path/to/file.json'))

By default, the parsing is strict and follows the JSON specifications. You can change this behaviour by passing in ReaderFlags. Ex:

>>> Document('''{
...     // Comments in JSON!?!?
...     "a": 1
... }''', flags=ReaderFlags.ALLOW_COMMENTS)

Note

yyjson has distinct APIs and data structures for mutable and immutable documents. This class is a wrapper around both of them, and will automatically convert between them as needed.

Parameters:

content (str, bytes, Path, dict, list) – The initial content of the document.
flags (ReaderFlags, optional) – Flags that modify the document parsing behaviour.
default (callable, optional) – A function called to convert objects that are not JSON serializable. Should return a JSON serializable version of the object or raise a TypeError.

as_obj¶: Converts the Document to a native Python object, such as a dict or list.

dumps()¶

Dumps the document to a string and returns it.

By default, serializes to a minified string and strictly follows the JSON specification. Ex:

>>> doc = Document({'hello': 'world'})
>>> print(doc.dumps())
{"hello":"world"}

This behaviour can be controlled by passing WriterFlags. Ex:

>>> doc = Document({'hello': 'world'})
>>> print(doc.dumps(flags=WriterFlags.PRETTY))
{
    "hello": "world"
}

To dump just part of a document, you can pass a JSON pointer (RFC 6901) as at_pointer, ex:

>>> doc = Document({'results': {'count': 3, 'rows': [55, 66, 77]}})
>>> print(doc.dumps(at_pointer='/results/rows'))
[55,66,77]

Parameters:

flags (yyjson.WriterFlags, optional) – Flags that control JSON writing behaviour.
at_pointer (str, optional) – An optional JSON pointer specifying what part of the document should be dumped. If not specified, defaults to the entire Document.

Returns:

The serialized Document.

Return type:

str

freeze()¶

Freezes the document, copying it into yyjson’s read-only internal object.

This object can be used as a normal Document object, but uses less memory after creation, and offers slightly improved performance.

Note

If a Document method that requires mutation is called on a frozen Document, such as patch(), it will be automatically thawed. This is an advanced function and can usually be ignored.

get_pointer()¶

Returns the JSON element at the given JSON pointer (RFC 6901).

Parameters:: pointer (str) – JSON Pointer to search for.

is_thawed¶: Returns whether the Document is thawed/mutable.

patch()¶

Patch a Document with another Document, using either JSON Patch (RFC 6902) or JSON Merge-Patch (RFC 7386).

By default, this will apply a JSON Patch. Specify use_merge_patch=True to use JSON Merge-Patch instead.

Note

This method will automatically thaw a frozen Document.

Parameters:

patch (Document) – The Document to patch with.
at_pointer (str) – The (optional) JSON Pointer (RFC 6901) to patch at, instead of patching the entire document.
use_merge_patch – Whether to use JSON Merge-Patch (RFC 7386) instead of JSON Patch (RFC 6902).

thaw()¶

Thaws the document, copying it into yyjson’s mutable internal object.

This object can be used as a normal Document object, but will use slightly more memory after creation, and offers slightly worse performance.

Note

This is an advanced function and can usually be ignored.

class yyjson.ReaderFlags(value)[source]¶

Bases: IntFlag

Flags that can be passed into JSON reading functions to control parsing behaviour.

ALLOW_COMMENTS = 8¶: Allow C-style single line and multiple line comments.

ALLOW_INF_AND_NAN = 16¶: Allow inf/nan number and literal, case-insensitive, such as 1e999, NaN, inf, -Infinity

ALLOW_TRAILING_COMMAS = 4¶: Allow single trailing comma at the end of an object or array, such as [1,2,3,] {“a”:1,”b”:2,}.

BIGNUM_AS_RAW = 128¶: Alias for BIG_NUMBERS_AS_DECIMAL.

BIG_NUMBERS_AS_DECIMAL = 128¶: Like NUMBERS_AS_DECIMAL, but only for numbers that are too large to fit in a native type.

NUMBERS_AS_DECIMAL = 32¶: Read all numbers as Decimal objects instead of native types. This option is useful for preserving the exact precision of numbers or for handling numbers that are too large to fit in a native type.

NUMBERS_AS_RAW = 32¶: Alias for NUMBERS_AS_DECIMAL.

STOP_WHEN_DONE = 2¶: Stop when done instead of issues an error if there’s additional content after a JSON document. This option may be used to parse small pieces of JSON in larger data, such as NDJSON.

class yyjson.WriterFlags(value)[source]¶

Bases: IntFlag

Flags that can be passed into JSON writing functions to control writing behaviour.

ALLOW_INF_AND_NAN = 8¶: Writes Infinity and NaN.

ESCAPE_SLASHES = 4¶: Escapes / as \/.

ESCAPE_UNICODE = 2¶: Escapes unicode as uXXXXX so that all output is ASCII.

INF_AND_NAN_AS_NULL = 16¶: Writes Infinity and NaN as null instead of raising an error.

PRETTY = 1¶: Write the JSON with 4-space indents and newlines.

PRETTY_TWO_SPACES = 64¶: Write JSON pretty with 2 space indent. This flag will override the PRETTY flag.

WRITE_NEWLINE_AT_END = 128¶: Write a newline at the end of the JSON string.