本文件涵盖了 django.utils . 中的大多数模块 django.utils 是为内部使用而设计的，根据 internal release deprecation policy .
django.utils.cache¶此模块包含用于控制HTTP缓存的帮助程序函数。它通过管理 Vary 响应的标题。它包括直接修补响应对象头的函数，以及更改函数以自己修补头的修饰符。
以获取有关 Vary 标题，请参见 RFC 9110 Section 12.5.5 。
基本上， Vary HTTP头定义在构建缓存键时缓存应考虑哪些头。中名为的头具有相同路径但不同的头内容的请求 Vary 需要获取不同的缓存键以防止传递错误的内容。
例如， internationalization 中间件需要通过 Accept-language 标题。
此函数用于修补 Cache-Control 通过将所有关键字参数添加到标题。改造如下：
所有关键字参数名称都转换为小写，下划线转换为连字符。
如果参数的值为 True （确切地说 True ，而不仅仅是一个真值），只有参数名被添加到头中。
应用后，所有其他参数都将与其值一起添加。 str() 对它。
向给定的 HttpResponse 对象：
Expires
Cache-Control
只有在尚未设置的情况下才会添加每个标题。
cache_timeout 是秒。这个 CACHE_MIDDLEWARE_SECONDS 默认情况下使用设置。
添加一个 Expires 标题设置为当前日期/时间。
添加一个 Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private 响应的标头，指示页面永远不应被缓存。
只有在尚未设置的情况下才会添加每个标题。
添加(或更新) Vary 给定头中的 HttpResponse 对象。 newheaders 是应位于以下位置的标头名称列表 Vary 。如果标头包含星号，则 Vary 页眉将由单个星号组成 '*' ，根据 RFC 9110 Section 12.5.5 。否则，中的现有头 Vary 并没有被移除。
django.utils.dateparse¶此模块中定义的函数共享以下属性：
它们接受iso 8601日期/时间格式的字符串（或一些相近的选项），并从python的相应类返回对象。 datetime 模块。
他们提高 ValueError 如果输入格式正确，但不是有效的日期或时间。
他们回来了 None 如果格式不好的话。
它们在输入中接受高达皮秒的分辨率，但它们将其截断为微秒，因为这正是Python所支持的。
分析字符串并返回 datetime.date .
分析字符串并返回 datetime.time .
不支持UTC偏移；如果 value 描述一个，结果是 None .
分析字符串并返回 datetime.datetime .
支持UTC偏移；如果 value 描述一个，结果是 tzinfo 属性是 datetime.timezone 实例。
分析字符串并返回 datetime.timedelta .
期望格式的数据 "DD HH:MM:SS.uuuuuu" ， "DD HH:MM:SS,uuuuuu" ，或按照ISO 8601的规定（例如 P4DT1H15M20S 这相当于 4 1:15:20 ）或PostgreSQL的日间间隔格式（例如 3 days 04:05:06 )。
django.utils.decorators¶将函数修饰符转换为方法修饰符。它可以用于修饰方法或类；在后一种情况下， name 是要修饰的方法的名称，并且是必需的。
decorator 也可以是函数的列表或元组。它们以相反的顺序包装，以便调用顺序是函数在列表/元组中出现的顺序。
见 decorating class based views 例如用法。
给定一个中间件类，返回一个视图修饰符。这允许您在每个视图的基础上使用中间件功能。创建中间件时没有传递任何参数。
它假定中间件与Django1.9和更早版本的旧样式兼容（具有类似于 process_request() ， process_exception() 和 process_response() ）
喜欢 decorator_from_middleware ，但返回一个接受要传递给中间件类的参数的函数。例如， cache_page() 修饰符是从 CacheMiddleware 这样地：：
cache_page = decorator_from_middleware_with_args(CacheMiddleware)
@cache_page(3600)
def my_view(request):
pass
将中间件标记为 synchronous-only . (The Django中的默认值，但如果默认值在未来版本中发生更改，这可以使您能够适应未来。）
将中间件标记为 asynchronous-only .当从WSGI请求路径调用它时，Django会将它包装在一个非同步事件循环中。
将中间件标记为 sync and async compatible ，这可以避免转换请求。您必须实现当前请求类型的检测才能使用此装饰器。看到 asynchronous middleware documentation 了解更多细节。
django.utils.encoding¶返回A str 表示任意对象的对象 s . 使用 encoding 编解码器。
如果 strings_only 是 True ，不要转换（某些）非字符串类型的对象。
类似于 smart_str() ，除了懒惰实例被解析为字符串，而不是作为懒惰对象保留。
如果 strings_only 是 True ，不要转换（某些）非字符串类型的对象。
返回任意对象的字节字符串版本 s ，按中的规定编码 encoding .
如果 strings_only 是 True ，不要转换（某些）非字符串类型的对象。
类似 smart_bytes ，除了惰性实例解析为字节字符串，而不是作为惰性对象保留。
如果 strings_only 是 True ，不要转换（某些）非字符串类型的对象。
将国际化资源标识符（IRI）部分转换为适合包含在URL中的URI部分。
这是第3.1节中的算法 RFC 3987 Section 3.1 ，稍微简化了一点，因为假设输入是字符串而不是任意字节流。
获取IRI（字符串或UTF-8字节）并返回包含编码结果的字符串。
将统一资源标识符转换为国际化资源标识符。
这是第3.2节中的算法 RFC 3987 Section 3.2 .
以ASCII字节为单位获取一个URI，并返回一个包含编码结果的字符串。
django.utils.feedgenerator¶示例用法：
>>> from django.utils import feedgenerator
>>> feed = feedgenerator.Rss201rev2Feed(
... title="Poynter E-Media Tidbits",
... link="https://www.poynter.org/tag/e-media-tidbits/",
... description="A group blog by the sharpest minds in online media/journalism/publishing.",
... language="en",
... )
>>> feed.add_item(
... title="Hello",
... link="https://www.holovaty.com/test/",
... description="Testing.",
... )
>>> with open("test.rss", "w") as fp:
... feed.write(fp, "utf-8")
...
用于简化发电机用途的选择 feedgenerator.DefaultFeed 目前 Rss201rev2Feed
有关不同版本的RSS的定义，请参见：https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss
创建Taguri。
参见https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id
Stylesheet¶Enclosure¶RssFeed¶Rss201rev2Feed¶RssUserland091Feed¶Atom1Feed¶django.utils.functional¶这个 @cached_property decorator用一个 self 参数作为属性。缓存的结果将保持与实例相同的时间，因此如果传递实例并随后调用函数，则将返回缓存的结果。
考虑一个典型的情况，在将模型实例放入上下文之前，视图可能需要调用模型的方法来执行一些计算，模板可能会再次调用该方法：：
# the model
class Person(models.Model):
def friends(self):
# expensive computation
...
return friends
# in the view:
if person.friends():
...
在模板中，您将拥有：
{% for friend in person.friends %}
在这里， friends() 将被调用两次。从实例开始 person 在视图和模板中是相同的，装饰 friends() 方法与 @cached_property 可以避免：
from django.utils.functional import cached_property
class Person(models.Model):
@cached_property
def friends(self): ...
注意，由于该方法现在是一个属性，所以在Python代码中，需要适当地访问它：：
# in the view:
if person.friends:
...
可以将缓存值视为实例的普通属性：
# clear it, requiring re-computation next time it's called
person.__dict__.pop("friends", None)
# set a value manually, that will persist on the instance until cleared
person.friends = ["Huckleberry Finn", "Tom Sawyer"]
因为这样 descriptor protocol 作品，使用 del （或） delattr ） cached_property 还没有得到加薪 AttributeError .
除了提供潜在的性能优势外， @cached_property 可以确保属性的值在实例的生命周期内不会意外更改。这可能会发生在计算基于 datetime.now() ，或者如果在同一实例上随后调用方法之间的短暂间隔内，某个其他进程将更改保存到数据库中。
您可以使方法的缓存属性。例如，如果你有一个昂贵的 get_friends() 方法并希望允许在不检索缓存值的情况下调用它，可以写入：
friends = cached_property(get_friends)
同时 person.get_friends() 将在每次调用时重新计算朋友，缓存属性的值将保持不变，直到您按上述方式删除它：
x = person.friends # calls first time
y = person.get_friends() # calls again
z = person.friends # does not call
x is z # is True
类似于 @classmethod vt.的. @classproperty 装饰器用单个 cls 参数转换为可以直接从类访问的属性。
Django提供许多实用功能（尤其是 django.utils ）把一个字符串作为第一个参数，并对该字符串做些什么。这些函数由模板过滤器以及直接在其他代码中使用。
如果您编写自己的类似函数并处理翻译，那么当第一个参数是一个懒惰的翻译对象时，您将面临如何处理的问题。您不希望立即将其转换为字符串，因为您可能在视图外部使用此函数（因此当前线程的区域设置将不正确）。
对于这种情况，请使用 django.utils.functional.keep_lazy() 装饰符。它修改函数以便 if 它的参数之一是用一个惰性转换来调用，函数计算会被延迟，直到需要将其转换为字符串为止。
例如：：
from django.utils.functional import keep_lazy, keep_lazy_text
def fancy_utility_function(s, *args, **kwargs):
# Do some conversion on string 's'
...
fancy_utility_function = keep_lazy(str)(fancy_utility_function)
# Or more succinctly:
@keep_lazy(str)
def fancy_utility_function(s, *args, **kwargs): ...
这个 keep_lazy() 装饰师需要一些额外的参数 (*args ）指定原始函数可以返回的类型。一个常见的用例是具有返回文本的函数。对于这些，您可以通过 str 键入至 keep_lazy (or使用 keep_lazy_text() 下一节描述的装饰者）。
使用这个修饰器意味着您可以编写函数并假定输入是一个适当的字符串，然后在末尾添加对惰性转换对象的支持。
捷径 keep_lazy(str)(func) .
如果您有一个返回文本的函数，并且您希望能够在延迟其评估的同时接受懒惰参数，则可以使用此装饰器：：
from django.utils.functional import keep_lazy, keep_lazy_text
# Our previous example was:
@keep_lazy(str)
def fancy_utility_function(s, *args, **kwargs): ...
# Which can be rewritten as:
@keep_lazy_text
def fancy_utility_function(s, *args, **kwargs): ...
django.utils.html¶通常，应该使用django的模板构建HTML，以利用其自动转义机制，并使用 django.utils.safestring 在适当的情况下。此模块提供一些附加的低级实用程序来转义HTML。
返回给定文本，其中包含为在HTML中使用而编码的符号、引号和尖括号。首先将输入强制为字符串，然后输出 mark_safe() 应用。
这类似于 str.format() ，只是它适用于构建HTML片段。第一个论点 format_string 不是转义的，但所有其他参数和Kwarg都通过 conditional_escape() 在被传递给 str.format() 。最后，输出具有 mark_safe() 已申请。
对于构建小HTML片段的情况，此函数优于使用 % 或 str.format() 直接，因为它将转义应用于所有参数——就像模板系统默认应用转义一样。
所以，不要写：
mark_safe(
"%s <b>%s</b> %s"
% (
some_html,
escape(some_text),
escape(some_other_text),
)
)
您应该使用：
format_html(
"{} <b>{}</b> {}",
mark_safe(some_html),
some_text,
some_other_text,
)
这有一个优点，你不需要申请 escape() 对于每个参数，如果您忘记了一个错误和一个XSS漏洞，则会有风险。
请注意，虽然该函数使用 str.format() 要进行插值，请使用由提供的一些格式选项 str.format() (e.g.数字格式）将不起作用，因为所有参数都被传递 conditional_escape() 这（最终）呼吁 force_str() 关于价值观。
包装纸 format_html() ，对于需要使用相同格式字符串格式化的一组参数的常见情况，然后使用 sep . sep 也是通过 conditional_escape() .
args_generator 应该是一个迭代器，产生要传递的参数 format_html() ，位置参数序列或关键字参数映射。
例如，二元组可用于位置参数：：
format_html_join(
"\n",
"<li>{} {}</li>",
((u.first_name, u.last_name) for u in users),
)
或者字典可以用于关键字参数：：
format_html_join(
"\n",
'<li data-id="{id}">{id} {title}</li>',
({"id": b.id, "title": b.title} for b in books),
)
支持中的映射 args_generator 加入浓度
使用其Unicode转义对所有的HTML/XML特殊字符进行转义，因此Value可以安全地与JavaScript一起使用。还将转义的JSON包装在 <script> 标签。如果 element_id 参数不是 None vt.的. <script> 标记被赋予了传递的id。例如：
>>> json_script({"hello": "world"}, element_id="hello-data")
'<script id="hello-data" type="application/json">{"hello": "world"}</script>'
这个 encoder ，默认为 django.core.serializers.json.DjangoJSONEncoder ，将用于序列化数据。见 JSON serialization 有关此序列化程序的详细信息。
尝试从字符串中删除任何看起来像HTML标记的内容，这些内容包含在 <> .
绝对不能保证生成的字符串是HTML安全的。所以永远不要把一个 strip_tag 调用而不首先转义它，例如 escape() .
例如：：
strip_tags(value)
如果 value 是 "<b>Joel</b> <button>is</button> a <span>slug</span>" 返回值为 "Joel is a slug" .
如果您正在寻找更健壮的解决方案，请考虑使用第三方HTML清理工具。
这个 __html__() 类上的方法帮助非Django模板检测其输出不需要HTML转义的类。
这个修饰符定义了 __html__() 包装装饰类的方法 __str__() 在里面 mark_safe() . 确保 __str__() 方法确实返回不需要HTML转义的文本。
django.utils.http¶python的一个版本 urllib.parse.urlencode() 可操作的功能 MultiValueDict 和非字符串值。
格式化时间以匹配 RFC 1123 Section 5.2.14 由HTTP指定的日期格式 RFC 9110 Section 5.6.7 。
接受自UTC中的epoch以来以秒表示的浮点数，例如由 time.time() . 如果设置为 None ，默认为当前时间。
以格式输出字符串 Wdy, DD Mon YYYY HH:MM:SS GMT .
django.utils.module_loading¶用于使用Python模块的函数。
django.utils.safestring¶用于处理“安全字符串”的函数和类：可以安全显示的字符串，而无需在HTML中进一步转义。将某些内容标记为“安全字符串”意味着字符串的生产者已经将HTML引擎（例如“<”）不应解释的字符转换为适当的实体。
为了（HTML）输出目的，显式地将字符串标记为安全字符串。返回的对象可以在字符串合适的任何地方使用。
可以在单个字符串上多次调用。
也可用作装饰。
对于构建HTML片段，通常应该使用 django.utils.html.format_html() 相反。
标记为SAFE的字符串如果被修改，将再次变得不安全。例如：
>>> mystr = "<b>Hello World</b> "
>>> mystr = mark_safe(mystr)
>>> type(mystr)
<class 'django.utils.safestring.SafeString'>
>>> mystr = mystr.strip() # removing whitespace
>>> type(mystr)
<type 'str'>
django.utils.text¶一个版本 str.format() 因为什么时候 format_string ， args 和/或 kwargs 包含惰性对象。第一个参数是要格式化的字符串。例如：：
from django.utils.text import format_lazy
from django.utils.translation import pgettext_lazy
urlpatterns = [
path(
format_lazy("{person}/<int:pk>/", person=pgettext_lazy("URL", "person")),
PersonDetailView.as_view(),
),
]
此示例允许翻译人员翻译URL的一部分。如果将“person”转换为“persona”，则正则表达式将匹配 persona/(?P<pk>\d+)/$ ，例如 persona/5/ .
通过以下方式将字符串转换为URL段塞：
转换为ASCII if allow_unicode 是 False （默认值）。
转换为小写。
删除不是字母数字、下划线、连字符或空格的字符。
用单个破折号替换任何空白或重复的破折号。
删除开头和结尾空白、破折号和强调线。
例如：
>>> slugify(" Joel is a slug ")
'joel-is-a-slug'
如果要允许使用Unicode字符，请传递 allow_unicode=True 。例如：
>>> slugify("你好 World", allow_unicode=True)
'你好-world'
django.utils.timezone¶返回A tzinfo 表示与UTC有固定偏移量的时区的实例。
offset 是一个 datetime.timedelta 或整数分钟数。对于UTC以东的时区使用正值，对于UTC以西的时区使用负值。
返回A tzinfo 表示的实例 default time zone .
返回的名称 default time zone .
返回A tzinfo 表示的实例 current time zone .
返回的名称 current time zone .
设置 current time zone . 这个 timezone 参数必须是 tzinfo 子类或时区名称。
颠覆 current time zone .
这是一个python上下文管理器，用于设置 current time zone 进入与 activate() ，并在退出时恢复先前活动的时区。如果 timezone 论证是 None , the current time zone 在输入时取消设置 deactivate() 相反。
override 也可用作函数修饰器。
转换感知 datetime 到其他时区，默认情况下 current time zone .
什么时候？ value 省略，默认为 now() .
此函数不适用于原始日期时间；使用 make_aware() 相反。
使用 localtime() 转换意识 datetime 到A date() 在不同的时区中，默认情况下 current time zone .
什么时候？ value 省略，默认为 now() .
此函数不适用于原始日期时间。
返回一个已知 datetime 表示与 value 在里面 timezone ， value 幼稚 datetime .如果 timezone 设置为 None ，默认为 current time zone .
返朴归真 datetime 代表 timezone 同一时间点 value ， value 有意识 datetime .如果 timezone 设置为 None ，默认为 current time zone .
django.utils.translation¶有关以下用法的完整讨论，请参阅 translation documentation .
与上面的非惰性版本相同，但使用惰性执行。
标记字符串进行翻译，但现在不进行翻译。这可用于将字符串存储在全局变量中，这些变量应保持在基础语言中（因为它们可能在外部使用），并将在以后进行转换。
Python上下文管理器，使用 django.utils.translation.activate() 要获取给定语言的翻译对象，将其激活为当前线程的翻译对象，并在退出时重新激活之前的活动语言。或者，它可以在退出时停用临时翻译 django.utils.translation.deactivate() 如果 deactivate 论据是 True .如果你通过 None 作为语言论据，a NullTranslations() 实例在上下文中被激活。
override 也可用作函数修饰器。
返回当前选定的语言代码。退换商品 None 如果翻译被暂时停用（由 deactivate_all() 或者什么时候 None 传递给 override() ）
分析请求，找出用户希望系统显示的语言。只考虑settings.languages中列出的语言。如果用户请求一个子语言，其中我们有一个主语言，我们发送主语言。
如果 check_path 是 True ，函数首先检查请求的URL的路径是否以中列出的语言代码开头。 LANGUAGES 设置。
返回 lang_code 如果它在 LANGUAGES 设置，可能选择更通用的变体。例如， 'es' 如果返回 lang_code 是 'es-ar' 和 'es' 是在 LANGUAGES 但是 'es-ar' 不是。
lang_code 最大可接受长度为500个字符。一 LookupError 如果 lang_code 超过这个限制， strict 是 True ，或者如果没有通用变体， strict 是 False .
如果 strict 是 False （默认值），当未找到语言代码或其通用变量时，可以返回特定于国家/地区的变量。例如，如果只有 'es-co' 是在 LANGUAGES ，返回 lang_code 类的 'es' 和 'es-ar' . 如果 strict=True .
加薪 LookupError 如果找不到任何东西。
5月 28, 2025