Skip to main content

A library for dealing with JSON as python objects

Project description

jsonobject

Build Status Downloads Supported Versions Contributors

jsonobject is a python library for handling deeply nested JSON objects as well-schema'd python objects.

jsonobject is made by Dimagi, where we build, use, and contribute to OSS in our mission to reduce inequity in the world.

jsonobject is inspired by and largely API compatible with the Document/DocumentSchema portion of couchdbkit. Because jsonobject is not only simpler and standalone, but also faster, we also maintain a fork of couchdbkit, jsonobject-couchdbkit, that is backed by jsonobject and works seamlessly as a swap-in replacement for the main library.

It is used heavily in CommCare HQ (source), and the API is largely stable, but more advanced features may change in the future.

Getting Started

To install using pip, simply run

pip install jsonobject

Example

The code below defines a simple user model, and its natural mapping to JSON.

from jsonobject import *

class User(JsonObject):
    username = StringProperty()
    name = StringProperty()
    active = BooleanProperty(default=False)
    date_joined = DateTimeProperty()
    tags = ListProperty(unicode)

Once it is defined, it can be used to wrap or produce deserialized JSON.

>>> user1 = User(
    name='John Doe',
    username='jdoe',
    date_joined=datetime.datetime.utcnow(),
    tags=['generic', 'anonymous']
)
>>> user1.to_json()
{
    'name': u'John Doe',
    'username': u'jdoe',
    'active': False,
    'date_joined': '2013-08-05T02:46:58Z',
    'tags': [u'generic', u'anonymous']
}

Notice that the datetime is converted to an ISO format string in JSON, but is a real datetime on the object:

>>> user1.date_joined
datetime.datetime(2013, 8, 5, 2, 46, 58)

The jsonobject Constructor

A JsonObject subclass that has been defined as User above comes with a lot of built-in functionality. The basic operations are

  1. Make a new object from deserialized JSON (e.g. the output of json.loads)
  2. Construct a new object with given values
  3. Modify an object
  4. Dump to deserialized json (e.g. the input of json.dumps)

1 & 2 are accomplished with the constructor. There are two main ways to call the constructor:

User(
    name='John Doe',
    username='jdoe',
    date_joined=datetime.datetime.utcnow(),
    tags=['generic', 'anonymous']
)

as above (satisfies #2) and

User({
    'name': u'John Doe',
    'username': u'jdoe',
    'active': False,
    'date_joined': '2013-08-05T02:46:58Z',
    'tags': [u'generic', u'anonymous']
})

(satisfies #1). These two styles can also be mixed and matched:

User({
    'name': u'John Doe',
    'username': u'jdoe',
    'active': False,
    'tags': [u'generic', u'anonymous']
}, date_joined=datetime.datetime.utcnow())

Notice how datetimes are stored as strings in the deserialized JSON, but as datetime.datetimes in the nice python object—we will refer to these as the "json" representation and the "python" representation, or alternatively the "unwrapped" representation and the "wrapped" representation.

Gotcha. When calling the constructor, remember that the keyword argument style requires you to pass in the "python" representation (e.g. a datetime) while the json-wrapping style of passing in a dict requires you to give it in the "json" representation (e.g. a datetime-formatted string).

Property Types

There are two main kinds of property types: scalar types (like string, bool, int, datetime, etc.) and container types (list, dict, set). They are dealt with separately below.

Scalar Types

All scalar properties can take the value None in addition to the values particular to their type (strings, bools, etc). If set to the wrong type, properties raise a jsonobject.exceptions.BadValueError:

class Foo(jsonobject.JsonObject):
    b = jsonobject.BooleanProperty()
>>> Foo(b=0)
Traceback (most recent call last):
  [...]
jsonobject.exceptions.BadValueError: 0 not of type <type 'bool'>

jsonobject.StringProperty

Maps to a unicode. Usage:

class Foo(jsonobject.JsonObject):
    s = jsonobject.StringProperty()

If you set it to an ascii str it will implicitly convert to unicode:

>>> Foo(s='hi')  # converts to unicode
Foo(s=u'hi')

If you set it to a non-ascii str, it will fail with a UnicodeDecodeError:

>>> Foo(s='\xff')
Traceback (most recent call last):
  [...]
UnicodeDecodeError: 'ascii' codec can't decode byte 0xff in position 0: ordinal not in range(128)

jsonobject.BooleanProperty

Maps to a bool.

jsonobject.IntegerProperty

Maps to an int or long.

jsonobject.FloatProperty

Maps to a float.

jsonobject.DecimalProperty

Maps to a decimal.Decimal and stored as a JSON string. This type, unlike FloatProperty, stores the "human" representation of the digits. Usage:

class Foo(jsonobject.JsonObject):
    number = jsonobject.DecimalProperty()

If you set it to an int or float, it will implicitly convert to Decimal:

>>> Foo(number=1)
Foo(number=Decimal('1'))
>>> Foo(number=1.2)
Foo(number=Decimal('1.2'))

If you set it to a str or unicode, however, it raises an AssertionError:

>>> Foo(number='1.0')
Traceback (most recent call last):
  [...]
AssertionError

Todo: this should really raise a BadValueError.

If you pass in json in which the Decimal value is a str or unicode, but it is malformed, it throws the same errors as decimal.Decimal.

>>> Foo({'number': '1.0'})
Foo(number=Decimal('1.0'))
>>> Foo({'number': '1.0.0'})
Traceback (most recent call last):
  [...]
decimal.InvalidOperation: Invalid literal for Decimal: '1.0.0'

jsonobject.DateProperty

Maps to a datetime.date and stored as a JSON string of the format '%Y-%m-%d'. Usage:

class Foo(jsonobject.JsonObject):
    date = jsonobject.DateProperty()

Wrapping a badly formatted string raises a BadValueError:

>>> Foo({'date': 'foo'})
Traceback (most recent call last):
  [...]
jsonobject.exceptions.BadValueError: 'foo' is not a date-formatted string

jsonobject.DateTimeProperty

Maps to a timezone-unaware datetime.datetime and stored as a JSON string of the format '%Y-%m-%dT%H:%M:%SZ'.

While it works perfectly with good inputs, it is extremely sloppy when it comes to dealing with inputs that don't match the exact specified format. Rather than matching stricty, it simply truncates the string to the first 19 characters and tries to parse that as '%Y-%m-%dT%H:%M:%S'. This ignores both microseconds and, even worse, the timezone. This is a holdover from couchdbkit.

In newer versions of jsonboject, you may optionally specify a DateTimeProperty as exact:

class Foo(jsonobject.JsonObject):
    date = jsonobject.DateTimeProperty(exact=True)

This provides a much cleaner conversion model that has the following properties:

  1. It preserves microseconds
  2. The incoming JSON representation must match '%Y-%m-%dT%H:%M:%S.%fZ' exactly. (This is similar to the default output, except for the mandatory 6 decimal places, i.e. milliseconds.)
  3. Representations that don't match exactly will be rejected with a BadValueError.

Recommendation: If you are not locked into couchdbkit's earlier bad behavior, you should always use the exact=True flag on DateTimePropertys and TimePropertys (below).

jsonobject.TimeProperty

Maps to a datetime.time, stored as a JSON string of the format '%H:%M:%S'.

To get access to milliseconds and strict behavior, use the exact=True setting which strictly accepts the format '%H:%M:%S.%f'. This is always recommended. For more information please read the previous section on DateTimeProperty.

Container Types

Container types generally take a first argument, item_type, specifying the type of the contained objects.

jsonobject.ObjectProperty(item_type)

Maps to a dict that has a schema specified by item_type, which must be itself a subclass of JsonObject. Usage:

class Bar(jsonobject.JsonObject):
    name = jsonobject.StringProperty()


class Foo(jsonobject.JsonObject):
    bar = jsonobject.ObjectProperty(Bar)

If not specified, it will be set to a new object with default values:

>>> Foo()
Foo(bar=Bar(name=None))

If you want it set to None you must do so explicitly.

jsonobject.ListProperty(item_type)

Maps to a list with items of type item_type, which can be any of the following:

  • an instance of a property class. This is the most flexible option, and all validation (required, etc.) will be done as as specified by the property instance.
  • a property class, which will be instantiated with required=True
  • one of their corresponding python types (i.e. int for IntegerProperty, etc.)
  • a JsonObject subclass

Note that a property class (as well as the related python type syntax) will be instantiated with required=True, so ListProperty(IntegerProperty) and ListProperty(int) do not allow None, and ListProperty(IntegerProperty()) does allow None.

The serialization behavior of whatever item type is given is recursively applied to each member of the list.

If not specified, it will be set to an empty list.

jsonobject.SetProperty(item_type)

Maps to a set and stored as a list (with only unique elements). Otherwise its behavior is very much like ListProperty's.

jsonobject.DictProperty(item_type)

Maps to a dict with string keys and values specified by item_type. Otherwise its behavior is very much like ListProperty's.

If not specified, it will be set to an empty dict.

Other

jsonobject.DefaultProperty()

This flexibly wraps any valid JSON, including all scalar and container types, dynamically detecting the value's type and treating it with the corresponding property.

Property options

Certain parameters may be passed in to any property.

For example, required is one such parameter in the example below:

class User(JsonObject):
    username = StringProperty(required=True)

Here is a complete list of properties:

  • default

    Specifies a default value for the property

  • name

    The name of the property within the JSON representation*. This defaults to the name of the python property, but you can override it if you wish. This can be useful, for example, to get around conflicting with python keywords:

    >>> class Route(JsonObject):
    ...     from_ = StringProperty(name='from')
    ...     to = StringProperty()  # name='to' by default
    >>> Route(from_='me', to='you').to_json()
    {'from': u'me', 'to': u'you'}
    

    Notice how an underscore is present in the python property name ('from_'), but absent in the JSON property name ('from').

    \*If you're wondering how `StringProperty`'s `name` parameter could possibly default to `to` in the example above, when it doesn't have access to the `Route` class's properties at init time, you're completely right. The behavior described is implemented in `JsonObject`'s `__metaclass__`, which *does* have access to the `Route` class's properties.
  • choices

    A list of allowed values for the property. (Unless otherwise specified, None is also an allowed value.)

  • required

    Defaults to False. For scalar properties requires means that the value None may not be used. For container properties it means they may not be empty or take the value None.

  • exclude_if_none

    Defaults to False. When set to true, this property will be excluded from the JSON output when its value is falsey. (Note that currently this is at odds with the parameter's name, since the condition is that it is falsey, not that it is None).

  • validators

    A single validator function or list of validator functions. Each validator function should raise an exception on invalid input and do nothing otherwise.

  • verbose_name

    This property does nothing and was added to match couchdbkit's API.

Performance Comparison with Couchdbkit

In order to do a direct comparison with couchdbkit, the test suite includes a large sample schema originally written with couchdbkit. It is easy to swap in jsonobject for couchdbkit and run the tests with each. Here are the results:

$ python -m unittest test.test_couchdbkit
....
----------------------------------------------------------------------
Ran 4 tests in 1.403s

OK
$ python -m unittest test.test_couchdbkit
....
----------------------------------------------------------------------
Ran 4 tests in 0.153s

OK

Development Lifecycle

jsonobject versions follow semantic versioning. Version information can be found in CHANGES.md.

Information for developers and maintainers, such as how to run tests and release new versions, can be found in LIFECYCLE.md.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonobject-2.3.1.tar.gz (570.0 kB view details)

Uploaded Source

Built Distributions

jsonobject-2.3.1-cp313-cp313-musllinux_1_2_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.13musllinux: musl 1.2+ x86-64

jsonobject-2.3.1-cp313-cp313-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.5+ x86-64

jsonobject-2.3.1-cp312-cp312-musllinux_1_2_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.12musllinux: musl 1.2+ x86-64

jsonobject-2.3.1-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.5+ x86-64

jsonobject-2.3.1-cp311-cp311-musllinux_1_2_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.11musllinux: musl 1.2+ x86-64

jsonobject-2.3.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.17+ x86-64

jsonobject-2.3.1-cp310-cp310-musllinux_1_2_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.10musllinux: musl 1.2+ x86-64

jsonobject-2.3.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.17+ x86-64

jsonobject-2.3.1-cp39-cp39-musllinux_1_2_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.9musllinux: musl 1.2+ x86-64

jsonobject-2.3.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.9manylinux: glibc 2.17+ x86-64

File details

Details for the file jsonobject-2.3.1.tar.gz.

File metadata

  • Download URL: jsonobject-2.3.1.tar.gz
  • Upload date:
  • Size: 570.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for jsonobject-2.3.1.tar.gz
Algorithm Hash digest
SHA256 d771ca4d055acd3843b60ef58eb26322bc2094809cf0f9643846fc628083e8a5
MD5 24e5d38f4505c7e4234c105c07375de7
BLAKE2b-256 971eeaa7426dc6499a5cc0699155d48020bbab06de3e8c48fcea003281d084bc

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1.tar.gz:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp313-cp313-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp313-cp313-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 21a39275ed2c5e2065296268ff3c05ddb619098da0e97358efb6ef66dc4c4f52
MD5 fde9aa82a62f542a0e3ee165ad4113fa
BLAKE2b-256 a4cca6748dcaa22f4b2bc06f1e4214850d7c9a11bd77ee66330f0ad9085cea6a

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp313-cp313-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp313-cp313-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp313-cp313-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3544a5edfedf7af746347e7b8a10094a6151d89bffedc044887f53a996ff48b2
MD5 0d44d5441faddd01000c880ab3dec1e7
BLAKE2b-256 10bb182628558fc7714005276c5d58cb8612f484bade43ed9a1964b3b17ce8b6

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp313-cp313-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp312-cp312-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp312-cp312-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 8e4abe4fcea3e6b20b664c1b003e62dea219747377ee52ac97154944c6464e51
MD5 c2219dd90a8d4cdd3918899f91a4fb15
BLAKE2b-256 49238fda0dabf81d92561a6a7b62d7d437c49d502d690af81a991b53d5a78a94

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp312-cp312-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b5e2e75bb5194213c3638f4e130181afe5150868b62c4619e0a623a35bda88e8
MD5 607e303aeb33e0c1501b5674a320e988
BLAKE2b-256 3ba6c2b803e03a93a729679c8e16556f5c392da280ed9681a4f95b11fa134eea

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp311-cp311-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp311-cp311-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 0c26249139d0e3d651b79b26bccbb16baa8c7578b67b4f6af279f78bd761af92
MD5 c8433b46aa752c5f6549bb9166cb2007
BLAKE2b-256 b4d9ddf8fb667c7f5bc1669aec6b86827395a960eef52512ffd3dc0dc3055000

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp311-cp311-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 05e16496e128143359d31da5ef3ae090bd882519a6906c5633157c646e04c600
MD5 0b7f57ae0cb01b6e3fb25fad3e12dc71
BLAKE2b-256 d38064f94e6ccff52e0bbf38ad6652a86748cd08c90c7f50af0e3fcd4157f213

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp310-cp310-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp310-cp310-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 4cd5f4541b8aa209803dc146657c0f454a3992dd730df4786c2b458408f62e57
MD5 e53429ad7d47977490a03e07dbb6daa7
BLAKE2b-256 6be3de9b3520d7368a19399e13e79b47a3c09fa128abcec783ee1da9d89fa6fe

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp310-cp310-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 39b21d9bc1be813387081fbf8cf3554f78f1a28cad212f7b044095de5a499021
MD5 b292949cd162debbae8d80a719c1d7eb
BLAKE2b-256 6c1293fdcf8188fec09179f20771b6a32be5b87db662c1461454bdfd3008d4da

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp39-cp39-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp39-cp39-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 4f3058c0b1e205a8808b67a4ddd36b32b9cc21da15a8a684f8d9bbc05abeb3f2
MD5 52167286f4b804dc2f88babc62f1c984
BLAKE2b-256 8e8abe3dd6b7763e6ac71251dd68389fd9fab0c56065d50e3724f2395c52162a

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp39-cp39-musllinux_1_2_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file jsonobject-2.3.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for jsonobject-2.3.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9f318fd178a81875ef133d53d9c33134fb5785b43c5c26f70e87c2c199783f4c
MD5 a9b9469cfdc8375f55c7ef2669c88cfe
BLAKE2b-256 6609d2a0a0ddb6aaf936768707b3698549878a9d8a4fd9aa9c3f7c246eeb6363

See more details on using hashes here.

Provenance

The following attestation bundles were made for jsonobject-2.3.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: pypi.yml on dimagi/jsonobject

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page