# jsonconversion

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

- **URL**: https://www.freshcrate.ai/projects/jsonconversion
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `1.2.1` (2026-04-21)
- **License**: BSD
- **Source**: https://github.com/DLR-RM/python-jsonconversion
- **Homepage**: https://pypi.org/project/jsonconversion/
- **Language**: Python
- **GitHub**: 9 stars, 3 forks
- **Registry**: pypi (`jsonconversion`)
- **Tags**: `conversion`, `json`, `pypi`, `serialization`

## 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.

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `1.2.1` | 2026-04-21 | Low | Imported from PyPI (1.2.1) |
| `1.2.0` | 2025-10-24 | Low | Migrated `pkg_resources` to `importlib.metadata` which is new standard for python>=3.7 |
| `1.1.2` | 2025-10-14 | Low | Relaxed numpy version for upper dependencies |
| `1.1.1` | 2025-01-27 | Low | Properly specifying numpy dependency based on python version |
| `1.1.0` | 2025-01-23 | Low | - Added dependabot configuration - Added github actions to run test on pull requests - Removed pytest dependability |
| `1.0.3` | 2025-01-22 | Low | Relieved numpy version for better backwards compatibility |
| `1.0.2` | 2025-01-13 | Low | Updated minimum python version to 3.9 |
| `1.0.1` | 2024-03-07 | Low | Updated build process |
| `1.0.0` | 2024-03-05 | Low | Updated dependency deprecation and moved to python3 |
| `0.2.7` | 2018-11-16 | Low | Release 0.2.7 |

## Citation

- HTML: https://www.freshcrate.ai/projects/jsonconversion
- Markdown: https://www.freshcrate.ai/projects/jsonconversion.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/jsonconversion/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._