Metadata-Version: 2.0
Name: kylie
Version: 0.2.0
Summary: Kylie provides mappings between JSON data structures and Python objects.
Home-page: https://github.com/judy2k/kylie
Author: Mark Smith
Author-email: mark.smith@practicalpoetry.co.uk
License: BSD
Keywords: kylie
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4

=====
Kylie
=====

.. image:: https://img.shields.io/travis/judy2k/kylie.svg
        :target: https://travis-ci.org/judy2k/kylie

.. image:: https://img.shields.io/pypi/v/kylie.svg
        :target: https://pypi.python.org/pypi/kylie


Kylie provides mappings between JSON data structures and Python objects. It
provides a reasonable amount of power with only a tiny bit of magic, and it has
100% code coverage.

* Free software: BSD license
* Documentation: https://kylie.readthedocs.org/

It supports name and type-mapping, and it's not bound to JSON, although it is
geared to serializing and de-serializing data to and from JSON-type data
structures such as dicts, lists, strings, numbers, and bools.


Example
-------

::

    class SpanishInquisitionModel(Model):
        inquisition_id = Attribute('id')
        expected = Attribute(python_type=bool, serialized_type=int)

Then::

    >>> surprise = SpanishInquisitionModel(inquisition_id=1234, expected=False)
    >>> surprise.inquisition_id
    1234
    >>> surprise.serialize()
    {'id': 1234, expected=0}

Note that the attribute ``inquisition_id`` becomes the dict key ``"id"``, and
expected is mapped to ``0`` instead of ``False``.

We can now take this dict, ``dumps`` it to JSON, and somewhere else call
the following on the json_data (which is a dict returned from ``loads``)::

    >>> my_surprise = SpanishInquisitionModel.deserialize(json_data)
    >>> my_surprise.inquisition_id
    1234
    >>> my_surprise.expected
    False

Kylie also supports :ref:`nested models`, so you can embed other Model instances
inside the data, and Kylie will manage serialization and deserialization of
them for you.


Features
--------

* Allows :ref:`name mapping` between Models and python dictionary keys.
* Allows type conversion when serializing and de-serializing objects.
* Automatic serialization/deserialization of attributes that are also Models.
* Not bound to JSON in any way, and should also be useful for MessagePack_

.. _MessagePack: http://msgpack.org/


Non-Features
------------

So what doesn't Kylie do yet? Well, there are a few things, because it's
very new:

* Doesn't have any mechanism for validation. I am planning to add this, once I
  decide the best way to do it. *Ideas welcome!*
* Doesn't have any built-in mechanism for choosing between different types to
  deserialize a dict to. Again, you can do this through customized type mapper
  functions. At the very least, I'll document this soon. I plan to add the
  ability to automatically deserialize to a type based on, for example, a
  ``__type__`` item in the dict.
* No post-serialize or post-deserialize options, unless you do it yourself.
  This would allow wiring up of objects that are referred to by ``id`` and
  provided elsewhere in the serialized data-structure, for example.

So, lots to do! The amount of non-features currently outweighs the list of
features, but I think Kylie is already useful.


Why is it called Kylie?
-----------------------

I named it `especially for you`_. Back in the late 80's (I'm old!) Kylie and
Jason were today's Kim and Kanye. **This** Kylie works well with JSON. Geddit?

.. image:: http://upload.wikimedia.org/wikipedia/en/1/1a/KylieEspeciallyForYouCover.png

.. _especially for you: http://en.wikipedia.org/wiki/Especially_for_You




=======
History
=======

0.2.0 (2015-04-22)
------------------

* Added list support to Relation with ``sequence=True`` parameter.

0.1.1 (2015-04-12)
------------------

* Removed print statement inside class constructor.


0.1.0 (2015-04-12)
------------------

* First release on PyPI.


