Hopiu/django-auditlog
1
0
Fork 0
mirror of https://github.com/jazzband/django-auditlog.git synced 2026-05-04 13:44:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Extend docs with many-to-many, manual logging

Browse source
This commit is contained in:
Jan-Jelle Kester 2015-07-22 01:16:58 +02:00
parent dab0342cf6
commit cfd6b35d6c
2 changed files with 40 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/source/installation.rst
View file

@ -20,7 +20,7 @@ https://travis-ci.org/jjkester/django-auditlog.
Adding Auditlog to your Django application
------------------------------------------
To use Auditlog in your application, just add ``'auditlog'`` to your project's ``INSTALLED_APPS`` setting and run either
To use Auditlog in your application, just add ``'auditlog'`` to your project's ``INSTALLED_APPS`` setting and run
``manage.py migrate`` to create/upgrade the necessary database structure.
If you want Auditlog to automatically set the actor for log entries you also need to enable the middleware by adding

43
docs/source/usage.rst
View file

@ -1,6 +1,16 @@
Usage
=====
.. py:currentmodule:: auditlog.models
Manually logging changes
------------------------
Auditlog log entries are simple :py:class:`LogEntry` model instances. This makes creating a new log entry very easy. For
even more convenience, :py:class:`LogEntryManager` provides a number of methods which take some work out of your hands.
See :doc:`internals` for all details.
Automatically logging changes
-----------------------------
@ -67,11 +77,9 @@ It is recommended to keep all middleware that alters the request loaded before A
Object history
--------------
.. py:currentmodule:: auditlog.models
Auditlog ships with a custom field that enables you to easily get the log entries that are relevant to your object. This
functionality is built on Django's content types framework (``django.contrib.contenttypes``). Using this field in your
models is equally easy as any other field::
functionality is built on Django's content types framework (:py:mod:`django.contrib.contenttypes`). Using this field in
your models is equally easy as any other field::
from auditlog.models import AuditlogHistoryField
from auditlog.registry import auditlog
@ -86,3 +94,30 @@ models is equally easy as any other field::
:py:class:`AuditlogHistoryField` accepts an optional :py:attr:`pk_indexable` parameter, which is either ``True`` or
``False``, this defaults to ``True``. If your model has a custom primary key that is not an integer value,
:py:attr:`pk_indexable` needs to be set to ``False``. Keep in mind that this might slow down queries.
Many-to-many relationships
--------------------------
.. versionadded:: 0.3.0
.. warning::
To-many relations are not officially supported. However, this section shows a workaround which can be used for now.
In the future, this workaround may be used in an official API or a completly different strategy might be chosen.
**Do not rely on the workaround here to be stable across releases.**
By default, many-to-many relationships are not tracked by Auditlog.
The history for a many-to-many relationship without an explicit 'through' model can be recorded by registering this
model as follows::
auditlog.register(MyModel.related.through)
The log entries for all instances of the 'through' model that are related to a ``MyModel`` instance can be retrieved
with the :py:meth:`LogEntryManager.get_for_objects` method. The resulting QuerySet can be combined with any other
queryset of :py:class:`LogEntry` instances. This way it is possible to get a list of all changes on an object and its
related objects::
obj = MyModel.objects.first()
rel_history = LogEntry.objects.get_for_objects(obj.related.all())
full_history = (obj.history.all() | rel_history.all()).order_by('-timestamp')