django-utils

收集了我们基于Django的Web应用中使用的实用工具

变更日志

开发

安装依赖项，假设你已经安装了poetry

poetry install

发布

此包使用towncrier来管理变更日志，并且要引入新更改，应在changes目录中创建一个具有简洁标题和简要说明更改完成情况的文件，以指示更改是功能、错误修复或其他。

要发布并发布到PyPI，可以执行以下命令

./bin/release

此脚本利用zest.releaser和towncrier创建发布、构建wheel并将其发布到PyPI。

在运行发布命令之前，需要通过执行以下命令并插入存储在1password中的令牌来使用PyPI访问令牌配置poetry

poetry config pypi-token.pypi <token>

设置

LogMixin

包含具有适合生产环境的默认值的日志配置的mixin。

可用环境变量

• LOGGING_LEVEL (默认: "WARNING")
• LOGGING_HANDLERS (默认: ["stream"])
• LOGGING_FILENAME (默认: <settings.BASE_DIR>/log/django.log)

用法

# myproject/settings/production.py

from django_utils.settings.logging import LogMixin

from myproject.settings.base import Base

class Production(LogMixin, Base):
    pass

SentryMixin

用于向Sentry报告错误的mixin。

可用环境变量

• SENTRY_DSN (必需)
• SENTRY_ENVIRONMENT (默认: "Production")
• SENTRY_CACERTS (默认: None)
• SENTRY_TAGS (默认: {})

用法

# myproject/settings/production.py

from django_utils.settings.sentry import SentryMixin

from myproject.settings.base import Base

class Production(SentryMixin, Base):
    pass

管理命令

ℹ️ 为了使用管理命令，您需要将 django_utils 添加到 INSTALLED_APPS 设置。

sentry_test

使用此命令测试与Sentry的连接。该命令故意引发异常。这应该在Sentry中报告。

用法

python manage.py sentry_test

模型字段

TextField

一个没有max_length的TextField，在Django管理界面中将其表单元素显示为单行'CharField'，具有扩展宽度。

用法

# models.py

from django.db import models
from django_utils.db.fields import TextField


class MyModel(models.Model):
    TextField(verbose_name="My TextField")

测试

视图

此包提供可用的视图，可用于端到端测试的测试设置和清理，以及登录或创建测试数据。

ℹ️ 这些视图依赖于管理命令的可执行性，如 python manage.py load_e2e_data --datasets initial，以加载测试的初始数据集。

⚠️ 重要：切勿在生产模式下添加这些视图（通过 django_utils.testing.urls）！它们仅应用于测试目的。

用法

# myproject/settings/testing.py

from django_utils.settings.logging import LogMixin

from myproject.settings.base import Base

class TestingE2E(LogMixin, Base):
    LOGGING_LEVEL = "INFO"
    LOGGING_HANDLERS = ["file"]

    @property
    def LOGGING_FILENAME(self):
        return super().BASE_DIR / "log" / "e2e.log"


# myproject/urls.py

from django.conf import settings
from django.urls import include
from django.urls import path

urlpatterns = [
    # ...
]

if settings.CONFIGURATION == "settings.TestingE2E":
    urlpatterns += [
        path("e2e/", include("django_utils.testing.urls")),
    ]

E2ETestSetupView (/setup)

创建媒体根文件夹的快照，重置数据库，恢复权限并加载初始数据（调用 python manage.py load_e2e_data --datasets initial）。

E2ETestTearDownView (/teardown)

清理媒体根文件夹。

TestingLoginView (/login)

在提交JSON请求体（例如 {"username": "username", "password": "password"}）时验证用户。

E2ETestLoadDataView (/load_data)

在提交JSON请求体（例如 {"datasets": ["initial"]}）时，使用 python manage.py load_e2e_data --datasets [datasets] 加载指定的数据集。

PingView (/ping)

以状态代码200响应HTTP响应。

受保护文件视图

Django Utils 提供了一种保护您的文件免受匿名访问的方法。

需求

文件视图依赖于 django-sendfile2 和 djangorestframework。

pip install django-sendfile2
pip install djangorestframework

视图

Django Utils 在 django_utils.views.FileGetterView 下提供了一个文件获取视图。此视图必须用于受保护访问文件。默认情况下，视图仅在用户登录时交付请求的文件。要覆盖行为，可以子类化 FileGetterView 并实现 get_object。只有当 get_object 方法评估模型实例时，视图才会允许访问。简单地返回 None 以阻止访问。

from django_utils.views import FileGetterView

class MyFileView(FileGetterView):
    def get_object(self, model_class, id, request, **kwargs):
        return model_class._default_manager.get(user=request.user, id=id)

URL

要将所有请求资产的请求转发到文件获取视图，请将您的urls与以下模式一起使用

urlpatterns = [
    re_path(r"media/(?P<file_info>.*)", FileGetterView.as_view(), name="media"),
]

您的模式必须以 (?P<file_info>.*) 结尾，并注册文件获取视图。

序列化器

为了使文件获取视图解析某些模型字段，字段必须在序列化器中是 ProtectedImageField

from django_utils.serializer.fields import ProtectedImageField

class MySerializer(Serializer):
    image = ProtectedImageField()

    class Meta:
        fields = (
            "image",
        )

设置

按照以下方式配置您的设置

SENDFILE_BACKEND = "django_sendfile.backends.simple"
SENDFILE_ROOT = self.BASE_DIR / "media"
MEDIA_URL = "/media/"

SENDFILE_ROOT 必须指向存储文件的目录。 MEDIA_URL 必须与url模式匹配。

如果您在生产中使用 uwsgi，请将以下设置应用到您的 uwsgi.ini

plugins = router_static
static-safe = %(base_path)/media
collect-header = X-Sendfile X_SENDFILE
response-route-if-not = empty:${X_SENDFILE} static:${X_SENDFILE}

确保 static-safe 与您的 MEDIA_URL 设置匹配。

缓存

附加文件的对象必须有一个名为 modified 的字段，每次对象更新时都会更改，以便在文件更新时创建新的URL。该字段不是必需的，但为了使缓存正常工作，它是必需的。

身份验证

SessionAuthentication

基于 Django REST Framework 的 SessionAuthentication，此类允许在 API 响应中区分状态码 401 和 403。对于未认证的请求（用户未登录），它返回状态码为 401 的响应；如果用户已登录但权限不足，则返回状态码为 403 的响应。

需要 djangorestframework。

用法

# myproject/settings/base.py

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": ["django_utils.authentication.SessionAuthentication"],
}

删除钩子

Ianus 能够请求用户删除并在用户被删除时进行通知。为了启用此功能，Ianus 需要在服务中存在某些视图。Django Utils 为这些视图提供了默认实现，这些视图处理 Ianus 发出的令牌认证和请求验证。要注册这些视图，请将下面的 urlpatterns 添加到 Ianus 通知的服务中

# urls.py
from django.urls import include

urlpatterns = [
    path("", include("django_utils.webhooks.delete_user.urls")),
]

当 Ianus 请求查询删除用户时，会调用钩子以确定用户是否可以被删除。默认钩子将始终接受查询。然而，可以通过提供具有 inquire_delete 方法的模块来覆盖此行为。为此，配置 IANUS_USER_DELETE_HOOKS 设置并将其指向实现 inquire_delete 方法的模块，如下所示

# settings.py
IANUS_USER_DELETE_HOOKS = "backend.authentication.delete_hooks"

inquire_delete 方法将接收 Ianus 查询删除的用户作为参数。inquire_delete 方法必须返回一个元组，其中第一个元素是一个布尔值，表示查询是否通过，第二个元素是一个字符串形式的理由，告诉 Ianus 失败查询的原因。如果查询成功，理由可以设置为 None，如下所示

# delete_hooks.py
def inquire_delete(user):
    return (True, None)

或者，您可以为 Ianus 返回一个失败消息，指出查询失败的原因，如下所示

# delete_hooks.py
def inquire_delete(user):
    return (False, "User cannot be deleted due to specific reasons.")

此概念同样适用于用户删除通知。必须在同一模块中提供名为 subscribe_delete 的方法来订阅 Ianus 的用户删除。subscribe_delete 方法将接收在 Ianus 中被删除的用户作为参数。默认实现将始终删除用户。您可以在该方法中提供自己的实现，如下所示

# delete_hooks.py
def subscribe_delete(user):
    user.delete()

要配置删除钩子 API 的身份验证令牌，请使用 IANUS_DELETE_HOOK_API_TOKEN 设置。在 Ianus 中配置的身份验证令牌必须与此令牌匹配才能正确进行身份验证。