Internals
You might be interested in the way things work on the inside of Auditlog. This section covers the internal APIs of Auditlog which is very useful when you are looking for more advanced ways to use the application or if you like to contribute to the project.
The documentation below is automatically generated from the source code.
Models and fields
- class auditlog.models.AuditlogHistoryField(pk_indexable=True, delete_related=False, **kwargs)[source]
A subclass of py:class:django.contrib.contenttypes.fields.GenericRelation that sets some default variables. This makes it easier to access Auditlog’s log entries, for example in templates.
By default, this field will assume that your primary keys are numeric, simply because this is the most common case. However, if you have a non-integer primary key, you can simply pass
pk_indexable=False
to the constructor, and Auditlog will fall back to using a non-indexed text based field for this model.Using this field will not automatically register the model for automatic logging. This is done so you can be more flexible with how you use this field.
- Parameters:
pk_indexable (bool) – Whether the primary key for this model is not an
int
orlong
.delete_related (bool) – Delete referenced auditlog entries together with the tracked object. Defaults to False to keep the integrity of the auditlog.
Return all objects related to
objs
via thisGenericRelation
.
- class auditlog.models.LogEntry(*args, **kwargs)[source]
Represents an entry in the audit log. The content type is saved along with the textual and numeric (if available) primary key, as well as the textual representation of the object when it was saved. It holds the action performed and the fields that were changed in the transaction.
If AuditlogMiddleware is used, the actor will be set automatically. Keep in mind that editing / re-saving LogEntry instances may set the actor to a wrong value - editing LogEntry instances is not recommended (and it should not be necessary).
- class Action[source]
The actions that Auditlog distinguishes: creating, updating and deleting objects. Viewing objects is not logged. The values of the actions are numeric, a higher integer value means a more intrusive action. This may be useful in some cases when comparing actions because the
__lt
,__lte
,__gt
,__gte
lookup filters can be used in queries.The valid actions are
Action.CREATE
,Action.UPDATE
,Action.DELETE
andAction.ACCESS
.
- exception DoesNotExist
- exception MultipleObjectsReturned
- property changes_dict
- Returns:
The changes recorded in this log entry as a dictionary object.
- property changes_display_dict
- Returns:
The changes recorded in this log entry intended for display to users as a dictionary object.
- property changes_str
Return the changes recorded in this log entry as a string. The formatting of the string can be customized by setting alternate values for colon, arrow and separator. If the formatting is still not satisfying, please use
LogEntry.changes_dict()
and format the string yourself.- Parameters:
colon – The string to place between the field name and the values.
arrow – The string to place between each old and new value.
separator – The string to place between each field.
- Returns:
A readable string of the changes in this log entry.
- class auditlog.models.LogEntryManager(*args, **kwargs)[source]
Custom manager for the
LogEntry
model.- get_for_model(model)[source]
Get log entries for all objects of a specified type.
- Parameters:
model (class) – The model to get log entries for.
- Returns:
QuerySet of log entries for the given model.
- Return type:
QuerySet
- get_for_object(instance)[source]
Get log entries for the specified model instance.
- Parameters:
instance (Model) – The model instance to get log entries for.
- Returns:
QuerySet of log entries for the given model instance.
- Return type:
QuerySet
- get_for_objects(queryset)[source]
Get log entries for the objects in the specified queryset.
- Parameters:
queryset (QuerySet) – The queryset to get the log entries for.
- Returns:
The LogEntry objects for the objects in the given queryset.
- Return type:
QuerySet
- log_create(instance, force_log: bool = False, **kwargs)[source]
Helper method to create a new log entry. This method automatically populates some fields when no explicit value is given.
- log_m2m_changes(changed_queryset, instance, operation, field_name, **kwargs)[source]
Create a new “changed” log entry from m2m record.
- Parameters:
changed_queryset (QuerySet) – The added or removed related objects.
instance (Model) – The model instance to log a change for.
operation – “add” or “delete”.
field_name (str) – The name of the changed m2m field.
kwargs – Field overrides for the
LogEntry
object.
- Returns:
The new log entry or None if there were no changes.
- Return type:
Middleware
Correlation ID
- auditlog.cid.get_cid() str | None [source]
Calls the cid getter function based on settings.AUDITLOG_CID_GETTER
If the setting value is:
None: then it calls the default getter (which retrieves the value set in set_cid)
callable: then it calls the function
type(str): then it imports the function and then call it
The result is then returned to the caller.
If your custom getter does not depend on set_header(), then we recommend setting settings.AUDITLOG_CID_GETTER to None.
- Returns:
The correlation ID
- auditlog.cid.set_cid(request: HttpRequest | None = None) None [source]
A function to read the cid from a request. If the header is not in the request, then we set it to None.
Note: we look for the value of AUDITLOG_CID_HEADER in request.headers and in request.META.
This function doesn’t do anything if the user is supplying their own AUDITLOG_CID_GETTER.
- Parameters:
request – The request to get the cid from.
- Returns:
None
Signal receivers
- auditlog.receivers.check_disable(signal_handler)[source]
Decorator that passes along disabled in kwargs if any of the following is true: - ‘auditlog_disabled’ from threadlocal is true - raw = True and AUDITLOG_DISABLE_ON_RAW_SAVE is True
- auditlog.receivers.log_access(sender, instance, **kwargs)[source]
Signal receiver that creates a log entry when a model instance is accessed in a AccessLogDetailView.
Direct use is discouraged, connect your model through
auditlog.registry.register()
instead.
- auditlog.receivers.log_create(sender, instance, created, **kwargs)[source]
Signal receiver that creates a log entry when a model instance is first saved to the database.
Direct use is discouraged, connect your model through
auditlog.registry.register()
instead.
- auditlog.receivers.log_delete(sender, instance, **kwargs)[source]
Signal receiver that creates a log entry when a model instance is deleted from the database.
Direct use is discouraged, connect your model through
auditlog.registry.register()
instead.
Custom Signals
Django Auditlog provides two custom signals that will hook in before
and after any Auditlog record is written from a create
, update
,
delete
, or accessed
action on an audited model.
- auditlog.signals.pre_log = <django.dispatch.dispatcher.Signal object>
Whenever an audit log entry is written, this signal is sent before writing the log. Keyword arguments sent with this signal:
- Parameters:
sender (class) – The model class that’s being audited.
instance (Any) – The actual instance that’s being audited.
action (Action) – The action on the model resulting in an audit log entry. Type:
auditlog.models.LogEntry.Action
The receivers’ return values are sent to any
post_log()
signal receivers, with one exception: if any receiver returns False, no logging will be made. This can be useful if logging should be conditionally enabled / disabled
- auditlog.signals.post_log = <django.dispatch.dispatcher.Signal object>
Whenever an audit log entry is written, this signal is sent after writing the log. This signal is also fired when there is an error in creating the log.
Keyword arguments sent with this signal:
- Parameters:
sender (class) – The model class that’s being audited.
instance (Any) – The actual instance that’s being audited.
action (Action) – The action on the model resulting in an audit log entry. Type:
auditlog.models.LogEntry.Action
changes (Optional[dict]) – The changes that were logged. If there was en error while determining the changes, this will be None. In some cases, such as when logging access to the instance, the changes will be an empty dict.
log_entry (Optional[LogEntry]) – The log entry that was created and stored in the database. If there was an error, this will be None.
log_created (bool) – Was the log actually created? This could be false if there was an error in creating the log.
error (Optional[Exception]) – The error, if one occurred while saving the audit log entry.
None
, otherwisepre_log_results (List[Tuple[method,Any]]) – List of tuple pairs
[(pre_log_receiver, pre_log_response)]
, wherepre_log_receiver
is the receiver method, andpre_log_response
is the corresponding response of that method. If there are nopre_log
receivers, then the list will be empty.pre_log_receiver
is guaranteed to be non-null, butpre_log_response
may beNone
. This depends on the correspondingpre_log_receiver
’s return value.
New in version 3.0.0.
Calculating changes
- auditlog.diff.get_field_value(obj, field)[source]
Gets the value of a given model instance field.
- Parameters:
obj (Model) – The model instance.
field (Any) – The field you want to find the value of.
- Returns:
The value of the field as a string.
- Return type:
str
- auditlog.diff.get_fields_in_model(instance)[source]
Returns the list of fields in the given model instance. Checks whether to use the official _meta API or use the raw data. This method excludes many to many fields.
- Parameters:
instance (Model) – The model instance to get the fields for
- Returns:
The list of fields for the given model (instance)
- Return type:
list
- auditlog.diff.mask_str(value: str) str [source]
Masks the first half of the input string to remove sensitive data.
- Parameters:
value (str) – The value to mask.
- Returns:
The masked version of the string.
- Return type:
str
- auditlog.diff.model_instance_diff(old: Model | None, new: Model | None, fields_to_check=None)[source]
Calculates the differences between two model instances. One of the instances may be
None
(i.e., a newly created model or deleted model). This will cause all fields with a value to have changed (fromNone
).- Parameters:
old (Model) – The old state of the model instance.
new (Model) – The new state of the model instance.
fields_to_check (Iterable) – An iterable of the field names to restrict the diff to, while ignoring the rest of the model’s fields. This is used to pass the update_fields kwarg from the model’s save method.
- Returns:
A dictionary with the names of the changed fields as keys and a two tuple of the old and new field values as value.
- Return type:
dict
- auditlog.diff.track_field(field)[source]
Returns whether the given field should be tracked by Auditlog.
Untracked fields are many-to-many relations and relations to the Auditlog LogEntry model.
- Parameters:
field (Field) – The field to check.
- Returns:
Whether the given field should be tracked.
- Return type:
bool
Registry
- class auditlog.registry.AuditlogModelRegistry(create: bool = True, update: bool = True, delete: bool = True, access: bool = True, m2m: bool = True, custom: Dict[ModelSignal, Callable] | None = None)[source]
A registry that keeps track of the models that use Auditlog to track changes.
- contains(model: ModelBase) bool [source]
Check if a model is registered with auditlog.
- Parameters:
model – The model to check.
- Returns:
Whether the model has been registered.
- Return type:
bool
- register(model: ModelBase = None, include_fields: List[str] | None = None, exclude_fields: List[str] | None = None, mapping_fields: Dict[str, str] | None = None, mask_fields: List[str] | None = None, m2m_fields: Collection[str] | None = None, serialize_data: bool = False, serialize_kwargs: Dict[str, Any] | None = None, serialize_auditlog_fields_only: bool = False)[source]
Register a model with auditlog. Auditlog will then track mutations on this model’s instances.
- Parameters:
model – The model to register.
include_fields – The fields to include. Implicitly excludes all other fields.
exclude_fields – The fields to exclude. Overrides the fields to include.
mapping_fields – Mapping from field names to strings in diff.
mask_fields – The fields to mask for sensitive info.
m2m_fields – The fields to handle as many to many.
serialize_data – Option to include a dictionary of the objects state in the auditlog.
serialize_kwargs – Optional kwargs to pass to Django serializer
serialize_auditlog_fields_only – Only fields being considered in changes will be serialized.