djblets.db.fields.counter_field¶

Field for atomically incrementing and decrementing counters in models.

class CounterField(verbose_name=None, name=None, initializer=None, default=None, **kwargs)[source]¶

Bases: django.db.models.fields.IntegerField

A 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 initializer parameter 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 to initializer must 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 the field by one.

decrement_field_name

Atomically decrement the field 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]¶

Increment several fields on a model instance at once.

Parameters:	model_instance (django.db.models.Model) – The model instance containing the fields to increment. values (dict) – A dictionary mapping field names to delta values to increment by. reload_object (bool, optional) – Whether to reload the field values in model_instance to reflect the current values in the database after incrementing.

classmethod decrement_many(model_instance, values, reload_object=True)[source]¶

Decrement several fields on a model instance at once.

Parameters:	model_instance (django.db.models.Model) – The model instance containing the fields to decrement. values (dict) – A dictionary mapping field names to delta values to decrement by. reload_object (bool, optional) – Whether to reload the field values in model_instance to reflect the current values in the database after decrementing.

__init__(verbose_name=None, name=None, initializer=None, default=None, **kwargs)[source]¶

Initialize the field.

This can take a default value for the counter, or an initializer function that can compute a value (based on database queries or anything else needed).

Parameters:

verbose_name (unicode, optional) – The verbose name to show users in forms. This defaults to a variation of the field name. name (str, optional) – The name of the field. This defaults to the attribute name on the model. initializer (callable, optional) – A function to call to compute an initial value for the field if None or when re-initializing. default (int, optional) – An explicit default value for the field. **kwargs (dict) – Additional keyword arguments for the field.

increment(queryset, increment_by=1)[source]¶

Increment this field on every object in the provided queryset.

By default, this increments by 1, but a custom delta value can be provided.

Parameters:	queryset (django.db.models.query.QuerySet) – The queryset for the update. increment_by (int, optional) – The value to increment by. Defaults to 1.

decrement(queryset, decrement_by=1)[source]¶

Decrement this field on every object in the provided queryset.

By default, this increments by 1, but a custom delta value can be provided.

Parameters:	queryset (django.db.models.query.QuerySet) – The queryset for the update. decrement_by (int, optional) – The value to decrement by. Defaults to 1.

contribute_to_class(cls, name)[source]¶

Add methods to the model class.

This introduces the methods for incrementing, decrementing, reloading, and re-initializing the fields.

Parameters:	cls (type) – The model class. name (str) – The name of the field on the model.