Metadata-Version: 1.1
Name: hgijson
Version: 2.0.0
Summary: Python 3 library for easily JSON encoding/decoding complex class-based Python models, using an arbitrarily complex (but easy to write!) mapping schema.
Home-page: https://github.com/wtsi-hgi/python-json
Author: Colin Nolan
Author-email: colin.nolan@sanger.ac.uk
License: MIT
Description-Content-Type: UNKNOWN
Description: |Build Status| |codecov.io| |Documentation Status|
        
        HGI JSON
        ========
        
        A Python 3 library for easily JSON encoding/decoding complex class-based
        Python models, using an arbitrarily complex (but easy to write!) mapping
        schema.
        
        Features
        --------
        
        -  Ability to create serializers and deserializers for complex
           class-based models using a mapping schema defined in Python.
        -  Works seamlessly with Python's in-built ``json.dumps`` and
           ``json.loads`` serialization methods - does not require the use of
           exotic ``convert_to_json``/``convert_from_json`` methods.
        -  Python models are not be coupled to the serialization process -
           models do not have to inherit from a particular superclass or
           implement an interface with a ``to_json`` (or similar) method.
        -  JSON representations produced are not coupled to the Python model -
           an arbitrary mapping between the JSON and the model can be defined.
        -  Simple to define serialization of subclasses, based on how
           superclasses are serialized.
        -  Pure Python 3 - no DSL, XML or similar required to describe mappings,
           not using outdated Python 2.
        -  `Well tested <https://codecov.io/gh/wtsi-hgi/python-json/>`__.
        
        Overview
        --------
        
        Basic Steps
        ~~~~~~~~~~~
        
        1. Define schema for mapping an object to and/or from JSON
           representation using a list of ``JsonPropertyMapping`` definitions.
        2. Use ``MappingJSONEncoderClassBuilder`` with the mappings to build a
           subclass of ``JSONEncode`` for serializing instances of a specific
           type. Similar with decode.
        3. Use created encoder class with Python's in-built ``json.dumps`` via
           the ``cls`` parameter. Similar with decoder.
        
        Defining Encoders/Decoders
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Encoders and decoders are generated based on a defined JSON <-> Model
        mapping. A mapping can be written that allows complex classes, such as
        that below, to be mapped to and from any JSON representation:
        
        .. code:: python
        
            class CustomClass(SupportFor, MultipleInheritance):
                self __init__(self, support_for_constructor_parameters):
                self.support_for_all_types_of_properties = ""
                self.including_sets = set()
                self.and_lists = list()
                self.and_dictionaries = dict()
                self.and_complex_properties = ComplexClass()
                self.and_nested_objects_of_the_same_type = CustomClass()
                self.and_properties_not_in_json_if_none = None
        
                self support_for_setters(self, value):
                    """..."""
        
                self support_for_getters(self):
                    """..."""
                    
            CustomClassJSONEncoder = MappingJSONEncoderClassBuilder(...).build()    # type: JSONEncoder
            CustomClassJSONDecoder = MappingJSONDecoderClassBuilder(...).build()    # type: JSONDecoder
        
            custom_class_as_json = json.dumps(custom_class, cls=CustomClassJSONEncoder)     # type: str
            custom_class = json.loads("<custom_class_as_json>", cls=CustomClassJSONDecoder)     # type: CustomClass
        
        Documentation
        -------------
        
        For more details, including information on how to setup and use the
        library, please `view the documentation on
        ReadTheDocs <http://hgi-json.readthedocs.io/en/latest/>`__ or read it
        from ``/docs``.
        
        .. |Build Status| image:: https://travis-ci.org/wtsi-hgi/python-json.svg
           :target: https://travis-ci.org/wtsi-hgi/python-json
        .. |codecov.io| image:: https://codecov.io/gh/wtsi-hgi/python-json/graph/badge.svg
           :target: https://codecov.io/gh/wtsi-hgi/python-json/
        .. |Documentation Status| image:: https://readthedocs.org/projects/hgi-json/badge/?version=latest
           :target: http://hgi-json.readthedocs.io/en/latest/?badge=latest
        
Keywords: json,serialization
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
