README.rst
1jsonfield
2=========
3
4.. image:: https://circleci.com/gh/rpkilby/jsonfield.svg?style=shield
5 :target: https://circleci.com/gh/rpkilby/jsonfield
6.. image:: https://codecov.io/gh/rpkilby/jsonfield/branch/master/graph/badge.svg
7 :target: https://codecov.io/gh/rpkilby/jsonfield
8.. image:: https://img.shields.io/pypi/v/jsonfield.svg
9 :target: https://pypi.org/project/jsonfield
10.. image:: https://img.shields.io/pypi/l/jsonfield.svg
11 :target: https://pypi.org/project/jsonfield
12
13**jsonfield** is a reusable model field that allows you to store validated JSON, automatically handling
14serialization to and from the database. To use, add ``jsonfield.JSONField`` to one of your models.
15
16**Note:** `django.contrib.postgres`_ now supports PostgreSQL's jsonb type, which includes extended querying
17capabilities. If you're an end user of PostgreSQL and want full-featured JSON support, then it is
18recommended that you use the built-in JSONField. However, jsonfield is still useful when your app
19needs to be database-agnostic, or when the built-in JSONField's extended querying is not being leveraged.
20e.g., a configuration field.
21
22.. _django.contrib.postgres: https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/#jsonfield
23
24
25Requirements
26------------
27
28**jsonfield** aims to support all current `versions of Django`_, however the explicity tested versions are:
29
30* **Python:** 3.6, 3.7, 3.8
31* **Django:** 2.2, 3.0
32
33.. _versions of Django: https://www.djangoproject.com/download/#supported-versions
34
35
36Installation
37------------
38
39.. code-block:: python
40
41 pip install jsonfield
42
43
44Usage
45-----
46
47.. code-block:: python
48
49 from django.db import models
50 from jsonfield import JSONField
51
52 class MyModel(models.Model):
53 json = JSONField()
54
55
56Querying
57--------
58
59As stated above, ``JSONField`` is not intended to provide extended querying capabilities.
60That said, you may perform the same basic lookups provided by regular text fields (e.g.,
61``exact`` or ``regex`` lookups). Since values are stored as serialized JSON, it is highly
62recommended that you test your queries to ensure the expected results are returned.
63
64
65Handling null values
66--------------------
67
68A model field's ``null`` argument typically controls whether null values may be stored in
69its column by setting a not-null constraint. However, because ``JSONField`` serializes its
70values (including nulls), this option instead controls *how* null values are persisted. If
71``null=True``, then nulls are **not** serialized and are stored as a null value in the
72database. If ``null=False``, then the null is instead stored in its serialized form.
73
74This in turn affects how null values may be queried. Both fields support exact matching:
75
76.. code-block:: python
77
78 MyModel.objects.filter(json=None)
79
80However, if you want to use the ``isnull`` lookup, you must set ``null=True``.
81
82.. code-block:: python
83
84 class MyModel(models.Model):
85 json = JSONField(null=True)
86
87 MyModel.objects.filter(json__isnull=True)
88
89Note that as ``JSONField.null`` does not prevent nulls from being stored, achieving this
90must instead be handled with a validator.
91
92
93Advanced Usage
94--------------
95
96By default python deserializes json into dict objects. This behavior differs from the standard json
97behavior because python dicts do not have ordered keys. To overcome this limitation and keep the
98sort order of OrderedDict keys the deserialisation can be adjusted on model initialisation:
99
100.. code-block:: python
101
102 import collections
103
104 class MyModel(models.Model):
105 json = JSONField(load_kwargs={'object_pairs_hook': collections.OrderedDict})
106
107
108Other Fields
109------------
110
111**jsonfield.JSONCharField**
112
113Subclasses **models.CharField** instead of **models.TextField**.
114
115
116Running the tests
117-----------------
118
119The test suite requires ``tox``.
120
121.. code-block:: shell
122
123 $ pip install tox
124
125
126Then, run the ``tox`` command, which will run all test jobs.
127
128.. code-block:: shell
129
130 $ tox
131
132Or, to test just one job (for example Django 2.0 on Python 3.6):
133
134.. code-block:: shell
135
136 $ tox -e py36-django20
137
138
139Release Process
140---------------
141
142* Update changelog
143* Update package version in setup.py
144* Check supported versions in setup.py and readme
145* Create git tag for version
146* Upload release to PyPI test server
147* Upload release to official PyPI server
148
149.. code-block:: shell
150
151 $ pip install -U pip setuptools wheel twine
152 $ rm -rf dist/ build/
153 $ python setup.py sdist bdist_wheel
154 $ twine upload -r test dist/*
155 $ twine upload dist/*
156
157
158Changes
159-------
160
161Take a look at the `changelog`_.
162
163.. _changelog: https://github.com/rpkilby/jsonfield/blob/master/CHANGES.rst
164
