django-atris 2.0.3

集成指南

为了使用应用程序，您必须执行以下操作

• 将“atris”添加到settings中的INSTALLED_APPS

• 您必须将 'django.contrib.postgres' 添加到您的 INSTALLED_APPS 中

• 为了使应用能够获取更改的用户，请将 'atris.middleware.LoggingRequestMiddleware' 添加到 MIDDLEWARE 中

• 在您想要跟踪历史记录的模型类中添加一个字段（您可以根据需要命名），该字段包含一个 HistoryLogging 实例（例如：history = HistoryLogging()）

其他功能

• 其他数据 -

  如果您希望存储有关模型实例的一些其他数据，可以通过在模型中添加一个包含这些数据的字典来实现。创建该字典后，在实例化 HistoryLogging 字段时使用它

  additional_data = {'changed_from': 'djadmin'}
  history = HistoryLogging(additional_data_param_name='additional_data')

• 排除字段 -

  如果您不希望跟踪某些字段，只需在模型中添加一个包含您不希望跟踪的字段列表的列表，并在实例化 HistoryLogging 字段时使用该列表即可

  exclude_fields = ['last_modified'] # as it would always appear to have been updated
  history = HistoryLogging(excluded_fields_param_name='exclude_fields')

• 忽略特定用户更改 -

  如果您不希望跟踪特定用户所做的更改，例如专门为烟雾测试设置的特定用户，您可以声明一个名为您喜欢的额外字段，并将其传递给 HistoryLogging 对象。该字段必须是一个包含 'user_ids' 和 'user_names' 键的字典，这两个键的值都必须是包含适当信息的列表

  ignore_history_for_users = {'user_ids': [1010101], 'user_names': ['ignore_user']}
  history = HistoryLogging(ignore_history_for_users='ignore_history_for_users')

• 相关字段 -

  （自版本 1.1.0 以来添加）

  如果您希望在模型更改时为与模型相关的对象添加历史记录，可以通过声明一个包含相关字段名称的列表来实现。这适用于 1-to-1、1-to-many 和 many-to-many 字段

  poll = ForeignKey('Poll')
  ...
  interested_related_fields = ['poll']
  history = HistoryLogging(interested_related_fields='interested_related_fields')

使用指南

将应用集成到您自己的应用后，您可以通过多种方式使用它。

首先，当检查历史实例时，您将获得以下可用字段

• content_type = django contenttype

• object_id = 保存历史记录的模型实例 ID

• history_date = 创建历史实例的日期

• history_user = 触发历史实例的用户（来自中间件）；对于此字符串，其值按以下顺序优先：全名 > 电子邮件 > 用户名，如果都不可用，则保持为 None。

• history_user_id = 触发历史实例的用户 ID（来自中间件）

• history_type = 历史类型，+：创建，~：更新，-：删除（'get_history_type_display()' 方法为您提供字符串表示形式）

• data = JSON 字段，包含一个快照（以字典形式），其中包含正在保存历史记录的模型实例，不包含排除的字段或附加数据字段。所有字段值都转换为字符串。外键的值以字符串形式表示对象 ID。ManyToManyFields 的值以包含逗号分隔的 ID 列表的字符串表示

  新功能 1.1.0：将 ForeignKey 字段的键从 <FK_FIELD_NAME>_id 更改为 <FK_FIELD_NAME>；添加 many-to-many 字段的条目

• additional_data = JSON 字段，包含模型实例的附加数据，形式为字典

注意 #1：只有当本地模型字段发生更改时，才会生成历史记录。（自版本 1.1.0 以来新增）

注意 #2：您可以实现自己的 HistoricalRecord 类，并通过在项目的 settings.py 中通过 ATRIS_HISTORY_MODEL 指定来使用它，格式为 <APP_NAME>.<MODEL_NAME>。（自版本 1.1.0 以来新增）

代码示例中的使用方法

• 我们将使用示例中的类

  >>> class Foo(models.Model):
  ...   field_1 = models.CharField(max_length=255)
  ...   field_2 = models.IntField()
  ...   last_modified = models.DateTimeField(auto_now=True)
  ...   excluded_fields = ['last_modified']
  ...   ignore_history_for_users = {
  ...       'user_ids': [1010101],
  ...       'user_names': ['ignore_user'],
  ...   }
  ...   history = HistoryLogging(
  ...       excluded_fields='excluded_fields',
  ...       ignore_history_for_users='ignore_history_for_users,
  ...   )
  
  >>> class Bar(models.Model):
  ...   field_1 = models.CharField(max_length=255)
  ...   field_2 = models.IntField()
  ...   last_modified = models.DateTimeField(auto_now=True)
  ...   fk_field = models.ForeignKey(Foo)
        # setting this specifies the default value for your additional data
  ...   additional_data = {'modified_from': 'code'}
  ...   excluded_fields = ['last_modified']
  ...   interested_related_fields = ['fk_field']
  ...   history = HistoryLogging(
  ...       'additional_data',
  ...       'excluded_fields',
  ...       interested_related_fields='interested_related_fields',
  ...   )
  
  >>> foo = Foo.objects.create(field_1='aaa', field_2=0)
  >>> foo_1 = Foo.objects.create(field_1='bar', field_2=1)

• 获取刚创建的第一个模型实例的所有历史信息

  >>> foo.history.all()
  [<HistoricalRecord: Create foo id=1>]

• 获取 Foo 模型的所有历史信息

  >>> Foo.history.all()
  [<HistoricalRecord: Create foo id=1>, <HistoricalRecord: Create foo id=2>]

• 获取全局历史信息（按 history_date 降序排序）

  >>> from atris.models import HistoricalRecord
  >>> HistoricalRecord.objects.all()
  [<HistoricalRecord: Create bar id=1>, <HistoricalRecord: Create foo id=2>]

• 获取 Bar 模型的所有历史信息

  Bar.objects.create(field_1='aaa', field_2=0, fk_field=foo)
  >>> Bar.history.all()
  [<HistoricalRecord: Create bar id=1>]

• 再次获取全局历史信息

  >>> HistoricalRecord.objects.all()
  [<HistoricalRecord: Update foo id=1>, <HistoricalRecord: Create bar id=1>,
    <HistoricalRecord: Create foo id=2>, <HistoricalRecord: Create foo id=1>]

  请注意，当将 bar 对象链接到 foo 时，已为 foo 创建了一个“更新”历史记录。

• 获取模型历史记录的另一种方法

  >>> HistoricalRecord.objects.by_model(Foo)
  [<HistoricalRecord: Update foo id=1>, <HistoricalRecord: Create foo id=1>,
   <HistoricalRecord: Create foo id=2>]

• 获取模型实例历史记录的另一种方法，适用于您想要历史记录但已删除的对象

  >>> HistoricalRecord.objects.by_model_and_model_id(Foo, foo.id)
  [<HistoricalRecord: Update foo id=1>, <HistoricalRecord: Create foo id=1>]

• 获取创建的条形实例快照

  >>> bar.history.first().data
  {'field_1': 'aaa', 'field_2': '0', 'fk_field': '1'}

• 获取条形实例的附加数据

  >>> bar.history.first().additional_data
  {'modified_from': 'code'}

• 如果您遇到无法从django中间件确定用户的情况，您还可以执行以下操作

  >>> bar.history_user = User(username='username') # where User is the django User model
  >>> # Some other changes to bar so that a historical record will be generated.
  >>> bar.save()
  >>> bar.history.first().history_user
  'username'

• 您还可以标记用户，以便不保存该用户的历史记录。您可以按用户名（请注意：用户名被认为是全名、电子邮件或与历史记录关联的用户实例的用户名，取决于哪个最先可用，按此顺序）或ID进行操作。您可以使用此功能告诉atris忽略某些用户（例如烟雾测试用户）所做的更改

  >>> bar.history_user = User(username='ignore_user') # where User is the django User model
  >>> bar.save()
  >>> bar.history.filter(history_user='ignore_user').count()
  0

变更日志

1.2.2:

• Django 1.10 兼容

1.3.0:

• Django 2 兼容

1.3.1:

• 抑制近似计数。待办事项

1.3.2:

• Django 2.1 兼容

1.3.3:

• 评估字段详细名称的延迟翻译文本

1.3.4:

• 添加对Django 2.2的支持

2.0.0:

• 移除对Django < 2.2和Python < 3.6的支持

• 修复了在添加新字段后第一次保存实例后生成历史记录的问题

  • 此问题导致在保存（没有任何更改）现有受跟踪模型的实例时生成历史记录

2.0.1:

• 移除对Python < 3.7的支持

• 添加了对Django 3.2的支持

• 从setup.py迁移到pyproject.toml

2.0.2:

• 移除对Django 2的支持

• 添加了对Django 4的支持（已测试至4.2.6）

• 移除对python < 3.8的支持

2.0.3:

• 移除对Django 3的支持

• 支持范围从4.2.6扩展到Django 5以下（已测试至4.2.7）