a
Bgn @ sl d Z ddlZddlZddlmZmZ ddlmZmZm Z m
Z
ddl m Z e dddZ
G d d dejd
ZdS ) zJOSE interfaces. N)MappingSequence)AnyTypeTypeVarUnion)errorsGenericJSONDeSerializableJSONDeSerializable)boundc @ s e Zd ZdZejedddZedddZe eje
e ee ddd Z e e
e e
eef e d
d d Zeed
ddZedddZe d edddZdS )r
a Interface for (de)serializable JSON objects.
Please recall, that standard Python library implements
:class:`json.JSONEncoder` and :class:`json.JSONDecoder` that perform
translations based on respective :ref:`conversion tables
` that look pretty much like the one below (for
complete tables see relevant Python documentation):
.. _conversion-table:
====== ======
JSON Python
====== ======
object dict
... ...
====== ======
While the above **conversion table** is about translation of JSON
documents to/from the basic Python types only,
:class:`JSONDeSerializable` introduces the following two concepts:
serialization
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
:ref:`conversion table `. **Partial
serialization** (accomplished by :meth:`to_partial_json`)
produces a Python object that might also be built from other
:class:`JSONDeSerializable` objects.
deserialization
Turning a decoded Python object (necessarily one of the basic
types as required by the :ref:`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
``jobj``.
Wording in the official Python documentation might be confusing
after reading the above, but in the light of those definitions, one
can view :meth:`json.JSONDecoder.decode` as decoder and
deserializer of basic types, :meth:`json.JSONEncoder.default` as
serializer of basic types, :meth:`json.JSONEncoder.encode` as
serializer and encoder of basic types.
One could extend :mod:`json` to support arbitrary object
(de)serialization either by:
- overriding :meth:`json.JSONDecoder.decode` and
:meth:`json.JSONEncoder.default` in subclasses
- or passing ``object_hook`` argument (or ``object_hook_pairs``)
to :func:`json.load`/:func:`json.loads` or ``default`` argument
for :func:`json.dump`/:func:`json.dumps`.
Interestingly, ``default`` is required to perform only partial
serialization, as :func:`json.dumps` applies ``default``
recursively. This is the idea behind making :meth:`to_partial_json`
produce only partial serialization, while providing custom
:meth:`json_dumps` that dumps with ``default`` set to
:meth:`json_dump_default`.
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()
)returnc C s
t dS )a Partially serialize.
Following the example, **partial serialization** means the following::
assert isinstance(Bar().to_partial_json()[0], Foo)
assert isinstance(Bar().to_partial_json()[1], Foo)
# in particular...
assert Bar().to_partial_json() != ['foo', 'foo']
:raises josepy.errors.SerializationError:
in case of any serialization error.
:returns: Partially serializable object.
N)NotImplementedErrorself r 5/usr/lib/python3.9/site-packages/josepy/interfaces.pyto_partial_jsonc s z"JSONDeSerializable.to_partial_jsonc s t t d fdd | S )aD Fully serialize.
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.
)objr c s t | tr | S t | tr$| S t | tr@ fdd| D S t | tr`t fdd| D S t | tr fdd| D S | S d S )Nc s g | ] } |qS r r .0Zsubobj
_serializer r
zBJSONDeSerializable.to_json.._serialize..c 3 s | ]} |V qd S )Nr r r r r r zAJSONDeSerializable.to_json.._serialize..c s i | ]\}} | |qS r r )r keyvaluer r r
r zBJSONDeSerializable.to_json.._serialize..)
isinstancer
r strlistr tupler items)r r r r r s
z.JSONDeSerializable.to_json.._serialize)r r r r r to_jsonv s zJSONDeSerializable.to_json)clsjobjr c C s | S )a Deserialize a decoded JSON document.
:param jobj: Python object, composed of only other basic data
types, as decoded from JSON document. Not necessarily
:class:`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.
r )r$ r% r r r from_json s z JSONDeSerializable.from_json)r$ json_stringr c
C sH zt |}W n. ty< } zt|W Y d}~n
d}~0 0 | |S )z&Deserialize from JSON document string.N)jsonloads
ValueErrorr ZDeserializationErrorr& )r$ r' r) errorr r r
json_loads s
z JSONDeSerializable.json_loads)kwargsr c K s t j| fd| ji|S )zsDump to JSON string using proper serializer.
:returns: JSON document string.
:rtype: str
default)r( dumpsjson_dump_default)r r- r r r
json_dumps s z JSONDeSerializable.json_dumpsc C s | j ddddS )zNDump the object to pretty JSON document string.
:rtype: str
T ),z: )Z sort_keysindentZ
separators)r1 r r r r json_dumps_pretty s z$JSONDeSerializable.json_dumps_pretty)
python_objectr c C s& t |tr| S tt|d dS )a Serialize Python object.
This function is meant to be passed as ``default`` to
:func:`json.dump` or :func:`json.dumps`. They call
``default(python_object)`` only for non-basic Python types, so
this function necessarily raises :class:`TypeError` if
``python_object`` is not an instance of
:class:`IJSONSerializable`.
Please read the class docstring for more information.
z is not JSON serializableN)r r
r TypeErrorrepr)r$ r6 r r r r0 s
z$JSONDeSerializable.json_dump_defaultN)__name__
__module__ __qualname____doc__abcabstractmethodr r r# classmethodr r r& r r bytesr, r1 r5 r0 r r r r r
s V
) metaclass)r< r= r( collections.abcr r typingr r r r Zjosepyr r ABCMetar
r r r r s