Metadata-Version: 2.1
Name: jsonconversion
Version: 0.2.12
Summary: This python module helps converting arbitrary Python objects into JSON strings and back.
Home-page: https://github.com/DLR-RM/python-jsonconversion
Author: Franz Steinmetz
Author-email: franz.steinmetz@dlr.de
Maintainer: Franz Steinmetz
Maintainer-email: franz.steinmetz@dlr.de
License: BSD
Download-URL: https://github.com/DLR-RM/python-jsonconversion/tarball/master
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.
        
Keywords: json,conversion,serialization
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Flask
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Object Brokering
Classifier: Topic :: Utilities
Requires-Python: >=2.6
Provides-Extra: testing