django.utils.cache¶

此模块包含用于控制 HTTP 缓存的辅助函数。它通过管理响应的 Vary 标头来实现。它包括直接修补响应对象的标头的函数，以及将函数更改为自行执行该标头修补的装饰器。

有关 Vary 标头的信息，请参见RFC 9110 第 12.5.5 节。

本质上，Vary HTTP 标头定义了缓存构建其缓存键时应考虑哪些标头。具有相同路径但 Vary 中命名的标头的标头内容不同的请求需要获取不同的缓存键，以防止传递错误的内容。

例如，国际化 中间件需要根据 Accept-language 标头区分缓存。

patch_cache_control(response, **kwargs)[source]¶

此函数通过向其添加所有关键字参数来修补 Cache-Control 标头。转换如下

• 所有关键字参数名称都转换为小写，下划线转换为连字符。

• 如果参数的值为 True（正好是 True，而不仅仅是真值），则仅将参数名称添加到标头中。

• 所有其他参数都与其值一起添加，在应用 str() 之后。

get_max_age(response)[source]¶

从响应 Cache-Control 标头返回 max-age 作为整数（如果未找到或不是整数，则返回 None）。

patch_response_headers(response, cache_timeout=None)[source]¶

向给定的 HttpResponse 对象添加一些有用的标头

• Expires

• Cache-Control

仅当标头尚未设置时才添加每个标头。

cache_timeout 以秒为单位。默认情况下使用 CACHE_MIDDLEWARE_SECONDS 设置。

add_never_cache_headers(response)[source]¶

将 Expires 标头添加到当前日期/时间。

将 Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private 标头添加到响应中，以指示页面永远不应该被缓存。

仅当标头尚未设置时才添加每个标头。

patch_vary_headers(response, newheaders)[source]¶

在给定的 HttpResponse 对象中添加（或更新）Vary 标头。 newheaders 是应该在 Vary 中的标头名称列表。如果 headers 包含星号，则 Vary 标头将仅包含一个星号 '*'，根据RFC 9110 第 12.5.5 节。否则，不会删除 Vary 中现有的标头。

get_cache_key(request, key_prefix=None, method='GET', cache=None)[source]¶

根据请求路径返回缓存键。它可以在请求阶段使用，因为它从全局路径注册表中提取要考虑的标头列表，并使用它们构建要检查的缓存键。

如果没有存储标头列表，则需要重建页面，因此此函数返回 None。

learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None)[source]¶

从响应对象中了解为某些请求路径考虑哪些标头。它将这些标头存储在全局路径注册表中，以便以后访问该路径将知道要考虑哪些标头，而无需构建响应对象本身。标头在响应的 Vary 标头中命名，但我们希望防止响应生成。

用于缓存键生成的标头列表存储在与页面本身相同的缓存中。如果缓存使某些数据从缓存中过期，则意味着我们必须构建响应一次才能获取 Vary 标头，以及用于缓存键的标头列表。

django.utils.dateparse¶

此模块中定义的函数具有以下属性

• 它们接受 ISO 8601 日期/时间格式（或一些接近的替代格式）的字符串，并返回 Python 的 datetime 模块中相应类的对象。

• 如果它们的输入格式正确但不是有效的日期或时间，则会引发 ValueError。

• 如果格式完全错误，则返回 None。

• 它们接受高达皮秒级的输入分辨率，但会将其截断为微秒，因为这是 Python 支持的。

parse_date(value)[source]¶

解析字符串并返回 datetime.date。

parse_time(value)[source]¶

解析字符串并返回一个 datetime.time。

不支持 UTC 偏移量；如果 value 描述了 UTC 偏移量，则结果为 None。

parse_datetime(value)[source]¶

解析字符串并返回一个 datetime.datetime。

支持 UTC 偏移量；如果 value 描述了 UTC 偏移量，则结果的 tzinfo 属性为 datetime.timezone 实例。

parse_duration(value)[source]¶

解析字符串并返回一个 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¶

method_decorator(decorator, name='')[source]¶

将函数装饰器转换为方法装饰器。它可以用来装饰方法或类；在后一种情况下，name 是要装饰的方法的名称，并且是必需的。

decorator 也可以是函数列表或元组。它们以相反的顺序包装，以便调用顺序是函数在列表/元组中出现的顺序。

参见 装饰基于类的视图 以了解示例用法。

decorator_from_middleware(middleware_class)[source]¶

给定一个中间件类，返回一个视图装饰器。这允许您在每个视图的基础上使用中间件功能。中间件是在没有传递参数的情况下创建的。

它假设与 Django 1.9 及更早版本的老式风格兼容的中间件（具有诸如 process_request()、process_exception() 和 process_response() 之类的方法）。

decorator_from_middleware_with_args(middleware_class)[source]¶

类似于 decorator_from_middleware，但返回一个接受要传递给中间件类的参数的函数。例如，cache_page() 装饰器就是这样从 CacheMiddleware 创建的

cache_page = decorator_from_middleware_with_args(CacheMiddleware)


@cache_page(3600)
def my_view(request):
    pass

sync_only_middleware(middleware)[source]¶

将中间件标记为 仅同步。（Django 中的默认值，但这允许您在将来版本中默认值发生更改时进行防范。）

async_only_middleware(middleware)[source]¶

将中间件标记为 仅异步。当从 WSGI 请求路径调用它时，Django 会将其包装在一个异步事件循环中。

sync_and_async_middleware(middleware)[source]¶

将中间件标记为 同步和异步兼容，这允许避免转换请求。您必须实现对当前请求类型的检测才能使用此装饰器。有关详细信息，请参阅 异步中间件文档。

django.utils.encoding¶

smart_str(s, encoding='utf-8', strings_only=False, errors='strict')[source]¶

返回表示任意对象 s 的 str 对象。使用 encoding 编码处理字节字符串。

如果 strings_only 为 True，则不转换（某些）非字符串类型的对象。

is_protected_type(obj)[source]¶

确定对象实例是否为受保护类型。

当传递给 force_str(strings_only=True) 时，受保护类型的对象会按原样保留。

force_str(s, encoding='utf-8', strings_only=False, errors='strict')[source]¶

类似于 smart_str()，除了延迟实例被解析为字符串，而不是保留为延迟对象。

如果 strings_only 为 True，则不转换（某些）非字符串类型的对象。

smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')[source]¶

返回任意对象 s 的字节字符串版本，编码方式如 encoding 中指定。

如果 strings_only 为 True，则不转换（某些）非字符串类型的对象。

force_bytes(s, encoding='utf-8', strings_only=False, errors='strict')[source]¶

类似于 smart_bytes，除了延迟实例被解析为字节字符串，而不是保留为延迟对象。

如果 strings_only 为 True，则不转换（某些）非字符串类型的对象。

iri_to_uri(iri)[source]¶

将国际化资源标识符 (IRI) 部分转换为适合包含在 URL 中的 URI 部分。

这是来自 RFC 3987 第 3.1 节 的算法，稍微简化了一下，因为假设输入是一个字符串而不是一个任意的字节流。

接收一个 IRI（字符串或 UTF-8 字节）并返回一个包含编码结果的字符串。

uri_to_iri(uri)[source]¶

将统一资源标识符 (URI) 转换为国际化资源标识符 (IRI)。

这是来自 RFC 3987 第 3.2 节 的算法。

接收一个 ASCII 字节格式的 URI 并返回一个包含编码结果的字符串。

filepath_to_uri(path)[source]¶

将文件系统路径转换为适合包含在 URL 中的 URI 部分。假设路径为 UTF-8 字节、字符串或 Path。

此方法将对某些通常被识别为 URI 特殊字符的字符进行编码。请注意，此方法不会对 ' 字符进行编码，因为它是 URI 中的有效字符。有关详细信息，请参阅 encodeURIComponent() JavaScript 函数。

返回一个包含编码结果的 ASCII 字符串。

escape_uri_path(path)[source]¶

转义统一资源标识符 (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

get_tag_uri(url, date)[source]¶

创建 TagURI。

请参阅 https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id

django.utils.functional¶

class cached_property(func)[source]¶

@cached_property 装饰器将具有单个 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 是相同的，因此使用 @cached_property 装饰 friends() 方法可以避免这种情况。

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
del person.friends  # or delattr(person, "friends")

# set a value manually, that will persist on the instance until cleared
person.friends = ["Huckleberry Finn", "Tom Sawyer"]

由于 描述符协议 的工作方式，在尚未访问过的 cached_property 上使用 del（或 delattr）会引发 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

class classproperty(method=None)[source]¶

类似于 @classmethod，@classproperty 装饰器将具有单个 cls 参数的方法的结果转换为可以直接从类访问的属性。

keep_lazy(func, *resultclasses)[source]¶

Django 提供了许多实用函数（尤其是在 django.utils 中），这些函数将字符串作为其第一个参数并对该字符串执行某些操作。这些函数被模板过滤器以及其他代码直接使用。

如果您编写了自己的类似函数并处理翻译，您将面临当第一个参数是延迟翻译对象时该怎么办的问题。您不希望立即将其转换为字符串，因为您可能在视图之外使用此函数（因此当前线程的区域设置将不正确）。

对于这种情况，请使用 django.utils.functional.keep_lazy() 装饰器。它修改函数，以便如果它使用延迟翻译作为其参数之一被调用，则函数评估将延迟到需要将其转换为字符串时。

例如

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（或使用下一节中描述的 keep_lazy_text() 装饰器）。

使用此装饰器意味着您可以编写您的函数并假设输入是一个正确的字符串，然后在最后添加对延迟翻译对象的支持。

keep_lazy_text(func)[source]¶

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 转义实用程序。

escape(text)[source]¶

将给定的文本中的 &、引号和尖括号进行编码，以便在 HTML 中使用。输入首先被强制转换为字符串，输出应用了 mark_safe()。

conditional_escape(text)[source]¶

类似于 escape()，但它不会对预先转义的字符串进行操作，因此不会进行双重转义。

format_html(format_string, *args, **kwargs)[source]¶

这类似于 str.format()，但它适用于构建 HTML 片段。第一个参数 format_string 不会被转义，但所有其他 args 和 kwargs 都会通过 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() 提供的一些格式化选项（例如数字格式化）将无法使用，因为所有参数都通过 conditional_escape() 传递，后者（最终）会对这些值调用 force_str()。

自版本 5.0 起已弃用: 不支持在不传递 args 或 kwargs 的情况下调用 format_html()。

format_html_join(sep, format_string, args_generator)[source]¶

format_html() 的包装器，用于需要使用相同格式字符串格式化的一组参数，然后使用 sep 连接的常见情况。sep 也会通过 conditional_escape() 传递。

args_generator 应该是一个迭代器，它返回将传递给 format_html() 的 args 序列。例如

format_html_join("\n", "<li>{} {}</li>", ((u.first_name, u.last_name) for u in users))

json_script(value, element_id=None, encoder=None)[source]¶

使用其 Unicode 转义字符转义所有 HTML/XML 特殊字符，因此 value 可安全用于 JavaScript。还将转义后的 JSON 包裹在 <script> 标记中。如果 element_id 参数不是 None，则 <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 序列化。

strip_tags(value)[source]¶

尝试从字符串中删除任何看起来像 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_safe()[source]¶

类上的 __html__() 方法可以帮助非 Django 模板检测其输出不需要 HTML 转义的类。

此装饰器通过将 __str__() 包裹在 mark_safe() 中来定义装饰类上的 __html__() 方法。确保 __str__() 方法确实返回不需要 HTML 转义的文本。

django.utils.http¶

urlencode(query, doseq=False)[source]¶

Python 的 urllib.parse.urlencode() 函数的一个版本，它可以对 MultiValueDict 和非字符串值进行操作。

http_date(epoch_seconds=None)[source]¶

将时间格式化为与 HTTP RFC 9110 第 5.6.7 节 指定的 RFC 1123 第 5.2.14 节 日期格式相匹配。

接受以秒为单位表示的浮点数（以 UTC 为单位），例如 time.time() 输出的浮点数。如果设置为 None，则默认为当前时间。

输出格式为 Wdy, DD Mon YYYY HH:MM:SS GMT 的字符串。

content_disposition_header(as_attachment, filename)[source]¶

根据给定的filename和RFC 6266规范，构建一个Content-Disposition HTTP 头部值。如果as_attachment为False且filename为None，则返回None；否则返回一个适合Content-Disposition HTTP 头部的字符串。

base36_to_int(s)[source]¶

将一个36进制字符串转换为整数。

int_to_base36(i)[source]¶

将一个正整数转换为36进制字符串。

urlsafe_base64_encode(s)[source]¶

将字节字符串编码为URL安全的base64字符串，去除任何尾部的等号。

urlsafe_base64_decode(s)[source]¶

解码base64编码的字符串，并添加回可能被去除的任何尾部的等号。

django.utils.module_loading¶

用于处理Python模块的函数。

import_string(dotted_path)[source]¶

导入一个点分隔的模块路径，并返回路径中最后一个名称指定的属性/类。如果导入失败，则引发ImportError。例如

from django.utils.module_loading import import_string

ValidationError = import_string("django.core.exceptions.ValidationError")

等价于

from django.core.exceptions import ValidationError

django.utils.safestring¶

用于处理“安全字符串”的函数和类：“安全字符串”是指可以在HTML中安全显示而无需进一步转义的字符串。将某些内容标记为“安全字符串”意味着字符串的生成者已经将不应该被HTML引擎解释的字符（例如‘<’）转换为相应的实体。

class SafeString[source]¶

一个str的子类，它已被专门标记为“安全”（无需进一步转义）用于HTML输出目的。

mark_safe(s)[source]¶

显式地将字符串标记为（HTML）输出目的的安全字符串。返回的对象可以在任何需要字符串的地方使用。

可以对同一个字符串多次调用。

也可以用作装饰器。

对于构建HTML片段，通常应该使用django.utils.html.format_html()。

如果被修改，标记为安全的字符串将再次变为不安全。例如

>>> 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¶

format_lazy(format_string, *args, **kwargs)¶

当format_string、args和/或kwargs包含延迟对象时，str.format()的一个版本。第一个参数是要格式化的字符串。例如

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/。

slugify(value, allow_unicode=False)[source]¶

通过以下步骤将字符串转换为URL slug：

1. 如果allow_unicode为False（默认值），则转换为ASCII。

2. 转换为小写。

3. 删除不是字母数字、下划线、连字符或空格的字符。

4. 将任何空格或重复的连字符替换为单个连字符。

5. 删除开头和结尾的空格、连字符和下划线。

例如

>>> slugify(" Joel is a slug ")
'joel-is-a-slug'

如果要允许Unicode字符，请传递allow_unicode=True。例如

>>> slugify("你好 World", allow_unicode=True)
'你好-world'

django.utils.timezone¶

get_fixed_timezone(offset)[source]¶

返回一个tzinfo实例，表示相对于UTC具有固定偏移量的时间区域。

offset是一个datetime.timedelta或一个整数分钟数。对于UTC以东的时间区域，使用正值；对于UTC以西的时间区域，使用负值。

get_default_timezone()[source]¶

返回一个tzinfo实例，表示默认时区。

get_default_timezone_name()[source]¶

返回默认时区的名称。

get_current_timezone()[source]¶

返回一个tzinfo实例，表示当前时区。

get_current_timezone_name()[source]¶

返回当前时区的名称。

activate(timezone)[source]¶

设置当前时区。timezone参数必须是tzinfo子类的实例或时区名称。

deactivate()[source]¶

取消设置当前时区。

override(timezone)[source]¶

这是一个Python上下文管理器，它使用activate()在进入时设置当前时区，并在退出时恢复先前激活的时区。如果timezone参数为None，则改用deactivate()在进入时取消设置当前时区。

override也可以用作函数装饰器。

localtime(value=None, timezone=None)[source]¶

将一个带时区的 datetime 对象转换为不同的时区，默认为 当前时区。

当省略 value 时，默认为 now()。

此函数不适用于无时区的日期时间；请改用 make_aware()。

localdate(value=None, timezone=None)[source]¶

使用 localtime() 将一个带时区的 datetime 对象转换为不同时区中的 date() 对象，默认为 当前时区。

当省略 value 时，默认为 now()。

此函数不适用于无时区的日期时间。

now()[source]¶

返回一个表示当前时间的 datetime 对象。返回的具体内容取决于 USE_TZ 的值。

• 如果 USE_TZ 为 False，则返回一个 无时区 的日期时间对象（即没有关联时区的日期时间），表示系统本地时区的当前时间。

• 如果 USE_TZ 为 True，则返回一个 带时区 的日期时间对象，表示 UTC 中的当前时间。请注意，无论 TIME_ZONE 的值如何，now() 始终返回 UTC 时间；可以使用 localtime() 获取当前时区的时间。

is_aware(value)[source]¶

如果 value 带时区，则返回 True，如果无时区，则返回 False。此函数假设 value 是一个 datetime 对象。

is_naive(value)[source]¶

如果 value 无时区，则返回 True，如果带时区，则返回 False。此函数假设 value 是一个 datetime 对象。

make_aware(value, timezone=None)[source]¶

返回一个带时区的 datetime 对象，该对象在 timezone 中表示与 value 相同的时间点，value 是一个无时区的 datetime 对象。如果 timezone 设置为 None，则默认为 当前时区。

make_naive(value, timezone=None)[source]¶

返回一个无时区的 datetime 对象，该对象在 timezone 中表示与 value 相同的时间点，value 是一个带时区的 datetime 对象。如果 timezone 设置为 None，则默认为 当前时区。

django.utils.translation¶

有关以下内容的完整讨论，请参阅 翻译文档。

gettext(message)[source]¶

翻译 message 并将其作为字符串返回。

pgettext(context, message)[source]¶

在给定 context 的情况下翻译 message 并将其作为字符串返回。

有关更多信息，请参阅 上下文标记。