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
- 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
Noneif it’s an empty string.- Return type
- 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,
DjbletsJSONEncoderis used, which supports lazy strings, datetimes, and model-specified custom encoding behavior.- contribute_to_class(cls, name)[source]¶
Add methods/signal handlers to the model owning this field.
This will add
get_fieldname_json()andset_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.
- 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.
- 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
- 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
- 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