jsonconversion 1.2.1
This python module helps converting arbitrary Python objects into JSON strings and back.
License: BSD
Requires Python: >=3.9
Keywords: json, conversion, serialization


The ``jsonconversion`` package
==============================

This python module helps converting arbitrary Python objects into JSON strings and back. It extends the basic features
of the ``JSONEncoder`` and ``JSONDecoder`` classes provided by the native ``json`` package. For this purpose,
``jsonconversion`` ships with these four classes:

The ``JSONObject`` class
------------------------

Your serializable classes should inherit from this class. Hereby, they must implement the methods ``from_dict`` and
``to_dict``. The example further down describes how to do so.

The ``JSONExtendedEncoder`` class
---------------------------------

This is a class used internally by ``JSONObjectEncoder``. However, it can also be used directly, if you do not need the
features of ``JSONObjectEncoder`` but want to implement your own encoders.

The class is especially helpful, if you want custom handling of builtins (``int``, ``dict``, ...) or classes deriving
from builtins. This would not be possible if directly inheriting from ``JSONEncoder``. To do so, override the
``isinstance`` method and return ``False`` for all types you want to handle in the ``default`` method.

If you look at the source code of ``JSONObjectEncoder``, you will see how this can be used.

The ``JSONObjectEncoder`` class
-------------------------------

Encodes Python objects into JSON strings. Supported objects are:

-  Python builtins: ``int``, ``float``, ``str``, ``list``, ``set``, ``dict``, ``tuple``
-  ``type`` objects: ``isinstance(object, type)``
-  All classes deriving from ``JSONObject``

Those objects can of course also be nested!

The ``JSONObjectDecoder`` class
-------------------------------

Decodes JSON strings converted using the ``JSONObjectEncoder`` back to Python objects.

The class adds a custom keyword argument to the ``load[s]`` method: ``substitute_modules``. This parameter takes a
``dict`` in the form ``{"old.module.MyClass": "new.module.MyClass"}``. It can be used if you have serialized
``JSONObject``\s who's module path has changed.

Usage
=====

Using ``jsonconversion`` is easy. You can find further code examples in the ``test`` folder.

Encoding and Decoding
---------------------

In order to encode Python objects with JSON conversion and to later decode them, you have to import the Python module
``json``. The module provides the methods ``dump``/``dumps`` for encoding and ``load``/``loads`` for decoding:

.. code:: python

    import json

    from jsonconversion.decoder import JSONObjectDecoder
    from jsonconversion.encoder import JSONObjectEncoder

    var = (1, 2, 3)  # variable to be serialized

    # "dumps" converts the variable to a string, "dump" directly writes it to a file
    str_var = json.dumps(var, cls=JSONObjectEncoder)
    # Equivalently, "loads" converts the object back from a string. "load" from a file
    var_2 = json.loads(str_var, cls=JSONObjectDecoder)
    assert var == var_2

Deriving from JSONObject
------------------------

In order to serialize arbitrary, self-written classes, they must derive from ``JSONObject`` and implement the two
methods ``from_dict`` and ``to_dict``:

.. code:: python

    class MyClass(JSONObject):

        def __init__(self, a, b, c):
            self.a = a
            self.b = b
            self.c = c

        @classmethod
        def from_dict(cls, dict_):
            return cls(dict_['a'], dict_['b'], dict_['c'])

        def to_dict(self):
            return {'a': self.a, 'b': self.b, 'c': self.c}

        def __eq__(self, other):
            return self.a == other.a and self.b == other.b and self.c == other.c

General notes
-------------

-  ``jsonconversion`` stores the class path in the JSON string when serializing a JSONObject. When decoding the object
   back, it automatically imports the correct module. You only have to ensure that the module is within your
   ``PYTHONPATH``.

-  The ``to_dict`` and ``from_dict`` methods only need to specify the elements of a class, needed to recreate the
   object. Derived attributes of a class (like ``age`` from ``year_born``) do not need to be serialized.

-  If you compare the original object with the object obtained from serialization and deserialization using ``is``, they
   will differ, as these are objects at different locations in memory. Also a comparison of JSONObject with ``==`` will
   fail, if you do not tell Python how to compare two objects. This is why ``MyClass`` overrides the ``__eq__`` method.