File: models.py

package info (click to toggle)
django-auditlog 3.4.1-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid
  • size: 744 kB
  • sloc: python: 5,794; makefile: 46; sh: 33
file content (647 lines) | stat: -rw-r--r-- 24,970 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
import ast
import contextlib
import json
from collections.abc import Callable
from copy import deepcopy
from datetime import timezone
from typing import Any

from dateutil import parser
from dateutil.tz import gettz
from django.conf import settings
from django.contrib.contenttypes.fields import GenericRelation
from django.contrib.contenttypes.models import ContentType
from django.core import serializers
from django.core.exceptions import (
    FieldDoesNotExist,
    ObjectDoesNotExist,
    ValidationError,
)
from django.db import DEFAULT_DB_ALIAS, models
from django.db.models import Q, QuerySet
from django.utils import formats
from django.utils import timezone as django_timezone
from django.utils.encoding import smart_str
from django.utils.translation import gettext_lazy as _

from auditlog import get_logentry_model
from auditlog.diff import get_mask_function

DEFAULT_OBJECT_REPR = "<error forming object repr>"


class LogEntryManager(models.Manager):
    """
    Custom manager for the :py:class:`LogEntry` model.
    """

    def log_create(self, instance, force_log: bool = False, **kwargs):
        """
        Helper method to create a new log entry. This method automatically populates some fields when no
        explicit value is given.

        :param instance: The model instance to log a change for.
        :type instance: Model
        :param force_log: Create a LogEntry even if no changes exist.
        :type force_log: bool
        :param kwargs: Field overrides for the :py:class:`LogEntry` object.
        :return: The new log entry or `None` if there were no changes.
        :rtype: LogEntry
        """
        from auditlog.cid import get_cid

        changes = kwargs.get("changes", None)
        pk = self._get_pk_value(instance)

        if changes is not None or force_log:
            kwargs.setdefault(
                "content_type", ContentType.objects.get_for_model(instance)
            )
            kwargs.setdefault("object_pk", pk)
            try:
                object_repr = smart_str(instance)
            except ObjectDoesNotExist:
                object_repr = DEFAULT_OBJECT_REPR
            kwargs.setdefault("object_repr", object_repr)
            kwargs.setdefault(
                "serialized_data", self._get_serialized_data_or_none(instance)
            )

            if isinstance(pk, int):
                kwargs.setdefault("object_id", pk)

            get_additional_data = getattr(instance, "get_additional_data", None)
            if callable(get_additional_data):
                kwargs.setdefault("additional_data", get_additional_data())

            # set correlation id
            kwargs.setdefault("cid", get_cid())
            return self.create(**kwargs)
        return None

    def log_m2m_changes(
        self, changed_queryset, instance, operation, field_name, **kwargs
    ):
        """Create a new "changed" log entry from m2m record.

        :param changed_queryset: The added or removed related objects.
        :type changed_queryset: QuerySet
        :param instance: The model instance to log a change for.
        :type instance: Model
        :param operation: "add" or "delete".
        :type action: str
        :param field_name: The name of the changed m2m field.
        :type field_name: str
        :param kwargs: Field overrides for the :py:class:`LogEntry` object.
        :return: The new log entry or `None` if there were no changes.
        :rtype: LogEntry
        """
        from auditlog.cid import get_cid

        pk = self._get_pk_value(instance)
        if changed_queryset:
            kwargs.setdefault(
                "content_type", ContentType.objects.get_for_model(instance)
            )
            kwargs.setdefault("object_pk", pk)
            try:
                object_repr = smart_str(instance)
            except ObjectDoesNotExist:
                object_repr = DEFAULT_OBJECT_REPR
            kwargs.setdefault("object_repr", object_repr)
            kwargs.setdefault("action", LogEntry.Action.UPDATE)

            if isinstance(pk, int):
                kwargs.setdefault("object_id", pk)

            get_additional_data = getattr(instance, "get_additional_data", None)
            if callable(get_additional_data):
                kwargs.setdefault("additional_data", get_additional_data())

            objects = [smart_str(instance) for instance in changed_queryset]
            kwargs["changes"] = {
                field_name: {
                    "type": "m2m",
                    "operation": operation,
                    "objects": objects,
                }
            }

            kwargs.setdefault("cid", get_cid())
            return self.create(**kwargs)

        return None

    def get_for_object(self, instance):
        """
        Get log entries for the specified model instance.

        :param instance: The model instance to get log entries for.
        :type instance: Model
        :return: QuerySet of log entries for the given model instance.
        :rtype: QuerySet
        """
        # Return empty queryset if the given model instance is not a model instance.
        if not isinstance(instance, models.Model):
            return self.none()

        content_type = ContentType.objects.get_for_model(instance.__class__)
        pk = self._get_pk_value(instance)

        if isinstance(pk, int):
            return self.filter(content_type=content_type, object_id=pk)
        else:
            return self.filter(content_type=content_type, object_pk=smart_str(pk))

    def get_for_objects(self, queryset):
        """
        Get log entries for the objects in the specified queryset.

        :param queryset: The queryset to get the log entries for.
        :type queryset: QuerySet
        :return: The LogEntry objects for the objects in the given queryset.
        :rtype: QuerySet
        """
        if not isinstance(queryset, QuerySet) or queryset.count() == 0:
            return self.none()

        content_type = ContentType.objects.get_for_model(queryset.model)
        primary_keys = list(
            queryset.values_list(queryset.model._meta.pk.name, flat=True)
        )

        if isinstance(primary_keys[0], int):
            return (
                self.filter(content_type=content_type)
                .filter(Q(object_id__in=primary_keys))
                .distinct()
            )
        elif isinstance(queryset.model._meta.pk, models.UUIDField):
            primary_keys = [smart_str(pk) for pk in primary_keys]
            return (
                self.filter(content_type=content_type)
                .filter(Q(object_pk__in=primary_keys))
                .distinct()
            )
        else:
            return (
                self.filter(content_type=content_type)
                .filter(Q(object_pk__in=primary_keys))
                .distinct()
            )

    def get_for_model(self, model):
        """
        Get log entries for all objects of a specified type.

        :param model: The model to get log entries for.
        :type model: class
        :return: QuerySet of log entries for the given model.
        :rtype: QuerySet
        """
        # Return empty queryset if the given object is not valid.
        if not issubclass(model, models.Model):
            return self.none()

        content_type = ContentType.objects.get_for_model(model)

        return self.filter(content_type=content_type)

    def _get_pk_value(self, instance):
        """
        Get the primary key field value for a model instance.

        :param instance: The model instance to get the primary key for.
        :type instance: Model
        :return: The primary key value of the given model instance.
        """
        # Should be equivalent to `instance.pk`.
        pk_field = instance._meta.pk.attname
        pk = getattr(instance, pk_field, None)

        # Check to make sure that we got a pk not a model object.
        # Should be guaranteed as we used `attname` above, not `name`.
        assert not isinstance(pk, models.Model)
        return pk

    def _get_serialized_data_or_none(self, instance):
        from auditlog.registry import auditlog

        if not auditlog.contains(instance.__class__):
            return None

        opts = auditlog.get_serialize_options(instance.__class__)
        if not opts["serialize_data"]:
            return None

        model_fields = auditlog.get_model_fields(instance.__class__)
        kwargs = opts.get("serialize_kwargs", {})

        if opts["serialize_auditlog_fields_only"]:
            kwargs.setdefault(
                "fields", self._get_applicable_model_fields(instance, model_fields)
            )

        instance_copy = self._get_copy_with_python_typed_fields(instance)
        data = dict(
            json.loads(serializers.serialize("json", (instance_copy,), **kwargs))[0]
        )

        mask_fields = model_fields["mask_fields"]
        if mask_fields:
            data = self._mask_serialized_fields(data, mask_fields, model_fields)

        return data

    def _get_copy_with_python_typed_fields(self, instance):
        """
        Attempt to create copy of instance and coerce types on instance fields

        The Django core serializer assumes that the values on object fields are
        correctly typed to their respective fields. Updates made to an object's
        in-memory state may not meet this assumption. To prevent this violation, values
        are typed by calling `to_python` from the field object, the result is set on a
        copy of the instance and the copy is sent to the serializer.
        """
        try:
            instance_copy = deepcopy(instance)
        except TypeError:
            instance_copy = instance
        for field in instance_copy._meta.fields:
            if not field.is_relation:
                value = getattr(instance_copy, field.name)
                try:
                    setattr(instance_copy, field.name, field.to_python(value))
                except ValidationError:
                    continue
        return instance_copy

    def _get_applicable_model_fields(
        self, instance, model_fields: dict[str, list[str]]
    ) -> list[str]:
        include_fields = model_fields["include_fields"]
        exclude_fields = model_fields["exclude_fields"]
        all_field_names = [field.name for field in instance._meta.fields]

        if not include_fields and not exclude_fields:
            return all_field_names

        return list(set(include_fields or all_field_names).difference(exclude_fields))

    def _mask_serialized_fields(
        self, data: dict[str, Any], mask_fields: list[str], model_fields: dict[str, Any]
    ) -> dict[str, Any]:
        all_field_data = data.pop("fields")
        mask_func = get_mask_function(model_fields.get("mask_callable"))

        masked_field_data = {}
        for key, value in all_field_data.items():
            if isinstance(value, str) and key in mask_fields:
                masked_field_data[key] = mask_func(value)
            else:
                masked_field_data[key] = value

        data["fields"] = masked_field_data
        return data


class AbstractLogEntry(models.Model):
    """
    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:
        """
        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 :py:attr:`Action.CREATE`, :py:attr:`Action.UPDATE`,
        :py:attr:`Action.DELETE` and :py:attr:`Action.ACCESS`.
        """

        CREATE = 0
        UPDATE = 1
        DELETE = 2
        ACCESS = 3

        choices = (
            (CREATE, _("create")),
            (UPDATE, _("update")),
            (DELETE, _("delete")),
            (ACCESS, _("access")),
        )

    content_type = models.ForeignKey(
        to="contenttypes.ContentType",
        on_delete=models.CASCADE,
        related_name="+",
        verbose_name=_("content type"),
    )
    object_pk = models.CharField(
        db_index=True, max_length=255, verbose_name=_("object pk")
    )
    object_id = models.BigIntegerField(
        blank=True, db_index=True, null=True, verbose_name=_("object id")
    )
    object_repr = models.TextField(verbose_name=_("object representation"))
    serialized_data = models.JSONField(null=True)
    action = models.PositiveSmallIntegerField(
        choices=Action.choices, verbose_name=_("action"), db_index=True
    )
    changes_text = models.TextField(blank=True, verbose_name=_("change message"))
    changes = models.JSONField(null=True, verbose_name=_("change message"))
    actor = models.ForeignKey(
        to=settings.AUTH_USER_MODEL,
        on_delete=models.SET_NULL,
        blank=True,
        null=True,
        related_name="+",
        verbose_name=_("actor"),
    )
    cid = models.CharField(
        max_length=255,
        db_index=True,
        blank=True,
        null=True,
        verbose_name=_("Correlation ID"),
    )
    remote_addr = models.GenericIPAddressField(
        blank=True, null=True, verbose_name=_("remote address")
    )
    remote_port = models.PositiveIntegerField(
        blank=True, null=True, verbose_name=_("remote port")
    )
    timestamp = models.DateTimeField(
        default=django_timezone.now,
        db_index=True,
        verbose_name=_("timestamp"),
    )
    additional_data = models.JSONField(
        blank=True, null=True, verbose_name=_("additional data")
    )
    actor_email = models.CharField(
        blank=True, null=True, max_length=254, verbose_name=_("actor email")
    )

    objects = LogEntryManager()

    class Meta:
        abstract = True
        get_latest_by = "timestamp"
        ordering = ["-timestamp"]
        verbose_name = _("log entry")
        verbose_name_plural = _("log entries")

    def __str__(self):
        if self.action == self.Action.CREATE:
            fstring = _("Created {repr:s}")
        elif self.action == self.Action.UPDATE:
            fstring = _("Updated {repr:s}")
        elif self.action == self.Action.DELETE:
            fstring = _("Deleted {repr:s}")
        else:
            fstring = _("Logged {repr:s}")

        return fstring.format(repr=self.object_repr)

    @property
    def changes_dict(self):
        """
        :return: The changes recorded in this log entry as a dictionary object.
        """
        return changes_func(self)

    @property
    def changes_str(self, colon=": ", arrow=" \u2192 ", separator="; "):
        """
        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 :py:func:`LogEntry.changes_dict` and format the string yourself.

        :param colon: The string to place between the field name and the values.
        :param arrow: The string to place between each old and new value.
        :param separator: The string to place between each field.
        :return: A readable string of the changes in this log entry.
        """
        substrings = []

        for field, values in self.changes_dict.items():
            substring = "{field_name:s}{colon:s}{old:s}{arrow:s}{new:s}".format(
                field_name=field,
                colon=colon,
                old=values[0],
                arrow=arrow,
                new=values[1],
            )
            substrings.append(substring)

        return separator.join(substrings)

    @property
    def changes_display_dict(self):
        """
        :return: The changes recorded in this log entry intended for display to users as a dictionary object.
        """
        from auditlog.registry import auditlog

        # Get the model and model_fields, but gracefully handle the case where the model no longer exists
        model = self.content_type.model_class()
        model_fields = None
        if auditlog.contains(model._meta.model):
            model_fields = auditlog.get_model_fields(model._meta.model)

        if settings.AUDITLOG_STORE_JSON_CHANGES:
            changes_dict = {}
            for field_name, values in self.changes_dict.items():
                values_as_strings = [str(v) for v in values]
                changes_dict[field_name] = values_as_strings
        else:
            changes_dict = self.changes_dict

        changes_display_dict = {}
        # grab the changes_dict and iterate through
        for field_name, values in changes_dict.items():
            # try to get the field attribute on the model
            try:
                field = model._meta.get_field(field_name)
            except FieldDoesNotExist:
                changes_display_dict[field_name] = values
                continue
            values_display = []
            # handle choices fields and Postgres ArrayField to get human-readable version
            choices_dict = None
            if getattr(field, "choices", []):
                choices_dict = dict(field.choices)
            if getattr(getattr(field, "base_field", None), "choices", []):
                choices_dict = dict(field.base_field.choices)

            if choices_dict:
                for value in values:
                    try:
                        value = ast.literal_eval(value)
                        if type(value) is [].__class__:
                            values_display.append(
                                ", ".join(
                                    [choices_dict.get(val, "None") for val in value]
                                )
                            )
                        else:
                            values_display.append(choices_dict.get(value, "None"))
                    except Exception:
                        values_display.append(choices_dict.get(value, "None"))
            else:
                try:
                    field_type = field.get_internal_type()
                except AttributeError:
                    # if the field is a relationship it has no internal type and exclude it
                    continue
                for value in values:
                    # handle case where field is a datetime, date, or time type
                    if field_type in ["DateTimeField", "DateField", "TimeField"]:
                        try:
                            value = parser.parse(value)
                            if field_type == "DateField":
                                value = value.date()
                            elif field_type == "TimeField":
                                value = value.time()
                            elif field_type == "DateTimeField":
                                value = value.replace(tzinfo=timezone.utc)
                                value = value.astimezone(gettz(settings.TIME_ZONE))
                            value = formats.localize(value)
                        except ValueError:
                            pass
                    elif field_type in ["ForeignKey", "OneToOneField"]:
                        value = self._get_changes_display_for_fk_field(field, value)

                    truncate_at = settings.AUDITLOG_CHANGE_DISPLAY_TRUNCATE_LENGTH
                    if 0 <= truncate_at < len(value):
                        value = value[:truncate_at] + ("..." if truncate_at > 0 else "")

                    values_display.append(value)

            # Use verbose_name from mapping if available, otherwise determine from field
            if model_fields and field.name in model_fields["mapping_fields"]:
                verbose_name = model_fields["mapping_fields"][field.name]
            else:
                verbose_name = getattr(field, "verbose_name", field.name)

            changes_display_dict[verbose_name] = values_display
        return changes_display_dict

    def _get_changes_display_for_fk_field(
        self, field: models.ForeignKey | models.OneToOneField, value: Any
    ) -> str:
        """
        :return: A string representing a given FK value and the field to which it belongs
        """
        # Return "None" if the FK value is "None".
        if value == "None":
            return value

        # Attempt to convert given value to the PK type for the related model
        try:
            pk_value = field.related_model._meta.pk.to_python(value)
        # ValidationError will handle legacy values where string representations were
        # stored rather than PKs. This will also handle cases where the PK type is
        # changed between the time the LogEntry is created and this method is called.
        except ValidationError:
            return value
        # Attempt to return the string representation of the object
        try:
            related_model_manager = _get_manager_from_settings(field.related_model)

            return smart_str(related_model_manager.get(pk=pk_value))
        # ObjectDoesNotExist will be raised if the object was deleted.
        except ObjectDoesNotExist:
            return f"Deleted '{field.related_model.__name__}' ({value})"


class LogEntry(AbstractLogEntry):
    class Meta(AbstractLogEntry.Meta):
        swappable = "AUDITLOG_LOGENTRY_MODEL"


class AuditlogHistoryField(GenericRelation):
    """
    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.

    :param pk_indexable: Whether the primary key for this model is not an :py:class:`int` or :py:class:`long`.
    :type pk_indexable: bool
    :param delete_related: Delete referenced auditlog entries together with the tracked object.
        Defaults to False to keep the integrity of the auditlog.
    :type delete_related: bool
    """

    def __init__(self, pk_indexable=True, delete_related=False, **kwargs):
        kwargs["to"] = get_logentry_model()

        if pk_indexable:
            kwargs["object_id_field"] = "object_id"
        else:
            kwargs["object_id_field"] = "object_pk"

        kwargs["content_type_field"] = "content_type"
        self.delete_related = delete_related
        super().__init__(**kwargs)

    def bulk_related_objects(self, objs, using=DEFAULT_DB_ALIAS):
        """
        Return all objects related to ``objs`` via this ``GenericRelation``.
        """
        if self.delete_related:
            return super().bulk_related_objects(objs, using)

        # When deleting, Collector.collect() finds related objects using this
        # method.  However, because we don't want to delete these related
        # objects, we simply return an empty list.
        return []


# should I add a signal receiver for setting_changed?
changes_func = None


def _changes_func() -> Callable[[LogEntry], dict]:
    def json_then_text(instance: LogEntry) -> dict:
        if instance.changes:
            return instance.changes
        elif instance.changes_text:
            with contextlib.suppress(ValueError):
                return json.loads(instance.changes_text)
        return {}

    def default(instance: LogEntry) -> dict:
        return instance.changes or {}

    if settings.AUDITLOG_USE_TEXT_CHANGES_IF_JSON_IS_NOT_PRESENT:
        return json_then_text
    return default


def _get_manager_from_settings(model: type[models.Model]) -> models.Manager:
    """
    Get model manager as selected by AUDITLOG_USE_BASE_MANAGER.

    - True: return model._meta.base_manager
    - False: return model._meta.default_manager
    """
    if settings.AUDITLOG_USE_BASE_MANAGER:
        return model._meta.base_manager
    else:
        return model._meta.default_manager