Django 实用工具

本文档涵盖 django.utils 中所有稳定的模块。django.utils 中的大多数模块都设计为供内部使用，并且只有以下部分可以被视为稳定，因此根据 内部发布弃用政策 向后兼容。

django.utils.cache

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

有关 Vary 标头的详细信息，请参阅 RFC 9110#section-12.5.5。

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

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

patch_cache_control(response, **kwargs)

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

  • 所有关键字参数名称都变为小写，下划线转换为连字符。
  • 如果参数的值为 True（确切为 True，而不仅仅是真值），则仅将参数名称添加到标题。
  • 对所有其他参数应用 str() 后，将它们与各自的值一起添加。
get_max_age(response)

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

patch_response_headers(response, cache_timeout=None)

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

  • Expires
  • Cache-Control

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

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

add_never_cache_headers(response)

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

向响应添加 Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private 标头，以表明永远不应缓存页面。

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

patch_vary_headers(response, newheaders)

在给定的 HttpResponse 对象中添加（或更新）Vary 头部。 newheaders 是应包含在 Vary 中的头部名称列表。如果头部包含星号，则根据 RFC 9110#section-12.5.5，Vary 头部将由单个星号 '*' 组成。否则，不会移除 Vary 中的现有头部。

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

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

如果没有存储头部列表，则需要重建页面，因此此函数返回 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 描述了一个 UTC 偏移，结果为 None。

parse_datetime(value)

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

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

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

django.utils.decorators

method_decorator(decorator, name='')[源代码]

将函数装饰器转换为方法装饰器。它可用于装饰方法或类；在后一种情况下，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 类似，但返回一个接受要传递给 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)[source]

将中间件标记为 仅同步。（Django 中的默认值，但如果默认值在将来的版本中发生更改，这将使您能够防患于未然。）

async_only_middleware(middleware)[源代码]

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

sync_and_async_middleware(middleware)[源代码]

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

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，则不转换（某些）非字符串对象。

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 字符串。

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

向 feed 添加一项。除 pubdate 和 updateddate（它们是 datetime.datetime 对象）以及 enclosures（它是 Enclosure 实例的列表）外，所有参数都应为字符串。

num_items()
root_attributes()

返回要放置在根（即 feed/channel）元素上的额外属性。从 write() 调用。

add_root_elements(handler)

在根（即 feed/channel）元素中添加元素。从 write() 调用。

item_attributes(item)

返回要放置在每个项目（即项目/条目）元素上的额外属性。

add_item_elements(handler, item)

在每个项目（即项目/条目）元素上添加元素。

write(outfile, encoding)

以给定的编码将 feed 输出到 outfile，它是一个类似于文件的对象。子类应重写此方法。

writeString(encoding)

以给定的编码将 feed 作为字符串返回。

latest_post_date()

返回 feed 中所有项目的最新 pubdate 或 updateddate。如果任何项目都没有这些属性，则返回当前 UTC 日期/时间。

附件

类 附件

表示 RSS 附件

RssFeed

类 RssFeed(SyndicationFeed)

Rss201rev2Feed

类 Rss201rev2Feed(RssFeed)

规范：https://cyber.harvard.edu/rss/rss.html

RssUserland091Feed

类 RssUserland091Feed(RssFeed)

规范：http://backend.userland.com/rss091

Atom1Feed

类 Atom1Feed(SyndicationFeed)

规范：RFC 4287

django.utils.functional

类 cached_property(func)[源代码]

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

返回给定文本，其中对 HTML 中使用的和号、引号和尖括号进行编码。首先将输入强制转换为字符串，然后对输出应用 mark_safe()。

conditional_escape(text)

类似于 escape()，但它不适用于预转义字符串，因此不会进行双重转义。

format_html(format_string, *args, **kwargs)

这类似于 str.format()，但它适用于构建 HTML 片段。第一个参数 format_string 不转义，但所有其他参数和关键字参数都通过 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() 传递，而 conditional_escape()（最终）对这些值调用 force_str()。

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

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))
json_script(value, element_id=None, encoder=None)

使用它们的 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 序列化。

在 Django 4.2 中更改

添加了 encoder 参数。

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

如果您正在寻找更健壮的解决方案，请考虑使用第三方 HTML 清理工具。

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)[源代码]

根据 HTTP RFC 9110#section-5.6.7 指定的 RFC 1123#section-5.2.14 日期格式设置时间。

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

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

content_disposition_header(as_attachment, filename)[源代码]
Django 4.2 中的新增功能。

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

base36_to_int(s)[source]

将 base 36 字符串转换为整数。

int_to_base36(i)[source]

将正整数转换为 base 36 字符串。

urlsafe_base64_encode(s)[source]

对字节串进行编码，以供在 URL 中使用，剥离任何尾随等号。

urlsafe_base64_decode(s)[source]

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

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

slugify(value, allow_unicode=False)

通过以下方式将字符串转换为 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)

返回一个 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，表示当前时间点。返回的内容具体取决于 USE_TZ 的值

  • 如果 USE_TZ 为 False，这将是一个 朴素 日期时间（即没有关联时区的日期时间），表示系统本地时区中的当前时间。
  • 如果 USE_TZ 为 True，这将成为一个 感知 日期时间，表示 UTC 中的当前时间。请注意，无论 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)

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

make_naive(value, timezone=None)

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

django.utils.translation

有关以下内容用法完整说明，请参阅翻译文档。

gettext(message)

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

pgettext(context, message)

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

有关详细信息，请参阅上下文标记。

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，看其路径是否以 LANGUAGES 设置中列出的语言代码开头。

get_supported_language_variant(lang_code, strict=False)

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

lang_code 的最大接受长度为 500 个字符。如果 lang_code 超过此限制且 strict 为 True，或者如果不存在通用变体且 strict 为 False，则会引发 ValueError。

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

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

在 Django 4.2.14 中更改

在较旧版本中，长度超过 500 个字符的 lang_code 值会在不引发 ValueError 的情况下进行处理。

to_locale(language)

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

templatize(src)

将 Django 模板转换为 xgettext 可以理解的内容。它通过将 Django 翻译标记转换为标准 gettext 函数调用来实现此目的。

django.urls URLconf 中使用的函数
验证器
返回顶部