djblets.db.fields.json_field¶

JSONValue¶

A type indicating a valid value in JSON data.

As of the time this was added, Python does not have its own JSON value definition, and type checkers do not allow for recursive definitions. This is currently very generic, but may be expanded or aliased in the future.

Deprecated since version 3.3: Consumers should use the more complete djblets.util.typing.JSONValue instead.

New in version 3.1.

JSONDict¶

A type for a JSON dictionary.

Deprecated since version 3.3: Consumers should use the more complete djblets.util.typing.JSONDict instead.

New in version 3.1.

alias of Dict[str, object]

class JSONFormField(encoder=None, encoder_cls=None, encoder_kwargs=None, *args, **kwargs)¶

Bases: CharField

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

__init__(encoder=None, encoder_cls=None, encoder_kwargs=None, *args, **kwargs)¶

Initialize the field.

Parameters:

• encoder (json.JSONEncoder, optional) –

  The explicit JSON encoder instance to use. If specified, this takes priority over encoder_cls and encoder_kwargs, and will prevent the field from nicely formatting the contents for editing.

  Deprecated since version 1.0.1: encoder_cls and encoder_kwargs should be used instead.

• encoder_cls (type, optional) – The type of encoder to use for serializing the JSON document for editing. This must be a subclass of json.JSONEncoder.

• encoder_kwargs (dict, optional) – Keyword arguments to pass to the constructor for the encoder.

• *args (tuple) – Extra positional arguments to pass to the field.

• **kwargs (dict) – Extra keyword arguments to pass to the field.

prepare_value(value)¶

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)¶

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)¶

Bases: TextField

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.

serialize_to_string = True¶

default_validators = [<function validate_json>]¶

default_error_messages = {'invalid_type': '%(type)s is not a supported value type.'}¶

__init__(verbose_name=None, name=None, encoder_cls=None, encoder_kwargs=None, **kwargs)¶

Initialize the field.

Parameters:

• verbose_name (unicode, optional) – The verbose name shown for the field.

• name (unicode, optional) – The attribute name of the field.

• encoder_cls (type, optional) – The type of encoder to use for serializing the JSON document for storage and editing. This must be a subclass of json.JSONEncoder.

• encoder_kwargs (dict, optional) – Keyword arguments to pass to the constructor for the encoder. This may be modified by the field.

• **kwargs (dict) – Additional keyword arguments for the field.

encoder()¶

An encoder instance used for this field.

contribute_to_class(cls, name)¶

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)¶

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)¶

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)¶

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)¶

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)¶

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)¶

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)¶

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)¶

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()¶

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.

New in version 0.9.

Returns:

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

Return type:

tuple