Interface for (de)serializable JSON objects.
Please recall, that standard Python library implements
json.JSONDecoderthat perform translations based on respective conversion tables that look pretty much like the one below (for complete tables see relevant Python documentation):
JSON Python object dict … …
While the above conversion table is about translation of JSON documents to/from the basic Python types only,
JSONDeSerializableintroduces the following two concepts:
- Turning an arbitrary Python object into Python object that can
be encoded into a JSON document. Full serialization produces
a Python object composed of only basic types as required by the
conversion table. Partial
serialization (accomplished by
to_partial_json()) produces a Python object that might also be built from other
- Turning a decoded Python object (necessarily one of the basic types as required by the conversion table) into an arbitrary Python object.
Serialization produces serialized object (“partially serialized object” or “fully serialized object” for partial and full serialization respectively) and deserialization produces deserialized object, both usually denoted in the source code as
Wording in the official Python documentation might be confusing after reading the above, but in the light of those definitions, one can view
json.JSONDecoder.decode()as decoder and deserializer of basic types,
json.JSONEncoder.default()as serializer of basic types,
json.JSONEncoder.encode()as serializer and encoder of basic types.
One could extend
jsonto support arbitrary object (de)serialization either by:
defaultis required to perform only partial serialization, as
defaultrecursively. This is the idea behind making
to_partial_json()produce only partial serialization, while providing custom
json_dumps()that dumps with
To make further documentation a bit more concrete, please, consider the following imaginatory implementation example:
class Foo(JSONDeSerializable): def to_partial_json(self): return 'foo' @classmethod def from_json(cls, jobj): return Foo() class Bar(JSONDeSerializable): def to_partial_json(self): return [Foo(), Foo()] @classmethod def from_json(cls, jobj): return Bar()
Deserialize a decoded JSON document.
Parameters: jobj – Python object, composed of only other basic data types, as decoded from JSON document. Not necessarily
dict(as decoded from “JSON object” document).
Raises: josepy.errors.DeserializationError – if decoding was unsuccessful, e.g. in case of unparseable X509 certificate, or wrong padding in JOSE base64 encoded string, etc.
Serialize Python object.
This function is meant to be passed as
json.dumps(). They call
default(python_object)only for non-basic Python types, so this function necessarily raises
python_objectis not an instance of
Please read the class docstring for more information.
Dump to JSON string using proper serializer.
Returns: JSON document string. Return type: str
Deserialize from JSON document string.
Again, following the example from before, full serialization means the following:
assert Bar().to_json() == ['foo', 'foo']
Raises: josepy.errors.SerializationError – in case of any serialization error. Returns: Fully serialized object.
Following the example, partial serialization means the following:
assert isinstance(Bar().to_partial_json(), Foo) assert isinstance(Bar().to_partial_json(), Foo) # in particular... assert Bar().to_partial_json() != ['foo', 'foo']
Raises: josepy.errors.SerializationError – in case of any serialization error. Returns: Partially serializable object.