djblets.db.fields¶
-
class
Base64DecodedValue[source]¶ Bases:
strA subclass of string that can be identified by Base64Field, in order to prevent double-encoding or double-decoding.
-
class
Base64Field(verbose_name=None, name=None, primary_key=False, max_length=None, unique=False, blank=False, null=False, db_index=False, rel=None, default=<class django.db.models.fields.NOT_PROVIDED>, editable=True, serialize=True, unique_for_date=None, unique_for_month=None, unique_for_year=None, choices=None, help_text=u”, db_column=None, db_tablespace=None, auto_created=False, validators=[], error_messages=None)[source]¶ Bases:
django.db.models.fields.TextFieldA subclass of TextField that encodes its data as base64 in the database. This is useful if you’re dealing with unknown encodings and must guarantee that no modifications to the text occurs and that you can read/write the data in any database with any encoding.
-
class
ModificationTimestampField(verbose_name=None, name=None, **kwargs)[source]¶ Bases:
django.db.models.fields.DateTimeFieldA subclass of DateTimeField that only auto-updates the timestamp when updating an existing object or when the value of the field is None. This specialized field is equivalent to DateTimeField’s auto_now=True, except it allows for custom timestamp values (needed for serialization/deserialization).
-
class
JSONFormField(encoder=None, *args, **kwargs)[source]¶ Bases:
django.forms.fields.CharFieldProvides a form field for JSON input.
This is meant to be used by JSONField, and handles the work of normalizing a Python data structure back into a serialized JSON string for editing.
-
class
JSONField(verbose_name=None, name=None, encoder=<django.core.serializers.json.DjangoJSONEncoder object>, **kwargs)[source]¶ Bases:
django.db.models.fields.TextFieldA field for storing JSON-encoded data. The data is accessible as standard Python data types and is transparently encoded/decoded to/from a JSON string in the database.
-
__init__(verbose_name=None, name=None, encoder=<django.core.serializers.json.DjangoJSONEncoder object>, **kwargs)[source]¶
-
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
-
-
class
CounterField(verbose_name=None, name=None, initializer=None, default=None, **kwargs)[source]¶ Bases:
django.db.models.fields.IntegerFieldA field that provides atomic counter updating and smart initialization.
The CounterField makes it easy to atomically update an integer, incrementing or decrementing it, without raise conditions or conflicts. It can update a single instance at a time, or a batch of objects at once.
CounterField is useful for storing counts of objects, reducing the number of queries performed. This requires that the calling code properly increments or decrements at all the right times, of course.
This takes an optional
initializerparameter that, if provided, can be used to auto-populate the field the first time the model instance is loaded, perhaps based on querying a number of related objects. The value passed toinitializermust be a function taking the model instance as a parameter, and must return an integer or None. If it returns None, the counter will not be updated or saved.The model instance will gain four new functions:
increment_{field_name}- Atomically increment by one.decrement_{field_name}- Atomically decrement by one.reload_{field_name}- Reload the value in this instance from the- database.
reinit_{field_name}- Re-initializes the stored field using the- initializer function.
The field on the class (not the instance) provides two functions for batch-updating models:
increment- Takes a queryset and increments this field for- each object.
decrement- Takes a queryset and decrements this field for- each object.
-
classmethod
increment_many(model_instance, values, reload_object=True)[source]¶ Increments several fields on a model instance at once.
This takes a model instance and dictionary of fields to values, and will increment each of those fields by that value.
If reload_object is True, then the fields on the instance will be reloaded to reflect the current values.
-
classmethod
decrement_many(model_instance, values, reload_object=True)[source]¶ Decrements several fields on a model instance at once.
This takes a model instance and dictionary of fields to values, and will decrement each of those fields by that value.
If reload_object is True, then the fields on the instance will be reloaded to reflect the current values.
-
increment(queryset, increment_by=1)[source]¶ Increments this field on every object in the provided queryset.
-
class
RelationCounterField(rel_field_name=None, *args, **kwargs)[source]¶ Bases:
djblets.db.fields.CounterFieldA field that provides an atomic count of a relation.
RelationCounterField is a specialization of CounterField that tracks how many objects there are on the other side of a ManyToManyField or ForeignKey relation.
RelationCounterField takes the name of a relation (either a field name, for a forward ManyToManyField relation, or the “related_name” for the reverse relation of another model’s ForeignKey or ManyToManyField. (Note that using a forward ForeignKey relation is considered invalid, as the count can only be 1 or 0.)
The counter will be initialized with the number of objects on the other side of the relation, and this will be kept updated so long as all updates to the table are made using standard create/save/delete operations on models.
Note that updating a relation outside of a model’s regular API (such as through raw SQL or something like an update() call) will cause the counters to get out of sync. They would then need to be reset using
reinit_{field_name}.-
class
InstanceState(model_instance, fields)[source]¶ Bases:
objectTracks state for a RelationCounterField assocation.
State instances are bound to the lifecycle of a model instance. They keep track of the model instance (using a weak reference) and all RelationCounterFields tied to the relation name provided.
These are used for looking up the proper instance and RelationCounterFields on the other end of a reverse relation, given a model, relation name, and IDs, through the _instance_states dictionary.
-
class
RelationTracker(model_cls, rel_field_name)[source]¶ Bases:
objectTracks relations and updates state for all affected CounterFields.
This class is responsible for all the hard work of updating RelationCounterFields refererring to a relation, based on updates to that relation. It’s really the meat of RelationCounterField.
Each RelationTracker is responsible for a given model/relation name pairing, across all instances of a model and across all RelationCounterFields following that relation name.
The main reason the code lives here instead of in each RelationCounterField is to keep state better in sync and to ensure we’re only ever dealing with one set of queries per relation name. We’re also simplifying signal registration, helping to make things less error-prone.
-
class