zserio.json module

The module implements WalkObserver for writing of zserio objects to JSON format.

class zserio.json.JsonDecoder

Bases: object

JSON value decoder.

class Result(success: bool, value: Any, num_read_chars: int)

Bases: object

Decoder result value.

Constructor.

classmethod from_failure(num_read_chars: int = 0)

Creates decoder result value in case of failure.

Parameters:

num_read_chars – Number of processed characters.

classmethod from_success(value: Any, num_read_chars: int = 0)

Creates decoder result value in case of success.

Parameters:

• value – Decoded value.

• num_read_chars – Number of read characters.

property num_read_chars: int

Gets the number of read characters from the string which contains encoded JSON value.

In case of failure, it returns the number of processed (read) characters.

Returns:

Number of read characters.

property success: bool

Gets the decoder result.

Returns:

True in case of success, otherwise false.

property value: Any

Gets the decoded JSON value.

Returns:

Decoded JSON value or None in case of failure.

static decode_value(content: str, pos: int) → Result

Decodes the JSON value from the string.

Parameters:

• content – String which contains encoded JSON value.

• pos – Position from zero in content where the encoded JSON value begins.

Returns:

Decoder result object.

class zserio.json.JsonEncoder

Bases: object

Converts zserio values to Json string representation.

Constructor.

encode_value(value: Any) → str

Encodes value to JSON string representation.

Parameters:

value – Value to encode.

Returns:

Value encoded to string as a valid JSON value.

class zserio.json.JsonEnumerableFormat(value)

Bases: Enum

Configuration for writing of enumerable types.

NUMBER = 1

Print as JSON integral value.

STRING = 2

Print as JSON string according to the following rules:

1. Enums

   • when an exact match with an enumerable item is found, the item name is used - e.g. “FIRST”,

   • when no exact match is found, it’s an invalid value, the integral value is converted to string and an appropriate comment is included - e.g. “10 /* no match */”.

2. Bitmasks

   • when an exact mach with or-ed bitmask values is found, it’s used - e.g. “READ | WRITE”,

   • when no exact match is found, but some or-ed values match, the integral value is converted to string and the or-ed values are included in a comment - e.g. “127 /* READ | CREATE */”,

   • when no match is found at all, the integral value is converted to string and an appropriate comment is included - e.g. “13 /* no match */”.

class zserio.json.JsonParser(text_io: TextIO, observer: Observer)

Bases: object

Json Parser.

Parses the JSON on the fly and calls an observer.

Constructor.

Parameters:

• text_io – Text stream to parse.

• observer – Observer to use.

ELEMENT_TOKENS = [<JsonToken.BEGIN_OBJECT: 3>, <JsonToken.BEGIN_ARRAY: 5>, <JsonToken.VALUE: 9>]

class Observer

Bases: object

Json parser observer.

begin_array() → None

Called when a JSON array begins - i.e. on ‘[‘.

begin_object() → None

Called when a JSON object begins - i.e. on ‘{‘.

end_array() → None

Called when a JSON array ends - i.e. on ‘]’.

end_object() → None

Called when a JSON object ends - i.e. on ‘}’.

visit_key(key: str) → None

Called on a JSON key.

Parameters:

key – Key value.

visit_value(value: Any) → None

Called on a JSON value.

Parameters:

value – JSON value.

get_column() → int

Gets current column number.

Returns:

Column number.

get_line() → int

Gets current line number.

Returns:

Line number.

parse() → bool

Parses single JSON element from the text stream.

Returns:

True when end-of-file is reached, False otherwise (i.e. another JSON element is present).

Raises:

JsonParserException – When parsing fails.

exception zserio.json.JsonParserException

Bases: PythonRuntimeException

Exception used to distinguish exceptions from the JsonParser.

class zserio.json.JsonReader(text_io: TextIO)

Bases: object

Reads zserio object tree defined by a type info from a text stream.

Constructor.

Parameters:

text_io – Text stream to read.

read(type_info: TypeInfo, *arguments: List[Any]) → Any

Reads a zserio object tree defined by the given type info from the text steam.

Parameters:

• type_info – Type info defining the expected zserio object tree.

• arguments – Arguments of type defining the expected zserio object tree.

Returns:

Zserio object tree initialized using the JSON data.

Raises:

PythonRuntimeException – When the JSON doesn’t contain expected zserio object tree.

class zserio.json.JsonToken(value)

Bases: Enum

Tokens used by Json Tokenizer.

BEGIN_ARRAY = 5

BEGIN_OBJECT = 3

BEGIN_OF_FILE = 1

END_ARRAY = 6

END_OBJECT = 4

END_OF_FILE = 2

ITEM_SEPARATOR = 8

KEY_SEPARATOR = 7

VALUE = 9

class zserio.json.JsonTokenizer(text_io: TextIO)

Bases: object

Tokenizer used by JsonParser.

Constructor.

Parameters:

text_io – Text stream to tokenize.

MAX_LINE_LEN = 65536

get_column() → int

Gets column number of the current token.

Returns:

Column number.

get_line() → int

Gets line number of the current token.

Returns:

Line number.

get_token() → JsonToken

Gets current token.

Returns:

Current token.

get_value() → Any

Gets current value.

Returns:

Current value.

next() → JsonToken

Moves to next token.

Returns:

Token.

Raises:

JsonParserException – When unknown token is reached.

class zserio.json.JsonWriter(*, text_io: TextIO | None = None, enumerable_format: JsonEnumerableFormat = JsonEnumerableFormat.STRING, item_separator: str | None = None, key_separator: str | None = None, indent: str | int | None = None)

Bases: WalkObserver

Walker observer which dumps zserio objects to JSON format.

Constructor.

Parameters:

• text_io – Optional text stream for JSON output, io.StringIO is used by default.

• item_separator – Optional item separator, default is ‘, ‘ if indent is None, ‘,’ otherwise.

• key_separator – Optional key separator, default is ‘: ‘.

• enumerable_format – Optional enumerable format to use, default is JsonEnumerableFormat.STRING.

• indent – String or (non-negative) integer defining the indent. If not None, newlines are inserted.

begin_array(array: List[Any], member_info: MemberInfo) → None

Called at the beginning of an array.

Note that for None arrays (i.e. non-present optionals) the visit_value with None is called instead!

Parameters:

• array – Zserio array.

• member_info – Array member info.

begin_compound(compound: Any, member_info: MemberInfo, element_index: int | None = None) → None

Called at the beginning of an compound field object.

Note that for None compounds (i.e. uninitialized or optionals) the visit_value method is called instead!

Parameters:

• compound – Compound zserio object.

• member_info – Compound member info.

• element_index – Element index in array or None if the compound is not in array.

begin_root(_compound: Any) → None

Called for the root compound zserio object which is to be walked-through.

Parameters:

compound – Root compound zserio object.

end_array(array: List[Any], member_info: MemberInfo) → None

Called at the end of an array.

Parameters:

• array – Zserio array.

• member_info – Array member info.

end_compound(compound: Any, member_info: MemberInfo, _element_index: int | None = None) → None

Called at the end of just walked compound object.

Parameters:

• compound – Compound zserio object.

• member_info – Compound member info.

• element_index – Element index in array or None if the compound is not in array.

end_root(_compound: Any) → None

Called at the end of just walked root compound zserio object.

Parameters:

compound – Root compound zserio object.

get_io() → TextIO

Gets the underlying text stream.

Returns:

Underlying text steam.

visit_value(value: Any, member_info: MemberInfo, element_index: int | None = None) → None

Called when a simple (or an unset compound or array - i.e. None) value is reached.

Parameters:

• value – Simple value.

• member_info – Member info.

• element_index – Element index in array or None if the value is not in array.