django-tools 0.56.2

django的杂项工具。

还可以查看兄弟项目：django-cms-tools（Django-CMS周围的工具/助手）。

| | https://pypi.python.org/pypi/django-tools/ | | | github.com/jedie/django-tools/actions | | | codecov.io/gh/jedie/django-tools | | | coveralls.io/r/jedie/django-tools |

(Logo contributed by @reallinfo see #16)

试用

例如

~$ git clone https://github.com/jedie/django-tools.git
~$ cd django-tools/
~/django-tools$ ./manage.py

现有内容

为允许的用户提供用户媒体文件

只为允许的用户提供settings.MEDIA_ROOT文件。

请参阅此处单独的README：django_tools/serve_media_app

模式版本保护

通过添加自动递增的版本号，保护模型免受用较旧的条目覆盖较新的条目。

请参阅此处单独的README：django_tools/model_version_protect

OverwriteFileSystemStorage

一个Django文件系统存储，如果内容发生变化，将覆盖现有文件并可以创建备份。

class ExampleModel(models.Model):
    foo_file = models.FileField(
        storage=OverwriteFileSystemStorage(create_backups=True)
    )
    bar_image = models.ImageField(
        storage=OverwriteFileSystemStorage(create_backups=False)
    )

备份通过追加后缀和序列号创建，例如。

• 源....: foo.bar
• 备份 1..: foo.bar.bak
• 备份 2..: foo.bar.bak0
• 备份3..: foo.bar.bak1

只有当文件内容改变时才会创建备份文件。但至少要备份一次！

Django日志工具

将其放入您的设置中，例如：

from django_tools.unittest_utils.logging_utils import CutPathnameLogRecordFactory, FilterAndLogWarnings

# Filter warnings and pipe them to logging system
# Warnings of external packages are displayed only once and only the file path.
warnings.showwarning = FilterAndLogWarnings()

# Adds 'cut_path' attribute on log record. So '%(cut_path)s' can be used in log formatter.
logging.setLogRecordFactory(CutPathnameLogRecordFactory(max_length=50))

LOGGING = {
    # ...
    'formatters': {
        'verbose': {
            'format': '%(levelname)8s %(cut_path)s:%(lineno)-3s %(message)s'
        },
    },
    # ...
}

(例如，通过以下方式激活警告：export PYTHONWARNINGS=all)

ThrottledAdminEmailHandler

ThrottledAdminEmailHandler的工作方式与原始的django.utils.log.AdminEmailHandler类似，但会限制在一定时间范围内发送的邮件数量。使用示例：

LOGGING = {
    # ...
    "handlers": {
        "mail_admins": {
            "level": "ERROR",
            "class": "django_tools.log_utils.throttle_admin_email_handler.ThrottledAdminEmailHandler",
            "formatter": "email",
            "min_delay_sec": 20, # << -- skip mails in this time range
        },
        # ...
    },
    # ...
}

django_tools.template.loader.DebugCacheLoader

将模板名称作为HTML注释插入，例如：

<!-- START 'foo/bar.html' -->
...
<!-- END 'foo/bar.html' -->

要使用此功能，您必须将django_tools.template.loader.DebugCacheLoader添加为模板加载器。

例如：仅在DEBUG模式下激活

if DEBUG:
    TEMPLATES[0]["OPTIONS"]["loaders"] = [
        (
            "django_tools.template.loader.DebugCacheLoader", (
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
            )
        )
    ]

发送文本+HTML邮件

一个辅助类，用于使用Django模板库发送文本+HTML邮件。

您需要两个模板文件，例如：

• mail_test.txt
• mail_test.html

您必须按如下方式指定模板文件：template_base="mail_test.{ext}"

通过Celery任务发送

# settings.py
SEND_MAIL_CELERY_TASK_NAME="mail:send_task"

from django_tools.mail.send_mail import SendMailCelery
SendMailCelery(
    template_base="mail_test.{ext}",
    mail_context={"foo": "first", "bar": "second"},
    subject="Only a test",
    recipient_list="foo@bar.tld"
).send()

不使用Celery发送

from django_tools.mail.send_mail import SendMail
SendMail(
    template_base="mail_test.{ext}",
    mail_context={"foo": "first", "bar": "second"},
    subject="Only a test",
    recipient_list="foo@bar.tld"
).send()

请参阅现有的单元测试

• django_tools_tests/test_email.py

延迟工具

有时您想模拟处理需要更长一点的时间。为此，存在django_tools.debug.delay.SessionDelay和django_tools.debug.delay.CacheDelay。使用将创建日志条目和用户消息，如果用户已认证。

更多信息请参阅单独的django_tools/debug/README.creole文件。

文件管理器库

用于构建类似文件管理器、画廊等Django应用的库。

更多信息，请阅读./filemanager/README.creole

按站点的缓存中间件

类似于django UpdateCacheMiddleware和FetchFromCacheMiddleware，但有一些增强功能：./cache/README.creole中的“按站点缓存”

平滑缓存后端

与django缓存后端相同，但添加了cache.smooth_update()，可以平滑地根据当前系统负载清除缓存。更多信息请参阅：./cache/README.creole中的“平滑缓存后端”

本地同步缓存

在多线程环境中保持本地字典的最新状态。对于缓存字典很有用。更多信息，请阅读./local_sync_cache/local_sync_cache.py中的文档字符串。

threadlocals中间件

要在任何地方获取请求对象，请使用./middlewares/ThreadLocal.py

动态SITE_ID中间件

注意：目前未维护！TODO：修复所有python/django版本的单元测试

使用基于当前请求域名名的中间件动态设置settings.SITE_ID。域名别名可以是简单的字符串，也可以是正则表达式。

更多信息，请阅读./dynamic_site/README.creole

StackInfoStorage

类似于LegacyFallbackStorage的消息存储，但每个消息都会有一个堆栈信息，这对调试很有帮助。只有在settings.DEBUG或MESSAGE_DEBUG开启时才会添加堆栈信息。要使用它，请将以下内容放入您的设置中：

MESSAGE_STORAGE = "django_tools.utils.messages.StackInfoStorage"

更多信息，请阅读./utils/messages.py中的文档字符串。

限制到用户组

通过选择仅有一个字段来限制某些内容

• 匿名用户
• 员工用户
• 超级用户
• ..所有现有的用户组..

更多信息，请阅读./limit_to_usergroups.py中的文档字符串。

权限辅助工具

请参阅django_tools.permissions和单元测试：django_tools_tests.test_permissions

表单/模型字段

• 目录字段 - 检查是否存在并在定义的基路径中
• 带有验证器的语言代码字段
• 媒体路径字段 浏览现有路径以选择和验证输入
• 签名分隔的表单/模型字段 例如逗号分隔的字段
• 静态路径字段
• URL字段 原始django表单URLField的灵活版本

单元测试辅助工具

Selenium测试用例

有Firefox和Chromium测试用例，包括和不包括django StaticLiveServerTestCase！

Chromium + StaticLiveServer示例

from django_tools.selenium.chromedriver import chromium_available
from django_tools.selenium.django import SeleniumChromiumStaticLiveServerTestCase

@unittest.skipUnless(chromium_available(), "Skip because Chromium is not available!")
class ExampleChromiumTests(SeleniumChromiumStaticLiveServerTestCase):
    def test_admin_login_page(self):
        self.driver.get(self.live_server_url + "/admin/login/")
        self.assert_equal_page_title("Log in | Django site admin")
        self.assert_in_page_source('<form action="/admin/login/" method="post" id="login-form">')
        self.assert_no_javascript_alert()

Firefox + StaticLiveServer示例

from django_tools.selenium.django import SeleniumFirefoxStaticLiveServerTestCase
from django_tools.selenium.geckodriver import firefox_available

@unittest.skipUnless(firefox_available(), "Skip because Firefox is not available!")
class ExampleFirefoxTests(SeleniumFirefoxStaticLiveServerTestCase):
    def test_admin_login_page(self):
        self.driver.get(self.live_server_url + "/admin/login/")
        self.assert_equal_page_title("Log in | Django site admin")
        self.assert_in_page_source('<form action="/admin/login/" method="post" id="login-form">')
        self.assert_no_javascript_alert()

无StaticLiveServer的测试用例

from django_tools.selenium.chromedriver import SeleniumChromiumTestCase
from django_tools.selenium.geckodriver import SeleniumFirefoxTestCase

也请参阅此处现有的单元测试

• /django_tools/django_tools_tests/test_unittest_selenium.py

设置Web驱动程序

Selenium测试用例需要浏览器和Web驱动程序。

SeleniumChromiumTestCase和SeleniumFirefoxTestCase将通过webdriver-manager自动安装Web驱动程序

有一个小的CLI（称为django_tools_selenium）来检查/安装Web驱动程序，例如

~/django-tools$ poetry run django_tools_selenium install
~/django-tools$ poetry run django_tools_selenium info

Mockup实用工具

创建带有文本的PIL/django-filer图像的占位符，请参阅

• /django_tools/unittest_utils/mockup.py

用法/测试

• /django_tools_tests/test_mockup.py

模型实例单元测试代码生成器

从现有模型实例生成单元测试代码框架。您可以将此功能用作django manage命令或作为管理操作。

作为管理命令的使用，例如

$ ./manage.py generate_model_test_code auth.
...
#
# pk:1 from auth.User <class 'django.contrib.auth.models.User'>
#
user = User.objects.create(
    password='pbkdf2_sha256$36000$ybRfVQDOPQ9F$jwmgc5UsqRQSXxJs/NrZeTLguieUSSZfaSZbMmC+L5w=', # CharField, String (up to 128)
    last_login=datetime.datetime(2018, 4, 24, 8, 27, 49, 578107, tzinfo=<UTC>), # DateTimeField, Date (with time)
    is_superuser=True, # BooleanField, Boolean (Either True or False)
    username='test', # CharField, String (up to 150)
    first_name='', # CharField, String (up to 30)
    last_name='', # CharField, String (up to 30)
    email='', # CharField, Email address
    is_staff=True, # BooleanField, Boolean (Either True or False)
    is_active=True, # BooleanField, Boolean (Either True or False)
    date_joined=datetime.datetime(2018, 3, 6, 17, 15, 50, 93136, tzinfo=<UTC>), # DateTimeField, Date (with time)
)
...

创建用户

/unittest_utils/user.py:

• django_tools.unittest_utils.user.create_user() - 创建用户，获取超级用户
• django_tools.unittest_utils.user.get_super_user() - 获取第一个现有超级用户

隔离文件系统装饰器/上下文管理器

django_tools.unittest_utils.isolated_filesystem.isolated_filesystem可以作为装饰器或上下文管理器。对于将在当前工作目录中创建文件/目录的测试非常有用，它执行以下操作

• 创建一个新的临时目录
• 将当前工作目录更改为临时目录
• 退出后
• 删除整个临时目录树

例如使用

from django_tools.unittest_utils.isolated_filesystem import isolated_filesystem

with isolated_filesystem(prefix="temp_dir_prefix"):
    open("foo.txt", "w").write("bar")

BaseUnittestCase

django_tools.unittest_utils.unittest_base.BaseUnittestCase包含一些底层断言方法

• assertEqual_dedent()

注意：断言方法将在将来迁移到：django_tools.unittest_utils.assertments！

django_tools.unittest_utils.tempdir包含TempDir，一个上下文管理类

with TempDir(prefix="foo_") as tempfolder:
    # create a file:
    open(os.path.join(tempfolder, "bar"), "w").close()

# the created temp folder was deleted with shutil.rmtree()

用法/测试

• /django_tools_tests/test_unittest_utils.py

DjangoCommandMixin

帮助运行shell命令。例如：在单元测试中使用“./manage.py cms check”。

用法/测试

• /django_tools_tests/test_unittest_django_command.py

单元测试中的DOM比较

问题：您无法轻松检查例如某些表单输入字段是否在响应中，因为表单渲染使用字典存储所有HTML属性。因此，表单字段属性的顺序未排序且不固定。

解决方案：您需要将响应内容解析为DOM树并比较节点。

我们添加了Gregor Müllegger在GSoC 2011表单渲染分支上的出色工作。您将拥有以下继承自：django_tools.unittest_utils.unittest_base.BaseTestCase的断言方法

• self.assertHTMLEqual() – 比较两个HTML DOM树
• self.assertDOM() – 检查响应中的节点是否存在。
• self.assertContains() – 检查节点在响应中出现的次数为“count”

更多信息示例请参阅./django_tools_tests/test_dom_asserts.py

@set_string_if_invalid() 装饰器

辅助函数，用于检查是否存在缺失的模板标签，通过设置临时变量 'string_if_invalid' 实现，请参阅：https://docs.django.ac.cn/en/1.8/ref/templates/api/#invalid-template-variables

用法示例：

from django.test import SimpleTestCase
from django_tools.unittest_utils.template import TEMPLATE_INVALID_PREFIX, set_string_if_invalid

@set_string_if_invalid()
class TestMyTemplate(SimpleTestCase):
    def test_valid_tag(self):
        response = self.client.get('/foo/bar/')
        self.assertNotIn(TEMPLATE_INVALID_PREFIX, response.content)

您还可以装饰测试方法 ;)

unittest_utils/signals.py

• SignalsContextManager 通过 with 语句连接/断开信号回调

unittest_utils/assertions.py

该文件包含一些常用的断言函数

• assert_startswith - 检查测试是否以指定前缀开始。
• assert_endswith - 检查文本是否以指定后缀结束。
• assert_locmem_mail_backend - 检查当前电子邮件后端是否为内存后端。
• {{{assert_language_code() - 检查给定的 language_code 是否在 settings.LANGUAGES 中
• assert_installed_apps() - 检查 settings.INSTALLED_APPS 中的条目
• assert_is_dir - 检查给定路径是否为目录
• assert_is_file - 检查给定路径是否为文件
• assert_path_not_exists - 检查给定路径不存在

加速测试

通过禁用迁移来加速测试运行，例如：

from django_tools.unittest_utils.disable_migrations import DisableMigrations
MIGRATION_MODULES = DisableMigrations()

小型工具

debug_csrf_failure()

显示正常的调试页面，而不是最小化的 csrf 调试页面。更多信息请参阅 DocString：django_tools/views/csrf.py

导入库辅助工具

对现有的 importlib 进行扩展的额外辅助工具，更多信息请参阅源代码：./utils/importlib.py

http 工具

增强 HttpRequest 以获取有关请求的更多信息。更多信息请参阅 DocString：django_tools/utils/http.py

@display_admin_error

开发人员助手，用于在 ModelAdmin.list_display 调用中显示静默错误。请参阅：display_admin_error 在 decorators.py

升级虚拟环境

一个简单的命令行脚本，它为虚拟环境中的每个已安装的包调用 pip install —-upgrade XY。只需将其复制/符号链接到虚拟环境的根目录并启动即可。

注意：似乎这个解决方案无法正确观察可编辑项。

要使用它，而无需安装 django-tools

~/$ cd goto/your_env
.../your_env/$ wget https://github.com/jedie/django-tools/raw/master/django_tools/upgrade_virtualenv.py
.../your_env/$ chmod +x upgrade_virtualenv.py
.../your_env/$ ./upgrade_virtualenv.py

如果 pip 有自己的升级命令，则此脚本将过时。

django_tools.utils.url.GetDict

类似于原始 django.http.QueryDict，但

• urlencode() 不会为空值添加 "="：使用 "?empty" 而不是 "?empty="
• 始终可变
• 输出将按顺序排序（更容易进行测试 ;)

更多信息，请参阅测试：django_tools_tests/test_utils_url.py

SignedCookieStorage

使用 django.core.signing 将信息存储在签名 Cookie 中，因此客户端无法操纵 Cookie 数据。来源/示例

• /django_tools/utils/client_storage.py
• /django_tools_tests/test_signed_cookie.py

打印 SQL 查询

通过上下文管理器打印使用的 SQL 查询。

例如使用

from django_tools.unittest_utils.print_sql import PrintQueries

# e.g. use in unittests:
class MyTests(TestCase):
    def test_foobar(self):
        with PrintQueries("Create object"):
            FooBar.objects.create("name"=foo)

# e.g. use in views:
def my_view(request):
    with PrintQueries("Create object"):
        FooBar.objects.create("name"=foo)

输出如下

_______________________________________________________________________________
 *** Create object ***
1 - INSERT INTO "foobar" ("name")
    VALUES (foo)
-------------------------------------------------------------------------------

SetRequestDebugMiddleware

中间件，用于向请求对象添加 debug bool 属性。更多信息：./debug/README.creole

TracebackLogMiddleware

通过在 process_exception() 上调用 logging.exception() 将堆栈跟踪放入日志中。通过以下方式激活：

MIDDLEWARE_CLASSES = (
    ...
    'django_tools.middlewares.TracebackLogMiddleware.TracebackLogMiddleware',
    ...
)

FnMatchIps() - 在 INTERNAL_IPS / ALLOWED_HOSTS 中使用 Unix shell-style 通配符

settings.py 例如：

from django_tools.settings_utils import FnMatchIps

INTERNAL_IPS = FnMatchIps(["127.0.0.1", "::1", "192.168.*.*", "10.0.*.*"])
ALLOWED_HOSTS = FnMatchIps(["127.0.0.1", "::1", "192.168.*.*", "10.0.*.*"])

StdoutStderrBuffer()

将 stdout + stderr 重定向到字符串缓冲区。例如：

from django_tools.unittest_utils.stdout_redirect import StdoutStderrBuffer

with StdoutStderrBuffer() as buffer:
    print("foo")
output = buffer.get_output() # contains "foo\n"

管理命令

permission_info

列出特定 django 用户的全部权限。（需要将 'django_tools' 添加到 INSTALLED_APPS 中）

例如

$ ./manage.py permission_info
No username given!

All existing users are:
foo, bar, john, doe

$ ./manage.py permission_info foo
All permissions for user 'test_editor':
	is_active    : yes
	is_staff     : yes
	is_superuser : no
[*] admin.add_logentry
[*] admin.change_logentry
[*] admin.delete_logentry
[ ] auth.add_group
[ ] auth.add_permission
[ ] auth.add_user
...

logging_info

显示所有日志记录器的列表，并标记哪些已在settings.LOGGING中配置。

$ ./manage.py logging_info

nice_diffsettings

类似于django 'diffsettings'，但使用美化打印的表示。

$ ./manage.py nice_diffsettings

database_info

仅显示有关所使用数据库和连接的一些信息。

$ ./manage.py database_info

list_models

仅以app_label.ModelName格式列出所有现有模型。在'dumpdata'等操作中很有用。

$ ./manage.py list_models

..所有其他...

存在许多杂项内容。查看源代码，luke！

向后不兼容的更改

旧更改存档在此git历史记录中

• >=v0.47
• >=v0.35

v0.51

所有Selenium辅助函数已弃用，请迁移到Playwright ;)

v0.50

已移除旧selenium辅助函数，自v0.43弃用

使所有Selenium WebDriver实例在整个测试会话中持久化。这加快了测试速度并修复了一些Selenium中的错误。

这导致所有测试类的浏览器/WebDriver设置相同！

v0.55

将支持的Django/Python最小版本移动到

• Django 4.1, 4.2, 5.1
• Python 3.11, 3.12

Django兼容性

（有关pyproject.toml中tox组合的更多信息，请参阅此处）

历史记录

• v0.56.2
  • 2024-08-25 - Bugfix: 删除覆盖现有代码的空包
• v0.56.1
  • 2024-08-25 - 在测试中使用typeguard
  • 2024-08-25 - 使用cli_base update-readme-history
  • 2024-08-25 - 通过manageprojects更新
• v0.56.0
  • 2024-08-25 - Bugfix：在真实终端中运行本地测试
  • 2024-08-25 - 修复CI
  • 2023-04-10 - Upgrade：使用managed-django-projec，移除弃用功能，更新支持的版本
• v0.54.0
  • 2022-09-15 - Bugfix版本检查
  • 2022-08-23 - 将README.creole替换为README.md
  • 2022-08-26 - 在CI中运行safety检查
  • 2022-08-25 - NEW：SyslogHandler，用于轻松将日志记录到syslog

链接

| 首页 | https://github.com/jedie/django-tools | | PyPi | https://pypi.python.org/pypi/django-tools/ |

捐赠

• paypal.me/JensDiemer
• Flattr This!
• 向比特币地址1823RZ5Md1Q2X5aSXRC5LRPcYdveCiVX6F发送