Skip to main content

This python module helps converting arbitrary Python objects into JSON strings and back.

Project description

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonconversion-0.2.4.tar.gz (11.0 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page