Decoding API

class pheres._decoder.TypedJSONDecoder(*args, **kwargs)

Bases: abc.ABC, pheres._datatypes.UsableDecoder

json.JSONDecoder subclass for typed JSON decoding

The type to decode must be provided by indexing this class with the type as key (like in the ‘typing’ module). The type hint must be valid in a JSON context.

jsonables are supported, as this is the whole point of that class

Example

# type check that all values are str or int
json.load(..., cls=JSONableDecoder[Dict[str, int]])
# The class exposed a `load` method
JSONableDecoder[Dict[str, int]].load(...)

classmethod __class_getitem__(tp)

Parametrize the TypedJSONDecoder to decode the provided type hint

Jsonable subclasses are supported

Parameters

tp – type hint to parametrize a TypedJSONDecoder for

Returns

A special subclass of TypedJSONDecoder for use with json.load

classmethod load(*, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

Thin wrapper around json.load that use this class as the cls argument. The TypedJSONDecoder must be parametrized.

Wrapped function docstring:

Deserialize fp (a .read()-supporting file-like object containing a JSON document) to a Python object.

object_hook is an optional function that will be called with the result of any object literal decode (a dict). The return value of object_hook will be used instead of the dict. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).

object_pairs_hook is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

To use a custom JSONDecoder subclass, specify it with the cls kwarg; otherwise JSONDecoder is used.

classmethod loads(*, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

Thin wrapper around json.loads that use this class as the cls argument. The TypedJSONDecoder must be parametrized.

Wrapped function docstring:

Deserialize s (a str, bytes or bytearray instance containing a JSON document) to a Python object.

object_hook is an optional function that will be called with the result of any object literal decode (a dict). The return value of object_hook will be used instead of the dict. This feature can be used to implement custom decoders (e.g. JSON-RPC class hinting).

object_pairs_hook is an optional function that will be called with the result of any object literal decoded with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the dict. This feature can be used to implement custom decoders. If object_hook is also defined, the object_pairs_hook takes priority.

parse_float, if specified, will be called with the string of every JSON float to be decoded. By default this is equivalent to float(num_str). This can be used to use another datatype or parser for JSON floats (e.g. decimal.Decimal).

parse_int, if specified, will be called with the string of every JSON int to be decoded. By default this is equivalent to int(num_str). This can be used to use another datatype or parser for JSON integers (e.g. float).

parse_constant, if specified, will be called with one of the following strings: -Infinity, Infinity, NaN. This can be used to raise an exception if invalid JSON numbers are encountered.

To use a custom JSONDecoder subclass, specify it with the cls kwarg; otherwise JSONDecoder is used.

pheres._decoder.deserialize(obj: JSONObject, type_hint: TypeHint) → JSONObject

Deserializes a python object representing a JSON to a given type

This is the equivalent of TypedJSONDecoder for JSON object that were already loaded with json.loads.

Parameters

• obj – the object to deserialize

• type_hint – the type to deserialize to, i.e. to type-check against

Returns

A JSONObject. It might not be equal to the original object, because serialized Jsonable are converted to a proper class instance

Raises

TypedJSONDecodeError – obj cannot be deserialized to type_hint