django-jsonfield
===================

.. image:: https://codeship.com/projects/2e1a3d30-7db7-0132-629f-4abd151a3721/status?branch=default

I had a serious need for a JSON field for django. There were a couple out
there, but none packaged up nicely on bitbucket/github that were usable
with ``pip install -e``.

So I took the code from `David Cramer's blog`_, and packaged it up.

Usage
-----

To use, just install the package, and then use the field::

    from django.db import models
    import jsonfield

    class MyModel(models.Model):
        the_json = jsonfield.JSONField()

Now, it will validate the JSON on entry, and store it as a string in the
database.  When you instantiate/fetch the object, it will be turned back
into a python list/dict/string.

There is also a ``TypedJSONField``, that allows you to define data types that must be included within each object in the array. More documentation to follow.


Notes
~~~~~

If no ``default`` is provided, and ``null=True`` is not passed in to the
field constructor, then a default of ``{}`` will be used.

There are also a couple of other bits and bobs:

Extras
------

jsonify templatetag
~~~~~~~~~~~~~~~~~~~
This allows you to convert a python data structure into JSON within a template::

    {% load jsonify %}

    <script>
    var foo = {{ bar|jsonify }};
    </script>

History
----------

0.9.19
~~~~~~
Allow passing `decoder_kwargs` as an argument to a field. This dict will be passed as kwargs to
the `json.loads()` calls when loading data that is a string.

You may also set this as a global value in settings.JSONFIELD_DECODER_KWARGS.

A new dict is created for each field: so if this value is altered after field definition, it shouldn't
affect already attached fields.

0.9.16
~~~~~~
Allow passing an argument of `encoder_class` to a field, which will result in that object (or
the object located at that path, for instance `core.utils.JSONEncoder`) being used as the `cls`
argument when serializing objects.

You may also set this as a global value in settings.JSONFIELD_ENCODER_CLASS

0.9.15
~~~~~~
Bump version number to get around uploading issues.

0.9.14
~~~~~~
No longer hit the db to work out db_type.

0.9.12
~~~~~~
Cache the result of db_type.
Handle incoming data from multiple select widget better.

0.9.9
~~~~~
Finally strip out non-required files.

0.9.8
~~~~~
Remove freezegun workarounds.
Fix broken build.

0.9.4
~~~~~
Fixes for mutable defaults: we serialize and then deserialize in this
case, so you can still use ``default={}``.

0.9.3
~~~~~
Remove support for storing data using Postgres' 9.2's JSON data type, as
you cannot currently query against this!

Remove support for django < 1.3.


0.9.0
~~~~~
Add LICENSE file.
Added TypedJSONField.


0.8.10
~~~~~~
Allow ``{{ variable|jsonify }}`` to work with querysets.

0.8.8
~~~~~
Prevent circular import problem with django 1.3.1 and gargoyle.

0.8.7
~~~~~
Better handle null=True and blank=True: it should make sense what they do now.

0.8.5
~~~~~
Allow for '{}' and '[]', and make them not appear to be None.

0.8.4
~~~~~
Ensure the version number file is installed with the package.

0.8.3
~~~~~
Store the version number in one place only, now.

0.8.2
~~~~~
Oops. Packaging error prevented install from pypi. Added README.rst to manifest.

0.8.1
~~~~~
Converting to string does nothing, as serializing a model instance with a JSONField would have a string version of that field, instead of it embedded inline. (Back to pre 0.8 behaviour).

Added better querying support: (``field__contains={'key':'value','key2':'value2'}`` works.)

Removed JSONTableWidget from package.

0.8
~~~
(Many thanks to `IanLewis`_ for these features)

Supports django 1.2

Supports callable and json serializable objects as default

Implemented get_db_prep_value()

Add tests and test runner.

Removed JSONTableWidget from README.

0.7.1
~~~~~
Don't fail when trying to install before django is installed.

0.7
~~~
First time I tagged releases.


Todo
----------
Allow for passing in a function to use for processing unknown data types.

Convert date/time objects nicely to/from ISO strings (YYYY-mm-dd HH:MM:SS
TZNAME). This is actually a bit tricky, as we don't know if we are expecting
a date/time object. We may parse objects as we go, but there could be
some performance issues with this. I'm tempted to say "only do this on TypedJSONField()"

.. _David Cramer's blog: http://justcramer.com/2009/04/14/cleaning-up-with-json-and-sql/
.. _IanLewis: https://bitbucket.org/IanLewis