jsonfield


Namejsonfield JSON
Version 3.1.0 PyPI version JSON
download
home_pagehttps://github.com/rpkilby/jsonfield/
SummaryA reusable Django field that allows you to store validated JSON in your model.
upload_time2020-02-22 08:42:30
maintainerRyan P Kilby
docs_urlNone
authorBrad Jasper
requires_python>=3.6
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            jsonfield
=========

.. image:: https://circleci.com/gh/rpkilby/jsonfield.svg?style=shield
  :target: https://circleci.com/gh/rpkilby/jsonfield
.. image:: https://codecov.io/gh/rpkilby/jsonfield/branch/master/graph/badge.svg
  :target: https://codecov.io/gh/rpkilby/jsonfield
.. image:: https://img.shields.io/pypi/v/jsonfield.svg
  :target: https://pypi.org/project/jsonfield
.. image:: https://img.shields.io/pypi/l/jsonfield.svg
  :target: https://pypi.org/project/jsonfield

**jsonfield** is a reusable model field that allows you to store validated JSON, automatically handling
serialization to and from the database. To use, add ``jsonfield.JSONField`` to one of your models.

**Note:** `django.contrib.postgres`_ now supports PostgreSQL's jsonb type, which includes extended querying
capabilities. If you're an end user of PostgreSQL and want full-featured JSON support, then it is
recommended that you use the built-in JSONField. However, jsonfield is still useful when your app
needs to be database-agnostic, or when the built-in JSONField's extended querying is not being leveraged.
e.g., a configuration field.

.. _django.contrib.postgres: https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/#jsonfield


Requirements
------------

**jsonfield** aims to support all current `versions of Django`_, however the explicity tested versions are:

* **Python:** 3.6, 3.7, 3.8
* **Django:** 2.2, 3.0

.. _versions of Django: https://www.djangoproject.com/download/#supported-versions


Installation
------------

.. code-block:: python

    pip install jsonfield


Usage
-----

.. code-block:: python

    from django.db import models
    from jsonfield import JSONField

    class MyModel(models.Model):
        json = JSONField()


Querying
--------

As stated above, ``JSONField`` is not intended to provide extended querying capabilities.
That said, you may perform the same basic lookups provided by regular text fields (e.g.,
``exact`` or ``regex`` lookups). Since values are stored as serialized JSON, it is highly
recommended that you test your queries to ensure the expected results are returned.


Handling null values
--------------------

A model field's ``null`` argument typically controls whether null values may be stored in
its column by setting a not-null constraint. However, because ``JSONField`` serializes its
values (including nulls), this option instead controls *how* null values are persisted. If
``null=True``, then nulls are **not** serialized and are stored as a null value in the
database. If ``null=False``, then the null is instead stored in its serialized form.

This in turn affects how null values may be queried. Both fields support exact matching:

.. code-block:: python

    MyModel.objects.filter(json=None)

However, if you want to use the ``isnull`` lookup, you must set ``null=True``.

.. code-block:: python

    class MyModel(models.Model):
        json = JSONField(null=True)

    MyModel.objects.filter(json__isnull=True)

Note that as ``JSONField.null`` does not prevent nulls from being stored, achieving this
must instead be handled with a validator.


Advanced Usage
--------------

By default python deserializes json into dict objects. This behavior differs from the standard json
behavior  because python dicts do not have ordered keys. To overcome this limitation and keep the
sort order of OrderedDict keys the deserialisation can be adjusted on model initialisation:

.. code-block:: python

    import collections

    class MyModel(models.Model):
        json = JSONField(load_kwargs={'object_pairs_hook': collections.OrderedDict})


Other Fields
------------

**jsonfield.JSONCharField**

Subclasses **models.CharField** instead of **models.TextField**.


Running the tests
-----------------

The test suite requires ``tox``.

.. code-block:: shell

    $ pip install tox


Then, run the ``tox`` command, which will run all test jobs.

.. code-block:: shell

    $ tox

Or, to test just one job (for example Django 2.0 on Python 3.6):

.. code-block:: shell

    $ tox -e py36-django20


Release Process
---------------

* Update changelog
* Update package version in setup.py
* Check supported versions in setup.py and readme
* Create git tag for version
* Upload release to PyPI test server
* Upload release to official PyPI server

.. code-block:: shell

    $ pip install -U pip setuptools wheel twine
    $ rm -rf dist/ build/
    $ python setup.py sdist bdist_wheel
    $ twine upload -r test dist/*
    $ twine upload dist/*


Changes
-------

Take a look at the `changelog`_.

.. _changelog: https://github.com/rpkilby/jsonfield/blob/master/CHANGES.rst



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/rpkilby/jsonfield/",
    "name": "jsonfield",
    "maintainer": "Ryan P Kilby",
    "docs_url": null,
    "requires_python": ">=3.6",
    "maintainer_email": "kilbyr@gmail.com",
    "keywords": "",
    "author": "Brad Jasper",
    "author_email": "contact@bradjasper.com",
    "download_url": "https://files.pythonhosted.org/packages/10/3b/4542fd9465908380ba4321329d3cdfeb959769ec48d878dead978286b48d/jsonfield-3.1.0.tar.gz",
    "platform": "",
    "description": "jsonfield\n=========\n\n.. image:: https://circleci.com/gh/rpkilby/jsonfield.svg?style=shield\n  :target: https://circleci.com/gh/rpkilby/jsonfield\n.. image:: https://codecov.io/gh/rpkilby/jsonfield/branch/master/graph/badge.svg\n  :target: https://codecov.io/gh/rpkilby/jsonfield\n.. image:: https://img.shields.io/pypi/v/jsonfield.svg\n  :target: https://pypi.org/project/jsonfield\n.. image:: https://img.shields.io/pypi/l/jsonfield.svg\n  :target: https://pypi.org/project/jsonfield\n\n**jsonfield** is a reusable model field that allows you to store validated JSON, automatically handling\nserialization to and from the database. To use, add ``jsonfield.JSONField`` to one of your models.\n\n**Note:** `django.contrib.postgres`_ now supports PostgreSQL's jsonb type, which includes extended querying\ncapabilities. If you're an end user of PostgreSQL and want full-featured JSON support, then it is\nrecommended that you use the built-in JSONField. However, jsonfield is still useful when your app\nneeds to be database-agnostic, or when the built-in JSONField's extended querying is not being leveraged.\ne.g., a configuration field.\n\n.. _django.contrib.postgres: https://docs.djangoproject.com/en/dev/ref/contrib/postgres/fields/#jsonfield\n\n\nRequirements\n------------\n\n**jsonfield** aims to support all current `versions of Django`_, however the explicity tested versions are:\n\n* **Python:** 3.6, 3.7, 3.8\n* **Django:** 2.2, 3.0\n\n.. _versions of Django: https://www.djangoproject.com/download/#supported-versions\n\n\nInstallation\n------------\n\n.. code-block:: python\n\n    pip install jsonfield\n\n\nUsage\n-----\n\n.. code-block:: python\n\n    from django.db import models\n    from jsonfield import JSONField\n\n    class MyModel(models.Model):\n        json = JSONField()\n\n\nQuerying\n--------\n\nAs stated above, ``JSONField`` is not intended to provide extended querying capabilities.\nThat said, you may perform the same basic lookups provided by regular text fields (e.g.,\n``exact`` or ``regex`` lookups). Since values are stored as serialized JSON, it is highly\nrecommended that you test your queries to ensure the expected results are returned.\n\n\nHandling null values\n--------------------\n\nA model field's ``null`` argument typically controls whether null values may be stored in\nits column by setting a not-null constraint. However, because ``JSONField`` serializes its\nvalues (including nulls), this option instead controls *how* null values are persisted. If\n``null=True``, then nulls are **not** serialized and are stored as a null value in the\ndatabase. If ``null=False``, then the null is instead stored in its serialized form.\n\nThis in turn affects how null values may be queried. Both fields support exact matching:\n\n.. code-block:: python\n\n    MyModel.objects.filter(json=None)\n\nHowever, if you want to use the ``isnull`` lookup, you must set ``null=True``.\n\n.. code-block:: python\n\n    class MyModel(models.Model):\n        json = JSONField(null=True)\n\n    MyModel.objects.filter(json__isnull=True)\n\nNote that as ``JSONField.null`` does not prevent nulls from being stored, achieving this\nmust instead be handled with a validator.\n\n\nAdvanced Usage\n--------------\n\nBy default python deserializes json into dict objects. This behavior differs from the standard json\nbehavior  because python dicts do not have ordered keys. To overcome this limitation and keep the\nsort order of OrderedDict keys the deserialisation can be adjusted on model initialisation:\n\n.. code-block:: python\n\n    import collections\n\n    class MyModel(models.Model):\n        json = JSONField(load_kwargs={'object_pairs_hook': collections.OrderedDict})\n\n\nOther Fields\n------------\n\n**jsonfield.JSONCharField**\n\nSubclasses **models.CharField** instead of **models.TextField**.\n\n\nRunning the tests\n-----------------\n\nThe test suite requires ``tox``.\n\n.. code-block:: shell\n\n    $ pip install tox\n\n\nThen, run the ``tox`` command, which will run all test jobs.\n\n.. code-block:: shell\n\n    $ tox\n\nOr, to test just one job (for example Django 2.0 on Python 3.6):\n\n.. code-block:: shell\n\n    $ tox -e py36-django20\n\n\nRelease Process\n---------------\n\n* Update changelog\n* Update package version in setup.py\n* Check supported versions in setup.py and readme\n* Create git tag for version\n* Upload release to PyPI test server\n* Upload release to official PyPI server\n\n.. code-block:: shell\n\n    $ pip install -U pip setuptools wheel twine\n    $ rm -rf dist/ build/\n    $ python setup.py sdist bdist_wheel\n    $ twine upload -r test dist/*\n    $ twine upload dist/*\n\n\nChanges\n-------\n\nTake a look at the `changelog`_.\n\n.. _changelog: https://github.com/rpkilby/jsonfield/blob/master/CHANGES.rst\n\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A reusable Django field that allows you to store validated JSON in your model.",
    "version": "3.1.0",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "13f1ad7433832529b9182c4bc772e389",
                "sha256": "df857811587f252b97bafba42e02805e70a398a7a47870bc6358a0308dd689ed"
            },
            "downloads": -1,
            "filename": "jsonfield-3.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "13f1ad7433832529b9182c4bc772e389",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6",
            "size": 7974,
            "upload_time": "2020-02-22T08:42:29",
            "upload_time_iso_8601": "2020-02-22T08:42:29.147167Z",
            "url": "https://files.pythonhosted.org/packages/7c/97/3a4805532a9c1982368fd9f37b58133419e83704744b733ccab9e9827176/jsonfield-3.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "0758b8a3b6cc67a3ba74dccdee3e8f4a",
                "sha256": "7e4e84597de21eeaeeaaa7cc5da08c61c48a9b64d0c446b2d71255d01812887a"
            },
            "downloads": -1,
            "filename": "jsonfield-3.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "0758b8a3b6cc67a3ba74dccdee3e8f4a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6",
            "size": 14870,
            "upload_time": "2020-02-22T08:42:30",
            "upload_time_iso_8601": "2020-02-22T08:42:30.846985Z",
            "url": "https://files.pythonhosted.org/packages/10/3b/4542fd9465908380ba4321329d3cdfeb959769ec48d878dead978286b48d/jsonfield-3.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2020-02-22 08:42:30",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "rpkilby",
    "github_project": "jsonfield",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "tox": true,
    "lcname": "jsonfield"
}
        
Elapsed time: 0.01355s