API Reference

Action – A unit of change

class discipline.models.Action

An Action object represents a single unit of change (creation, modification, deletion) done by a single Editor at a specific point in time.

Action.editor

A ForeignKey for the Editor that performed this action.

Action.when

A DateTimeField representing the time when the action was performed.

Action.reverted
Action.reverts

A self-referencing OneToOneField. If Action A reverts Action B, A.reverts will equal B and B.reverted will equal A.

Action.creation_commits
Action.modification_commits
Action.deletion_commits

The CreationCommit, ModificationCommit, DeletionCommit objects, respectfully, associated with this action.

Action.timemachine

An instance of the TimeMachine object for the object on which this action was performed. The time is set automatically to the time of this action.

Action.object_uid

The UUID of the object that the action was performed on.

Action.action_type

Either "cr", "md" or "dl" for creation, modification and deletion, respectfully.

Action.is_revertible

A boolean representing whether it is possible to undo the action or not.

Action.undo_errors

If it is not possible to undo the action, this will be a list of strings, each the text of an error, explaining why it is not possible.

Action.summary

A plaintext summary of the action: includes the editor, the time, the type and each modified field (if modification or creation). Useful for debugging:

>>> print Action.objects.all()[0]
Time: 2010-07-04 00:11:53.520869
Comitter: John Doe
Modified musician
name: Robert Frip -> Robert Fripp
Action.get_absolute_url()

The URL to the Action object in the Django admin.

Editor

class discipline.models.Editor
Editor.user

A ForeignKey pointing to a django.contrib.auth.models.User. Every user that is going to work on Discipline-controlled models has to have an Editor instance.

Editor.save_object(obj)

Save a Django object obj and record everything necessary for Discipline. Use this in scripts, migrations and whenever you want to edit or create an instance of a Discipline-controlled model outside of the Django admin:

>>> obj = Concept()
>>> obj.save() # Do NOT do this, instead, do this:
>>> editor.save_object(obj)
Editor.delete_object(obj)

Similarly to save_object() above, use this instead of obj.delete() when interfacing with a Discipline-controlled model.

Editor.undo_action(act)

If act is revertible (see is_revertible()), undo the action.

For a deletion action, this will recreate the object just as it was before it was deleted (including its uid field!). For a creation action, it will delete the object. For a modification action, it will restore the object’s state as it was right before it was modified.

TimeMachine – Objects at different points in time

class discipline.models.TimeMachine(uid[, when=None[, step=None]])

Create a TimeMachine for the object with uid as the unique id. If step is given, initialize this TimeMachine right before the Action whose id matches step, if when (a datetime object) is given, initialize the TimeMachine at when, otherwise initialize in the present, after the last Action in the database.

TimeMachine.at(step)

Creates a new TimeMachine instance for the same object initialized right before the Action with the id step.

TimeMachine.presently

A shortcut using the above, the TimeMachine for the current object initialized after the last Action in the database.

TimeMachine.at_previous_action

A TimeMachine for the current object initialized at the Action before the current action of the TimeMachine.

TimeMachine.current_action

The action whose id field matches the step of this TimeMachine. Effectively, the action right “before” the time of the TimeMachine.

TimeMachine.exists

A boolean indicating whether the TimeMachine‘s object exits at the TimeMachine‘s point in time.

TimeMachine.get_object()

Returns the Django object at which the TimeMachine is looking. If it doesn’t exist, Django will raise an error.

TimeMachine.get(fieldname)

Returns the value of the field fieldname of the TimeMachine‘s object as it was at the time of this TimeMachine, if a related object doesn’t exist anymore, Django will raise an error.

TimeMachine.get_timemachine_instance(fieldname)

Returns a TimeMachine for the object pointed by the field fieldname. It will be initialized in the present.

SchemaState – Schema Migrations

class discipline.models.SchemaState

Discipline stores schema states initially and after every schema migration so that the TimeMachine can know what fields an object has at different points in time.

SchemaState.when

A DateTimeField indicating when the schema state was saved.

SchemaState.state

A TextField holding the json representation of the schema state. Do not use this.

SchemaState.get_for_content_type(ct)

Takes a django.contrib.contenttypes.models.ContentType object and returns a dict in the form of {"fields":["field1", "field2"], "foreignkeys":["fk1"]} where fields are all non-ForeignKey fields.

CreationCommit, ModificationCommit, DeletionCommit – At the lowest level

The essense of each change is stored in CreationCommit, ModificationCommit and DeletionCommit objects. Every creation action is composed of one CreationCommit and as many ModificationCommit objects as there are fields. Every modification action is composed of as many ModificationCommit objects as there are fields modified. Every deletion action is composed of a single DeletionCommit.

class discipline.models.CreationCommit

Records the creation of an object. Has three fields:

CreationCommit.content_type

A ForeignKey pointing at a django.contrib.contenttypes.models.ContentType object.

CreationCommit.object_uid

A UUIDField storing the new object’s unique id.

CreationCommit.action

A ForeignKey pointing at an Action to which this CreationCommit belongs.

class discipline.models.ModificationCommit

Records the modification of a single field of a single object. Has four fields:

CreationCommit.object_uid
CreationCommit.action

See above.

CreationCommit.key

A CharField storing the fieldname.

CreationCommit.value

A TextField storing the value of the field serialized by cPickle.

class discipline.models.DeletionCommit

Records the deletion of a single object. Has two fields:

CreationCommit.object_uid
CreationCommit.action

See above.