Models

Recording Functions

record_changeset([**kwargs])

Return a context manager which records all changes made into a ChangeSet. If any keyword arguments are give, they are passed to ChangeSet when it is created as the context manager exits.

start_recording([**kwargs])

This, coupled with stop_recording, work the same as record_changeset. It is important to ensure that stop_recording is called (e.g. in a finally clause) or the changeset will never be created.

stop_recording()

See start_recording

scan(objects[, delete_only=False])

This must be called during recording (e.g. within record_changeset).

It scans a group of objects for changes after they have been made, and is ideal for situations where recorder cannot track the changes as they are made, or for populating initial data.

objects can be the name of a django app, a django Model, a Model instance, or an iterable of any of these. Deleted instances can be included and will be identified as such by their lack of primary key. If delete_only is True, then the objects will only be scanned for deleted objects. This is useful when, for example, bulk_delete has just been used.

Object wrapper

One of the fundamental concepts of this app is that the original models should always be an accurate representation of the current data state. The main implication of this is that deleted records should actually be deleted, so a query of MyModel.objects.all() doesn’t return an deleted or inaccurate data. However, it is useful to maintain a history of deleted records and historical foreign keys may refer to deleted records, so every reference to a record is wrapped in by the ObjectWrapper model.

class ObjectWrapper

A GenericForeignKey is used to reference the instance, so the usual caveats regarding these apply.

instance

Return the model instance being wrapped by this object. If it does not exist (because it has been deleted), then None is returned.

is_deleted()

Return True if the instance does not exist.

A custom manager provides a wrap method, to easily create new ObjectWrappers.

ObjectWrapperManager.wrap(instance)

Return an ObjectWrapper wrapping instance. This is functionally similar to get_or_create.

Field types

Individual changes to an instance are stored by field. To properly manage this, a FieldType model is used. It is similar in concept to ContentType, but operates at field level instead.

class FieldType

A FieldType is identified by the model (via a foreign key to ContentType) and the field_name. Additionally, for relation fields, the related model is automatically captured in rel_content_type.

model

Return the model containing the field.

field

Return the actual field object (e.g. a CharField instance).

is_fk()

Return True if the field is a foreign key.

is_m2m()

Return True if the field is a ManyToManyField.

clean_value(value)

Return a cleaned value using field.clean. If the value is invalid, ValidationError will be raise.

A custom manager is used to provide additional features.

class FieldTypeManager

for_field(model, field_name)

Get a FieldType for the specified model and field name. If the field does not exist on the model, FieldDoesNotExist is raised.

get_by_model(model[, related=True])

Filter all FieldTypes by model. If related is True, the fields on other models with a foreign or many-to-many key pointing to model will be included.

Changesets

class ChangeSet

user

The user who made the change. This is a User object from the django.contrib.auth framework.

comment

Optional comments related to the changeset. This is stored in a TextField.

Internals

CHANGE_STATE

(('+', 'add'), ('-', 'delete'))

The constant defines the choices for State.state and M2MChange.change_type.

class State

When a record is added or deleted, the change in state is recorded in this model.

changeset

Return the containing changeset

state

This indicates if the objects was added or deleted. This is a field defined with choices CHANGE_STATE, so django provides a way of getting the description via get_state_display().

wrapper

The ObjectWrapper wrapping the instance.

instance

This property is a shortcut to return state.wrapper.instance.

See also

ObjectWrapper.instance

class ValueChange

Individual changes are stored in this model.

changeset

Return the containing changeset

wrapper

The ObjectWrapper wrapping the instance.

instance

This property is a shortcut to return state.wrapper.instance.

See also

ObjectWrapper.instance

field

A FieldType instance referring to the field changed.

value

Todo

class M2MChange

This model inherits directly from ValueChange and adds a single field.

change_type

This indicates if the object referenced in value was added or deleted. This is a field defined with choices CHANGE_STATE, so django provides a way of getting the description via get_change_type_display().

Middleware

class ChangeSetMiddleware

Todo