Jump to >


class ChangeDescription(*args, **kwargs)[source]

The recorded set of changes, with a description and the changed fields.

This is a general model that can be used in applications for recording changes how they see fit. A helper function, ‘record_field_changed’, can be used to record information in a standard way for most value types, but the ‘fields_changed’ dictionary can be manipulated however the caller chooses.

A ChangeDescription is not bound to a particular model. It is up to models to establish relationships with a ChangeDescription.

Each field in ‘fields_changed’ represents a changed field.

For string fields, the following fields will be available:

  • ‘old’: The old value of the field

  • ‘new’: The new value of the field

For list and set fields, the following fields will be available:

  • ‘removed’: The fields that were removed, if any.

  • ‘added’: The fields that were added, if any.


Return the user associated with the change description.

This function delegates to the model it is associated with (if provided) to determine the user if it has not been previously determined. Once the user has been determined, it will be saved to the database.


model (django.db.models.Model, optional) – The model instance this change description is associated with.


The user associated with the change description, or None if it could not be determined.

Return type


is_new_for_user(user, last_visited, model=None)[source]

Return whether this change description is new for a user.

The change description is considered new if their last visited time is older than the change description’s timestamp and the user is not the one who created the change description.

  • user (django.contrib.auth.models.User) – The user accessing the change description.

  • last_visited (datetime.datetime) – The last time the user accessed a page where the change description would be shown.

  • model (django.db.models.Model, optional) – The model instance this change description is associated with. This is needed for calculating a user, if one is not associated, and should generally be provided.


True if the change description is new to this user. False if it’s older than the last visited time or the user created it.

Return type


record_field_change(field, old_value, new_value, name_field=None)[source]

Record a field change.

This will encode field changes following the rules in the overlying ‘ChangeDescription’ documentation.

‘name_field’ can be specified for lists or other iterables. When specified, each list item will be a tuple in the form of (object_name, object_url, object_id). Otherwise, it will be a tuple in the form of (item,).

It is generally expected that fields with lists of model objects will have ‘name_field’ set, whereas lists of numbers or some other value type will not. Specifying a ‘name_field’ for non-objects will cause an AttributeError.


Determine if the ‘fields_changed’ variable is non-empty.

Uses the ‘fields_changed’ variable to determine if there are any current modifications being tracked to this ChangedDescription object.