The history package provides simple version control-like facilities for Avocado's query structures: DataContext, DataView, and DataQuery. Each change that is made to an object produces a revision. This history of changes acts effectively as a persistent undo stack.

The API is kept simple to intentionally prevent being a full blown Version Control System (VCS) for the data. Changes can be committed which produce a revision. Thats it. Each revision contains the full structure, not just the diff (although the diff can be generated). Previous revisions can be reapplied, which itself produces a new revision. There is no going back to a revision, only reapplying a previous revision.


  • HISTORY_ENABLED - Enable default history tracking and behavior of Avocado query structures. This includes DataContext, DataView and DataQuery instances. Default is True.
  • HISTORY_MAX_SIZE - Maximum history size for a given instance. If an integer is specified, entries beyond the cutoff will be culled when avocado history --cull command is executed. Default is None.

If HISTORY_MAX_SIZE is defined, it is recommended to setup a cronjob that executes the avoacdo history --cull command.


Models can be registered which connect them to post-save and pre-delete signal receivers.

from avocado import history

# If fields is not defined, all local, editable, non-relational fields are
# included. Excluded fields take precedence over included fields.
history.register(MyModel, fields=(...), exclude=(...))

This will create a revision whenever an instance of MyModel is saved and has changed from the previous revision.

For manual revisioning, the Revision manager can be used.

from avocado.history import Revision

Revision.objects.create_revision(obj, fields=(...))