jsonype package

Module contents

class jsonype.FromDataclass[source]

Bases: ToJsonConverter[DataclassTarget_contra]

Converts objects of dataclasses.dataclass.

A dataclass is converted to a dict with keys corresponding to the fields of the dataclass and values being converted with their respective ToJsonConverter.

can_convert(o: Any) → bool[source]

Return if this converter can convert the given object to an object representing JSON.

Parameters:: o – the object to be converted to an object representing JSON
Returns:: True if this converter can convert the given object into an object representing JSON, False otherwise.

Convert the given object of type SourceType_contra to an object representing JSON.

Parameters:

o – the object to convert
to_json – If this converter converts container types like typing.Sequence this function is used to convert the contained objects into their corresponding objects representing JSON.

Returns:

the converted object representing JSON.

Raises:

ValueError – If the object cannot be converted to an object representing JSON.

Bases: ValueError

__init__(js: Literal[None] | int | float | str | bool | Sequence[Literal[None] | int | float | str | bool | Sequence[Json] | Mapping[str, Json]] | Mapping[str, Literal[None] | int | float | str | bool | Sequence[Json] | Mapping[str, Json]], target_type: type, reason: str | None = None) → None[source]

class jsonype.FromJsonConverter[source]

Bases: ABC, Generic[TargetType_co, ContainedTargetType_co]

The base-class for converters that convert from objects representing JSON.

Converters that convert from objects representing JSON to their specific python object have to implement the two abstract methods defined in this base-class.

TargetType:: The type this converter converts objects representing JSON to.
ContainedTargetType:: If TargetType is a container type (like Sequence for example) this is the type of the objects the container contains (e.g. the type of the elements of a Sequence).

abstract can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.FromMapping[source]

Bases: ToJsonConverter[Mapping[str, Any]]

Converts objects of type typing.Mapping.

A typing.Mapping with str typed keys is converted to a dict with all values being converted with their respective ToJsonConverter.

can_convert(o: Any) → bool[source]

Return if this converter can convert the given object to an object representing JSON.

Parameters:: o – the object to be converted to an object representing JSON
Returns:: True if this converter can convert the given object into an object representing JSON, False otherwise.

Convert the given object of type typing.Mapping to an object representing JSON.

Raises:: ValueError – If the typing.Mapping contains none-str keys.

class jsonype.FromNamedTuple[source]

Bases: ToJsonConverter[NamedTupleSource_contra]

Converts objects of type typing.NamedTuple.

A typing.NamedTuple is converted to a dict with keys corresponding to the fields of the NamedTuple and values being converted with their respective ToJsonConverter.

can_convert(o: Any) → bool[source]

Return if this converter can convert the given object to an object representing JSON.

Parameters:: o – the object to be converted to an object representing JSON
Returns:: True if this converter can convert the given object into an object representing JSON, False otherwise.

Convert the given object of type SourceType_contra to an object representing JSON.

Parameters:

o – the object to convert
to_json – If this converter converts container types like typing.Sequence this function is used to convert the contained objects into their corresponding objects representing JSON.

Returns:

the converted object representing JSON.

Raises:

ValueError – If the object cannot be converted to an object representing JSON.

class jsonype.FromNone[source]

Bases: ToJsonConverter[Literal[None]]

Converts a None instance.

A None is converted to None.

can_convert(o: Any) → bool[source]

Return if this converter can convert the given object to an object representing JSON.

Parameters:: o – the object to be converted to an object representing JSON
Returns:: True if this converter can convert the given object into an object representing JSON, False otherwise.

Convert the given object of type SourceType_contra to an object representing JSON.

Parameters:

o – the object to convert
to_json – If this converter converts container types like typing.Sequence this function is used to convert the contained objects into their corresponding objects representing JSON.

Returns:

the converted object representing JSON.

Raises:

ValueError – If the object cannot be converted to an object representing JSON.

class jsonype.FromSequence[source]

Bases: ToJsonConverter[Sequence[Any]]

Converts objects of type typing.Sequence.

A typing.Sequence is converted to a list with all elements being converted with their respective ToJsonConverter.

can_convert(o: Any) → bool[source]

Return if this converter can convert the given object to an object representing JSON.

Parameters:: o – the object to be converted to an object representing JSON
Returns:: True if this converter can convert the given object into an object representing JSON, False otherwise.

Convert the given object of type SourceType_contra to an object representing JSON.

Parameters:

o – the object to convert
to_json – If this converter converts container types like typing.Sequence this function is used to convert the contained objects into their corresponding objects representing JSON.

Returns:

the converted object representing JSON.

Raises:

ValueError – If the object cannot be converted to an object representing JSON.

class jsonype.FromSimple[source]

Bases: ToJsonConverter[int | float | str | bool]

Converts simple objects of type int, float, str, bool.

The conversion simply returns the given object.

can_convert(o: Any) → bool[source]

Return if this converter can convert the given object to an object representing JSON.

Parameters:: o – the object to be converted to an object representing JSON
Returns:: True if this converter can convert the given object into an object representing JSON, False otherwise.

Convert the given object of type SourceType_contra to an object representing JSON.

Parameters:

o – the object to convert
to_json – If this converter converts container types like typing.Sequence this function is used to convert the contained objects into their corresponding objects representing JSON.

Returns:

the converted object representing JSON.

Raises:

ValueError – If the object cannot be converted to an object representing JSON.

class jsonype.ToAny[source]

Bases: FromJsonConverter[Any, None]

Convert to the target type typing.Any.

This converter returns the object representing JSON unchanged.

can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToDataclass(strict: bool = False)[source]

Bases: FromJsonConverter[DataclassTarget_co, TargetType_co]

Convert an object representing JSON to a dataclasses.dataclass.

The JSON object is expected to have keys corresponding to the fields of the dataclass. Each value is converted to the corresponding field type.

__init__(strict: bool = False) → None[source]

can_convert(target_type: type, _origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToJsonConverter[source]

Bases: ABC, Generic[SourceType_contra]

The base-class for converters that convert to objects representing JSON.

Converters that convert objects of their specific type T to objects representing JSON have to implement the two abstract methods defined in this base-class.

SourceType_contra:: The type of the object that shall be converted into an object representing JSON.

abstract can_convert(o: Any) → bool[source]

Return if this converter can convert the given object to an object representing JSON.

Parameters:: o – the object to be converted to an object representing JSON
Returns:: True if this converter can convert the given object into an object representing JSON, False otherwise.

Convert the given object of type SourceType_contra to an object representing JSON.

Parameters:

o – the object to convert
to_json – If this converter converts container types like typing.Sequence this function is used to convert the contained objects into their corresponding objects representing JSON.

Returns:

the converted object representing JSON.

Raises:

ValueError – If the object cannot be converted to an object representing JSON.

class jsonype.ToList[source]

Bases: FromJsonConverter[Sequence[TargetType_co], TargetType_co]

Convert an array to a typing.Sequence.

Convert all elements of the array into the corresponding target type given by the type-parameter of the typing.Sequence.

A target type of Sequence[int] can convert a list of int, but not a list of str.

can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToLiteral[source]

Bases: FromJsonConverter[TargetType_co, None]

Convert to one of the listet literals.

Returns the JSON-representation unchanged if it equals one of the literals, otherwise it raises a ValueError

A target_type like Literal[5, 6] can be used to convert for example a 5 or a 6, but not a 7.

can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToMapping[source]

Bases: FromJsonConverter[Mapping[str, TargetType_co], TargetType_co]

Convert the JSON-representation to a typing.Mapping.

Convert all entries of the given Mapping (respectively JSON-object) into entries of a Mapping with the given key and value target types.

A target type of Mapping[str, int] can convert for example { "key1": 1, "key2": 2 }.

can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToNamedTuple(strict: bool = False)[source]

Bases: FromJsonConverter[NamedTupleTarget_co, TargetType_co]

Convert an object representing JSON to a typing.NamedTuple.

The JSON object is expected to have keys corresponding to the NamedTuple fields. Each value is converted to the corresponding field type. In case of an untyped NamedTuple, the field type is assumed to be Any.

__init__(strict: bool = False) → None[source]

can_convert(target_type: type, _origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToNone[source]

Bases: FromJsonConverter[None, None]

Return the JSON-representation, if it is None.

If the given JSON-representation is not None it raises an ValueError.

can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToSimple[source]

Bases: FromJsonConverter[TargetType_co, None]

Return the JSON-representation, if it is one of the types int, float, str, bool.

can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToTuple[source]

Bases: FromJsonConverter[tuple[Any, …], Any]

Convert an array to a tuple.

Convert the elements of the array in the corresponding target type given by the type-parameter of the tuple in the same position as the element. Raises ValueError if the number of type-parameters do not match to the number of elements.

The type-parameters may contain a single ... which is replaced by as many Any such that the number of type-parameters equals the number of elements. So a target type of tuple[int, ..., str] is equivalent to a target type of tuple[int, Any, Any, Any, str] if the JSON-representation to be converted is a typing.Sequence of 5 elements.

A target type like tuple[int, str] can convert for example the list [5, "Hello World!"] into the tuple (5, "Hello World!"), but not ["Hello World!", 5]

can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToTypedMapping(strict: bool = False)[source]

Bases: FromJsonConverter[Mapping[str, TargetType_co], TargetType_co]

Convert the JSON-representation to a typing.TypedDict.

Convert all entries of the given Mepping (respectively JSON-object) into entries of a TypedDict with the given key and value target types.

Parameters:: strict – indicates if the conversion of a Mapping should fail, if is contains more keys than the provided target type. Pass True to make it fail in this case. Defaults to False.

Example

>>> from typing import TypedDict
>>>
>>> # using the ToTypedMapping converter one can convert for example:
>>> json_object = {"k1": 1.0, "k2": 2, "un": "known"}
>>> # into the following:
>>> class Map(TypedDict):
...     k1: float
...     k2: int
>>> # In this example the result will meet:
>>> # assert result == {"k1": 1.0, "k2": 2}

__init__(strict: bool = False) → None[source]

can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.ToUnion[source]

Bases: FromJsonConverter[TargetType_co, TargetType_co]

Convert to one of the type-parameters of the given typing.Union.

It tries to convert the object representing JSON to one of the type-parameters of the Union-type in the order of their occurrence and returns the first successful conversion result. If none is successful it raises a ValueError.

A target_type like Union[int, str] can be used to convert for example a 5 or a "Hello World!", but will fail to convert a list.

can_convert(target_type: type, origin_of_generic: type | None) → bool[source]

Return if this converts from an object representing JSON into the given target_type.

Parameters:

target_type – the type this converter may or may not convert an object that represents JSON into.
origin_of_generic – the unsubscripted version of target_type (i.e. without type-parameters). This origin is computed with typing.get_origin().

Returns:

True if this converter can convert into target_type, False otherwise.

Convert the given object representing JSON to the given target type.

Parameters:

js – the JSON-representation to convert
target_type – the type to convert to
annotations – the annotations dict for target_type as returned by inspect.get_annotations()
from_json – If this converter converts into container types like typing.Sequence this function is used to convert the contained JSON-nodes into their respective target-types.

Returns:

the converted object of type target_type

Raises:

ValueError – If the JSON-representation cannot be converted an instance of target_type.

class jsonype.TypedJson(strict: bool = False)[source]

Bases: object

Provides methods to convert python objects to/from a JSON-representation.

Args;

strict: Perform a strict from-JSON conversion.: This makes from_json() raise more often for example when extra fields are in the JSON-representation that do not exist in the target-type.

Example

>>> from dataclasses import dataclass
>>> from typing import NamedTuple
>>> from jsonype import TypedJson
>>> from json import loads
>>>
>>> typed_json = TypedJson()
>>>
>>> class Address(NamedTuple):
...     street: str
...     city: str
>>>
>>> @dataclass
... class Person:
...     name: str
...     address: Address
...     some_related_number: int
>>>
>>> js = loads('''{
...         "name": "John Doe",
...         "address": {
...             "street": "123 Maple Street",
...             "city": "Any town",
...             "zip": "ignored"
...         },
...         "some_related_number": 5
...     }''')
>>> person = typed_json.from_json(js, Person)
>>>
>>> assert person == Person(
...     name="John Doe",
...     address=Address(
...         street="123 Maple Street",
...         city="Any town"
...     ),
...     some_related_number=5
... )
>>>
>>> try:
...     # strict conversion does not accept extra fields in the JSON-object
...     person = TypedJson(strict=True).from_json(js, Person)
... except ValueError as e:
...     print(e)  
("Cannot convert {'street': '...', ..., 'zip': 'ignored'}
to <class 'Address'>: unexpected keys: {'zip'}", ...
>>>
>>> # JSON-types must match expected types:
>>> js = loads('''{
...         "name": "John Doe",
...         "address": {
...             "street": "123 Maple Street",
...             "city": "Any town"
...         },
...         "some_related_number": "5"
...     }''')
>>> try:
...     person = typed_json.from_json(js, Person)
... except ValueError as e:
...     print(e)  
("Cannot convert 5 to <class 'int'>", ...

__init__(strict: bool = False) → None[source]

Convert the given JSON-representation to an object of the given type.

The JSON-representation is typically generated from a JSON string by using json.loads().

Parameters:

js – the JSON-representation to be converted
target_type – the type the JSON-representation should be converted to

Returns:

the object of the given type

Raises:

ValueError – If the JSON-representation cannot be converted as a converter fails to convert it to an object of the required type.

Convert the given object to a JSON-representation.

The JSON-representation can afterwards be converted to a string containing JSON by using json.dumps().

Parameters:: o – The object to be converted.
Returns:: The JSON-representation.
Raises:: ValueError – if the object cannot be converted to a JSON-representation as no suitable converter exists for the object’s type.

exception jsonype.UnsupportedTargetTypeError(target_type: type, reason: str | None = None)[source]

Bases: ValueError

__init__(target_type: type, reason: str | None = None) → None[source]