Metadata-Version: 2.1
Name: jsonlight
Version: 0.0.3
Summary: json with rudimentary type encoding/decoding for Python
Home-page: https://yourlabs.io/oss/jsonlight
Author: James Pic
Author-email: jamespic@gmail.com
License: MIT
Description: jsonlight: json with rudimentary type encoding/decoding for Python
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Adds support for a couple of new Python magic methods to make Python object
        oriented JSON encoding and decoding a bit easier, with the following goals in
        mind:
        
        - jsonlight.dumps should always work, even if it has to fallback to a string
        - it detects if an object being dumped defines a ``__jsondump__`` method
        - it detects if an object being dumped is of a type defined in the global
          typemap, or the one that's being used
        - for complete round-tripping, the type schema is maintained in a
          ``__jsonload__`` method that you must implement
        
        Standard types
        --------------
        
        This is what you can already do in Python:
        
        .. code:: python
        
            from jsonlight import loads, dumps
            from uuid import UUID, uuid4
        
            obj = uuid4()
            assert obj == UUID(loads(dumps(str(obj))))
        
        All standard Python types such as UUID must have an encode/decode method in the
        default typemap provided by jsonlight, so encoding to JSON should always work.
        However, the type must be specified on load:
        
        .. code:: python
        
            from jsonlight import loads, dumps
            from uuid import UUID, uuid4
        
            obj = uuid4()
            assert obj == loads(UUID, dumps(obj))
        
        You can see that the main difference with ``json.loads`` is that
        ``jsonlight.loads`` requires a type as first argument. This is because
        ``jsonlight.loads`` will first call ``json.loads`` to convert the string into a
        Python object with basic JSON tyes, and then pass that to the type's
        ``__jsonload__`` function.
        
        Nested types
        ------------
        
        You may leverage the ``__jsondump__`` and ``__jsonload__`` methods based on the
        following conventions:
        
        - ``__jsondump__``: return a representation of self with JSON data types
        - ``__jsonload__``: instanciate an object based on the result from __jsondump__
        
        Example:
        
        .. code-block:: python
        
            from jsonlight import load
        
            class YourClass:
                def __init__(self):
                    self.now = datetime.now()
        
                def __jsondump__(self):
                    return dict(now=self.now)
        
                @classmethod
                def __jsonload__(cls, data):
                    return cls(load(datetime, data['now'])
        
        
        As you can see:
        
        - you don't have to worry about calling ``__jsondump__`` on return values of
          your own ``__jsondump__`` because ``jsonlight.dumps`` will do that
          recursively,
        - you have full control on deserialization just like with ``__setstate__``, but
          if you call jsonlight.load in there yourself then you don't have to
          duplicate deserialization logic on nested objects,
        
        Typemaps
        --------
        
        This lib must support all standard Python types, and it already works for
        things like UUID or Path because they cast fine from and to strings.
        
        If you decided that you wanted to remove the leading slash of all Path objects
        dumps and ensure there is one on load for example, then you could do so by
        setting the encoder and decoder functions in a typemap:
        
        .. code-block:: python
        
            typemap = {
                Path: (
                    lambda value: str(value).lstrip('/'),
                    lambda data: Path('/' + data.lstrip('/')),
                ),
            }
            assert dumps(Path('/foo/bar'), typemap) == '"foo/bar"'
            assert loads(Path, '"foo/bar"', typemap)
        
        However, this is not the case for datetimes and there is no JSON standard for
        datetimes. Since it is a requirement for jsonlight to support all standard
        python types, a default typemap is also included, which makes datetimes export
        to string with ``.isoformat()`` and from string with ``.fromisoformat()``:
        
        .. code-block:: python
        
            now = datetime.now()
            assert now == loads(datetime, dumps(now))
Keywords: cli
Platform: UNKNOWN
Description-Content-Type: text/x-rst
Provides-Extra: test
