API

analog.define_log_model(model_class, base_class=<class 'analog.models.BaseLogEntry'>, on_delete=<function CASCADE>)

Define a log model for a given Django model class (“parent model”).

The log entry model class is returned, and it must be assigned to a variable in a models.py file to allow Django to pick it up for migrations.

For all intents and purposes, the log entry model is owned by your app after this function creates it.

The parent model is anointed with two new attributes:

  • add_log_entry, a function to add a log entry. (See BaseLogEntry.add_log_entry() for details, but heed the fact that the target argument will be implicitly passed.)
  • log_model, a reference to the log entry model.
Parameters:
  • model_class – The model class this log entry model is for.
  • base_class – Replacement base class for the model. Should be compatible with BaseLogEntry never- theless.
  • on_delete – The on_delete clause for the log entry class’s foreign key. Defaults to CASCADE, i.e. that log entries are deleted when the logged model instance is. PROTECT would be another sane option.
Returns:

The log entry model.
class analog.BaseLogEntry(*args, **kwargs)

Abstract base model class for the various log models.

The concrete models are created by define_log_model().

classmethod add_log_entry(target, message, identifier=None, kind=u'other', user=None, extra=None, save=True)

Add a log entry.

Note

This method should not be used directly; instead, the same method, aside from the target argument, is available on models that have been anointed by define_log_model().

Parameters:
  • target – Target model instance
  • message (str) – Log message
  • identifier (str|None) – Log message identifier. Useful for tagging log entries in a way that is not necessarily human-readable.
  • kind (int|str) – Log entry kind. Either a mnemonic string (preferred and readable), or the actual entry ID integer (if you really have to). Kinds are configured in your project’s settings.
  • user – An optional user object (an instance of settings.AUTH_USER_MODEL) to attach to this log entry.
  • extra (object|None) – Extra data, if applicable. If set, this must be serializable to JSON; ``dict``s are a good idea.
  • save (bool) – Whether to immediately save the log entry. Default True.
Returns:

The created log entry
get_kind_display()

Get the kind label for this log entry.

This emulates the behavior Django would have for fields that have the choices kwarg.