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.

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,}.

NUMBERS_AS_RAW = 32#: Read number as raw string. inf/nan literal is also read as raw with ALLOW_INF_AND_NAN flag.

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.