Django 实用程序

本文档涵盖了 django.utils 中的所有稳定模块。 django.utils 中的大部分模块都是为内部使用而设计的，只有以下部分可以被认为是稳定的，因此根据内部版本弃用政策向后兼容。

django.utils.cache

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

有关 Vary 标头的信息，请参阅 RFC 7231#section-7.1.4。

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

例如，internationalization 中间件需要通过 Accept-language 标头来区分缓存。

patch_cache_control(response, **kwargs)

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

所有关键字参数名称都转为小写，下划线转为连字符。
如果参数的值是 True（正好是 True，而不仅仅是一个真值），则只会将参数名称添加到标题中。
在对其应用 str() 后，所有其他参数都将与其值相加。

3.1 版更改：添加了对 no-cache 指令中的多个字段名称的支持。

get_max_age(response): 将响应 Cache-Control 标头中的 max-age 作为整数返回（如果未找到或不是整数，则返回 None）。

patch_response_headers(response, cache_timeout=None)

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

Expires
Cache-Control

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

cache_timeout 以秒为单位。默认使用 :setting:`CACHE_MIDDLEWARE_SECONDS` 设置。

add_never_cache_headers(response): 将 Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private 标头添加到响应以指示不应缓存页面。

patch_vary_headers(response, newheaders): 在给定的 HttpResponse 对象中添加（或更新）Vary 标头。 newheaders 是应该在 Vary 中的头名称列表。如果标头包含星号，则根据 RFC 7231#section-7.1.4，Vary 标头将由单个星号 '*' 组成。否则，不会删除 Vary 中的现有标头。

get_cache_key(request, key_prefix=None, method='GET', cache=None)

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

如果没有存储headerlist，则需要重建页面，因此该函数返回None。

learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None)

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

用于生成缓存键的标头列表与页面本身存储在同一缓存中。如果缓存老化了缓存中的一些数据，这意味着我们必须构建一次响应以获取 Vary 标头，因此在用于缓存键的标头列表中。

django.utils.dateparse

此模块中定义的函数共享以下属性：

它们接受 ISO 8601 日期/时间格式（或一些接近的替代格式）的字符串，并从 Python 的 datetime 模块中的相应类返回对象。
如果他们的输入格式正确但不是有效的日期或时间，他们会引发 ValueError。
如果格式不正确，它们将返回 None。
他们在输入中接受高达皮秒的分辨率，但他们将其截断为微秒，因为这是 Python 支持的。

parse_date(value): 解析字符串并返回 datetime.date。

parse_time(value)

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

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

3.1 版更改：添加了对毫秒逗号分隔符的支持。

parse_datetime(value)

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

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

3.1 版更改：添加了对毫秒逗号分隔符的支持。

parse_duration(value)

解析字符串并返回 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）。

3.1 版更改：添加了对 ISO 8601 格式和格式 "DD HH:MM:SS,uuuuuu" 中小数的逗号分隔符的支持。

django.utils.decorators

method_decorator(decorator, name=)

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

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

有关示例用法，请参阅基于类的装饰视图。

decorator_from_middleware(middleware_class)

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

它假定中间件与旧样式的 Django 1.9 及更早版本兼容（具有 process_request()、process_exception() 和 process_response() 等方法）。

decorator_from_middleware_with_args(middleware_class)

类似于 decorator_from_middleware，但返回一个函数，该函数接受要传递给 middleware_class 的参数。例如， cache_page() 装饰器是从 CacheMiddleware 创建的，如下所示：

cache_page = decorator_from_middleware_with_args(CacheMiddleware)

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

sync_only_middleware(middleware): 3.1 版中的新功能。

将中间件标记为仅同步。（Django 中的默认设置，但是如果未来版本中的默认设置发生变化，这允许您面向未来。）

async_only_middleware(middleware): 3.1 版中的新功能。

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

sync_and_async_middleware(middleware): 3.1 版中的新功能。

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

django.utils.encoding

smart_str(s, encoding='utf-8', strings_only=False, errors='strict')

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

如果 strings_only 是 True，不要转换（一些）非字符串对象。

is_protected_type(obj)

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

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

force_str(s, encoding='utf-8', strings_only=False, errors='strict')

类似于 smart_str()，除了惰性实例被解析为字符串，而不是作为惰性对象保存。

如果 strings_only 是 True，不要转换（一些）非字符串对象。

smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')

返回任意对象 s 的字节串版本，按照 encoding 中的规定进行编码。

如果 strings_only 是 True，不要转换（一些）非字符串对象。

force_bytes(s, encoding='utf-8', strings_only=False, errors='strict')

类似于 smart_bytes，除了惰性实例被解析为字节串，而不是作为惰性对象保存。

如果 strings_only 是 True，不要转换（一些）非字符串对象。

smart_text(s, encoding='utf-8', strings_only=False, errors='strict'): 自 3.0 版起已弃用。

force_str() 的别名用于向后兼容，尤其是在支持 Python 2 的代码中。

force_text(s, encoding='utf-8', strings_only=False, errors='strict'): 自 3.0 版起已弃用。

force_str() 的别名用于向后兼容，尤其是在支持 Python 2 的代码中。

iri_to_uri(iri)

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

这是 RFC 3987#section-3.1 第 3.1 节中的算法，稍微简化了一点，因为假设输入是字符串而不是任意字节流。

采用 IRI（字符串或 UTF-8 字节）并返回包含编码结果的字符串。

uri_to_iri(uri)

将统一资源标识符转换为国际化资源标识符。

这是 RFC 3987#section-3.2 第 3.2 节中的算法。

采用 ASCII 字节形式的 URI 并返回包含编码结果的字符串。

filepath_to_uri(path)

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

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

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

3.1 版更改：添加了对 pathlib.Path path 的支持。

escape_uri_path(path): 从统一资源标识符 (URI) 的路径部分转义不安全字符。

django.utils.feedgenerator

示例用法：

>>> from django.utils import feedgenerator
>>> feed = feedgenerator.Rss201rev2Feed(
...     title="Poynter E-Media Tidbits",
...     link="http://www.poynter.org/column.asp?id=31",
...     description="A group Weblog by the sharpest minds in online media/journalism/publishing.",
...     language="en",
... )
>>> feed.add_item(
...     title="Hello",
...     link="http://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)

创建一个 TagURI。

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

SyndicationFeed

class SyndicationFeed

所有联合提要的基类。子类应该提供 write()。

__init__(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)

使用给定的元数据字典初始化提要，该字典适用于整个提要。

您传递给 __init__ 的任何额外关键字参数都将存储在 self.feed 中。

所有参数都应该是字符串，除了 categories，它应该是一个字符串序列。

add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs): 将项目添加到提要。除了 pubdate 和 updateddate（它们是 datetime.datetime 对象）和 enclosures（是 Enclosure 的列表）之外的所有参数都应该是字符串] 实例。

num_items()

root_attributes(): 返回额外的属性以放置在根上（即馈送/通道）元素。从 write() 调用。

add_root_elements(handler): 在根中添加元素（即馈送/通道）元素。从 write() 调用。

item_attributes(item): 返回额外的属性以放置在每个项目上（即项目/条目）元素。

add_item_elements(handler, item): 在每个项目上添加元素（即项目/条目）元素。

write(outfile, encoding): 将给定编码的提要输出到 outfile，这是一个类似文件的对象。子类应该覆盖它。

writeString(encoding): 以字符串形式返回给定编码中的提要。

latest_post_date(): 为提要中的所有项目返回最新的 pubdate 或 updateddate。如果没有项目具有这些属性中的任何一个，则返回当前的 UTC 日期/时间。

Enclosure

class Enclosure: 代表一个 RSS 附件

RssFeed

class RssFeed(SyndicationFeed)

Rss201rev2Feed

class Rss201rev2Feed(RssFeed): 规格：https://cyber.harvard.edu/rss/rss.html

RssUserland091Feed

class RssUserland091Feed(RssFeed): 规格：http://backend.userland.com/rss091

Atom1Feed

class Atom1Feed(SyndicationFeed): 规格：RFC 4287

django.utils.functional

class cached_property(func, name=None)

@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）会引发 [ X142X]。

除了提供潜在的性能优势外，@cached_property 还可以确保属性值在实例的整个生命周期内不会发生意外更改。这可能发生在计算基于 datetime.now() 的方法中，或者如果某个其他进程在同一实例上的方法的后续调用之间的短暂间隔内将更改保存到数据库中。

您可以创建方法的缓存属性。例如，如果您有一个昂贵的 get_friends() 方法并希望允许在不检索缓存值的情况下调用它，您可以编写：

friends = cached_property(get_friends, name='friends')

你只需要name Python < 3.6 支持的参数。

虽然 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): 3.1 版中的新功能。

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

keep_lazy(func, *resultclasses)

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

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

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

例如：

from django.utils.functional import keep_lazy, keep_lazy_text

def fancy_utility_function(s, ...):
    # 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, ...):
    ...

keep_lazy() 装饰器接受许多额外的参数 (*args)，指定原始函数可以返回的类型。一个常见的用例是具有返回文本的函数。对于这些，您可以将 str 类型传递给 keep_lazy（或使用下一节中描述的 keep_lazy_text() 装饰器）。

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

keep_lazy_text(func)

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, ...):
    ...

# Which can be rewritten as:
@keep_lazy_text
def fancy_utility_function(s, ...):
    ...

django.utils.html

通常您应该使用 Django 的模板构建 HTML 以利用其自动转义机制，在适当的地方使用 django.utils.safestring 中的实用程序。该模块为转义 HTML 提供了一些额外的低级实用程序。

escape(text): 返回带有 & 符号、引号和尖括号的给定文本，这些文本经过编码以在 HTML 中使用。输入首先被强制为一个字符串，输出应用了 mark_safe()。

conditional_escape(text): 与escape()类似，只是它不对预转义的字符串进行操作，因此不会双重转义。

format_html(format_string, *args, **kwargs)

这类似于 str.format()，不同之处在于它适用于构建 HTML 片段。所有 args 和 kwargs 在传递给 str.format() 之前都通过 conditional_escape()。

对于构建小的 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()。

format_html_join(sep, format_string, args_generator)

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

strip_tags(value)

尝试从字符串中删除任何看起来像 HTML 标记的内容，即包含在 <> 中的任何内容。

绝对不保证结果字符串是 HTML 安全的。所以永远不要在没有先转义的情况下将 strip_tag 调用的结果标记为安全，例如使用 escape()。

例如：

strip_tags(value)

如果 value 为 "<b>Joel</b> <button>is</button> a <span>slug</span>"，则返回值将为 "Joel is a slug"。

如果您正在寻找更强大的解决方案，请查看 bleach Python 库。

html_safe()

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

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

django.utils.http

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

http_date(epoch_seconds=None)

格式化时间以匹配 RFC 1123#section-5.2.14 日期格式，如 HTTP RFC 7231#section-7.1.1.1[ X142X]。

接受自 UTC 纪元以来以秒表示的浮点数 - 例如由 time.time() 输出的数字。如果设置为 None，则默认为当前时间。

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

base36_to_int(s): 将基数为 36 的字符串转换为整数。

int_to_base36(i): 将正整数转换为基数为 36 的字符串。

urlsafe_base64_encode(s): 将字节字符串编码为用于 URL 的 base64 字符串，去除任何尾随等号。

urlsafe_base64_decode(s): 解码 base64 编码的字符串，添加回任何可能已被剥离的尾随等号。

django.utils.module_loading

用于处理 Python 模块的函数。

import_string(dotted_path)

导入虚线模块路径并返回路径中姓氏指定的属性/类。如果导入失败，则引发 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: 一个 str 子类，已被专门标记为“安全”（不需要进一步转义）以用于 HTML 输出目的。

mark_safe(s)

为 (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)

通过以下方式将字符串转换为 URL slug：

如果 allow_unicode 是 False（默认值），则转换为 ASCII。
转换为小写。
删除不是字母数字、下划线、连字符或空格的字符。
用单个破折号替换任何空格或重复的破折号。
删除前导和尾随空格、破折号和下划线。

例如：

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

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

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

3.2 版更改：在旧版本中，未删除前导和尾随的破折号和下划线。

django.utils.timezone

utc: tzinfo 代表 UTC 的实例。

get_fixed_timezone(offset)

返回一个 tzinfo 实例，该实例表示与 UTC 具有固定偏移量的时区。

offset 是 datetime.timedelta 或整数分钟。 UTC 以东的时区使用正值，UTC 以西的时区使用负值。

get_default_timezone(): 返回表示默认时区的 tzinfo 实例。

get_default_timezone_name(): 返回默认时区的名称。

get_current_timezone(): 返回表示当前时区的 tzinfo 实例。

get_current_timezone_name(): 返回当前时区的名称。

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

deactivate(): 取消设置当前时区。

override(timezone)

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

override 也可用作函数装饰器。

localtime(value=None, timezone=None)

将可感知的 datetime 转换为不同的时区，默认情况下为当前时区。

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

此功能不适用于幼稚的日期时间；改用 make_aware()。

localdate(value=None, timezone=None)

使用 localtime() 将有意识的 datetime 转换为不同时区的 date()，默认为当前时区。

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

此功能不适用于幼稚的日期时间。

now(): 返回表示当前时间点的 datetime。返回的确切内容取决于 :setting:`USE_TZ` 的值：

如果 :setting:`USE_TZ` 是 False，这将是一个 naive 日期时间（即没有关联时区的日期时间）表示系统本地时区中的当前时间。 如果 :setting:`USE_TZ` 是 True，这将是一个 aware 日期时间，表示 UTC 中的当前时间。请注意，无论 :setting:`TIME_ZONE`; 的值如何，now() 将始终以 UTC 返回时间。您可以使用 localtime() 获取当前时区的时间。

is_aware(value): 如果 value 知道，则返回 True，如果它是幼稚的，则返回 False。此函数假设 value 是 datetime。

is_naive(value): 如果 value 是幼稚的，则返回 True，如果知道，则返回 False。此函数假设 value 是 datetime。

make_aware(value, timezone=None, is_dst=None)

返回一个有意识的 datetime，它代表与 timezone 中的 value 相同的时间点，value 是一个朴素的 datetime。如果timezone设置为None，则默认为当前时区。

使用 pytz 时，如果您在 DST 转换期间尝试使 value 意识到同一时间发生两次（从 DST 恢复时），则会引发 pytz.AmbiguousTimeError 异常。将 is_dst 设置为 True 或 False 将分别通过选择时间是过渡前还是过渡后来避免异常。

使用 pytz 时，如果您尝试在 DST 转换期间使 value 意识到该时间，则会引发 pytz.NonExistentTimeError 异常，以便该时间从未发生。例如，如果在 DST 转换期间跳过 2:00 小时，则尝试使该时区中的 2:30 知道将引发异常。为避免这种情况，您可以使用 is_dst 指定 make_aware() 应如何解释这种不存在的时间。如果 is_dst=True 则上述时间将被解释为夏令时 2:30（相当于当地时间 1:30）。相反，如果 is_dst=False 时间将被解释为 2:30 标准时间（相当于当地时间 3:30）。

is_dst 参数在使用非 pytz 时区实现时无效。

make_naive(value, timezone=None): 返回一个朴素的 datetime，它在 timezone 中表示与 value、value 相同的时间点是一个有意识的 datetime。如果timezone设置为None，则默认为当前时区。

django.utils.translation

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

gettext(message): 翻译 message 并将其作为字符串返回。

pgettext(context, message)

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

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

gettext_lazy(message)

pgettext_lazy(context, message)

与上面的非惰性版本相同，但使用惰性执行。

请参阅延迟翻译文档。

gettext_noop(message): 标记要翻译的字符串，但现在不翻译它们。这可用于将字符串存储在应保留在基本语言中的全局变量中（因为它们可能在外部使用）并且稍后将被翻译。

ngettext(singular, plural, number): 翻译 singular 和 plural 并基于 number 返回适当的字符串。

npgettext(context, singular, plural, number): 翻译 singular 和 plural，并根据 number 和 context 返回适当的字符串。

ngettext_lazy(singular, plural, number)

npgettext_lazy(context, singular, plural, number)

与上面的非惰性版本相同，但使用惰性执行。

请参阅延迟翻译文档。

activate(language): 获取给定语言的翻译对象并将其激活为当前线程的当前翻译对象。

deactivate(): 停用当前活动的翻译对象，以便进一步的 _ 调用将再次针对默认翻译对象进行解析。

deactivate_all(): 使活动平移对象成为 NullTranslations() 实例。当我们出于某种原因希望延迟翻译显示为原始字符串时，这很有用。

override(language, deactivate=False)

一个 Python 上下文管理器，它使用 django.utils.translation.activate() 获取给定语言的翻译对象，将其激活为当前线程的翻译对象，并在退出时重新激活以前的活动语言。或者，如果 deactivate 参数是 True，它可以在退出时使用 django.utils.translation.deactivate() 停用临时翻译。如果您将 None 作为语言参数传递，则会在上下文中激活 NullTranslations() 实例。

override 也可用作函数装饰器。

check_for_language(lang_code): 检查是否存在给定语言代码的全局语言文件（例如 'fr'、'pt_BR'）。这用于确定用户提供的语言是否可用。

get_language(): 返回当前选择的语言代码。如果翻译被暂时停用（通过 deactivate_all() 或当 None 传递给 override()），则返回 None。

get_language_bidi(): 返回所选语言的 BiDi 布局：

False = 从左到右布局 True = 从右到左布局

get_language_from_request(request, check_path=False)

分析请求以查找用户希望系统显示的语言。仅考虑 settings.LANGUAGES 中列出的语言。如果用户请求我们有主要语言的子语言，我们会发送主要语言。

如果 check_path 是 True，该函数首先检查请求的 URL 的路径是否以 :setting:`LANGUAGES` 设置中列出的语言代码开头。

get_supported_language_variant(lang_code, strict=False)

如果在 :setting:`LANGUAGES` 设置中，则返回 lang_code，可能选择更通用的变体。例如，如果 lang_code 为 'es-ar' 且 'es' 在 :setting:`LANGUAGES` 但 'es-ar' 不是。

如果 strict 是 False（默认值），则在找不到语言代码或其通用变体时，可能会返回特定于国家/地区的变体。例如，如果只有 'es-co' 在 :setting:`LANGUAGES` 中，则为 lang_code 返回，如 'es' 和 'es-ar' . 如果 strict=True，则不会返回这些匹配项。

如果未找到任何内容，则引发 LookupError。

to_locale(language): 将语言名称 (en-us) 转换为区域设置名称 (en_US)。

templatize(src): 将 Django 模板转换为 xgettext 可以理解的内容。它通过将 Django 翻译标签翻译成标准的 gettext 函数调用来实现。

LANGUAGE_SESSION_KEY: 存储当前会话的活动语言的会话密钥。

自 3.0 版起已弃用：该语言不会存储在 Django 4.0 的会话中。改用 :setting:`LANGUAGE_COOKIE_NAME` cookie。

Django Utils — Django 文档

目录

Django 实用程序

django.utils.cache

django.utils.dateparse

django.utils.decorators

django.utils.encoding

django.utils.feedgenerator

SyndicationFeed

Enclosure

RssFeed

Rss201rev2Feed

RssUserland091Feed

Atom1Feed

django.utils.functional

django.utils.html

django.utils.http

django.utils.module_loading

django.utils.safestring

django.utils.text

django.utils.timezone

django.utils.translation