Jump to >

djblets.db.fields.json_field

class JSONFormField(encoder=None, encoder_cls=None, encoder_kwargs=None, *args, **kwargs)[source]

Provides a form field for JSON input.

This is meant to be used by JSONField, and handles the work of rendering JSON content in a more human-editable way for editing (by sorting keys and adding indentation), and then validating and returning the resulting JSON document back for storage in the field.

encoder

The JSON encoder being used to serialize JSON data for editing.

Type

json.JSONEncoder

prepare_value(value)[source]

Prepare a field’s value for storage in the database.

This will encode the value to JSON (unless it’s already a string).

Parameters

value (object) – The JSON-serializable value to encode.

Returns

The resulting JSON string.

Return type

unicode

to_python(value)[source]

Return the Python representation of the value in the field.

This will attempt to deserialize the value and return it. If the value is not a string, it will be returned directly.

Parameters

value (object) – The value stored for the field. This is expected to be a string representing serialized JSON data.

Returns

The deserialized JSON object, or None if it’s an empty string.

Return type

object

Raises

django.core.exceptions.ValidationError – The value was not able to be deserialized as JSON content.

class JSONField(verbose_name=None, name=None, encoder_cls=None, encoder_kwargs=None, **kwargs)[source]

A field for storing JSON-encoded data.

The data is accessible as standard Python data types and is transparently encoded to and decoded from a JSON string in the database.

Consumers can specify custom encoding behavior by providing an encoder class and keyword arguments. By default, DjbletsJSONEncoder is used, which supports lazy strings, datetimes, and model-specified custom encoding behavior.

encoder()[source]

An encoder instance used for this field.

contribute_to_class(cls, name)[source]

Add methods/signal handlers to the model owning this field.

This will add get_fieldname_json() and set_fieldname_json() methods to the model, which will allow retrieving and setting the serialized data directly.

It also listens for when an instance of the model is initialized and sets the field to point to the deserialized JSON data.

Parameters
  • cls (type) – The Model class to contribute to.

  • name (unicode) – The name of this field on the model.

pre_save(model_instance, add)[source]

Return serialized field data to save on a model instance.

Parameters
  • model_instance (django.db.models.Model) – The model instance being saved.

  • add (bool, unused) – Whether this is a new instance being added to the database. This is ignored.

Returns

The serialized data to save.

Return type

unicode

post_init(instance, **kwargs)[source]

Handle initialization of a model instance.

This will deserialize the stored data from the database and set it as the field data on the model.

Parameters
  • instance (django.db.models.Model) – The model instance being initialized.

  • **kwargs (dict) – Extra keyword arguments from the signal.

get_prep_value(value)[source]

Return the serialized value prepared for storage.

This will serialize the data, if it’s a JSON structure and not already a string, preparing it for storage in the database or another location.

Parameters

value (object) – The value to prepare.

Returns

The serialized representation of the value.

Return type

unicode

value_to_string(obj)[source]

Return the serialized JSON data from the field.

Parameters

obj (django.db.models.Model) – The model instance containing the field.

Returns

The serialized JSON data from the field.

Return type

unicode

to_python(value)[source]

Return a value suitable for using in Python code.

This will return the deserialized version of the data, allowing Python code to work with the data directly.

Parameters

value (object) – The value to make usable in Python code.

Returns

The deserialized data.

Return type

object

dumps(data)[source]

Return serialized version of the provided JSON document.

If the data is already a string, it will be provided directly. Otherwise, it will use the field’s associated JSON encoder to serialize the data.

Parameters

data (object) – The data to serialize.

Returns

The serialized JSON data.

Return type

unicode

loads(val)[source]

Return a JSON document from the serialized JSON data.

This will first attempt to deserialize the JSON data using the standard JSON decoder. If it’s unable to do so, or it gets back what appears to be a double-encoded JSON document or a Python string representation of a JSON document, it will attempt to parse the value and return a proper representation.

Parameters

val (unicode) – The serialized JSON data to deserialize.

Returns

The deserialized JSON document.

Return type

object

formfield(**kwargs)[source]

Return a form field that can be used to edit this data.

Parameters

**kwargs (dict) – Keyword arguments to pass to the subclass.

Returns

The resulting form field.

Return type

JSONFormField

deconstruct()[source]

Deconstruct the field for Django migrations.

This makes JSONField migration-safe by encoding the default value to a string so that it can be safely loaded into the database.

This is only used on Django 1.7+.

New in version 0.9.

Returns

A tuple of (name, module path, positional arguments, keyword arguments).

Return type

tuple