Skip to main content

Django Utils

本文档涵盖了 django.utils 中的所有稳定模块。 django.utils 中的大多数模块是为内部使用而设计的,只有以下部分才能被视为稳定,从而根据 内部释放弃用策略 向后兼容。

django.utils.cache

此模块包含用于控制缓存的帮助函数。它通过管理响应的 Vary 头来这样做。它包括直接修补响应对象的头部的函数和修改函数的修饰器来做自己的头部修补。

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

基本上,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 对象添加一些有用的标题:

  • ETag

  • Last-Modified

  • Expires

  • Cache-Control

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

cache_timeout 在几秒钟内。默认情况下使用 CACHE_MIDDLEWARE_SECONDS 设置。

add_never_cache_headers(response)

向响应中添加 Cache-Control: max-age=0, no-cache, no-store, must-revalidate 头以指示不应缓存页面。

Changed in Django 1.8.8:

在旧版本中,Cache-Control: max-age=0 已发送。这没有可靠地防止所有浏览器中的缓存。

patch_vary_headers(response, newheaders)

在给定的 HttpResponse 对象中添加(或更新) Vary 头。 newheaders 是应该在 Vary 中的报头名称的列表。不删除 Vary 中的现有标题。

get_cache_key(request, key_prefix=None)

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

如果没有存储的头文件,页面需要重建,所以此函数返回 None

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

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

用于缓存密钥生成的头的列表存储在与页本身相同的缓存中。如果缓存将一些数据从缓存中老化,这只是意味着我们必须构建响应一次以获得Vary头,因此在用于缓存键的头列表中。

django.utils.dateparse

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

  • 如果他们的输入格式正确,但不是有效的日期或时间,他们提出 ValueError

  • 如果它没有很好地格式化,他们返回 None

  • 它们在输入中接受高达picosecond的分辨率,但是它们截断到微秒级,因为这是Python支持的。

parse_date(value)[源代码]

解析字符串并返回 datetime.date

parse_time(value)[源代码]

解析字符串并返回 datetime.time

不支持UTC偏移;如果 value 描述一个,结果是 None

parse_datetime(value)[源代码]

解析字符串并返回 datetime.datetime

支持UTC偏移;如果 value 描述一个,则结果 tzinfo 属性是 FixedOffset 实例。

parse_duration(value)[源代码]

解析字符串并返回 datetime.timedelta

预期格式为 "DD HH:MM:SS.uuuuuu" 或ISO 8601规定的数据(例如,等效于 4 1:15:20P4DT1H15M20S)。

django.utils.decorators

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

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

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

有关使用示例,请参阅 装饰类的视图

Changed in Django 1.9:

添加了装饰类的能力,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

django.utils.encoding

python_2_unicode_compatible()[源代码]

一个装饰器,在Python 2下定义 __unicode____str__ 方法。在Python 3下,它什么都不做。

要使用单个代码库支持Python 2和3,请定义返回文本的 __str__ 方法,并将此装饰器应用于类。

smart_text(s, encoding='utf-8', strings_only=False, errors='strict')[源代码]

返回表示 s - unicode 在Python 2和 str 在Python 3上的文本对象。使用 encoding 编解码器处理bytestrings。

如果 strings_onlyTrue,不转换(一些)非字符串对象。

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

smart_text() 的历史名称。仅在Python 2下可用。

is_protected_type(obj)[源代码]

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

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

force_text(s, encoding='utf-8', strings_only=False, errors='strict')[源代码]

类似于 smart_text,除了惰性实例被解析为字符串,而不是保持为惰性对象。

如果 strings_onlyTrue,不转换(一些)非字符串对象。

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

force_text() 的历史名称。仅在Python 2下可用。

smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')[源代码]

返回 s 的按测试版本,按 encoding 中的指定进行编码。

如果 strings_onlyTrue,不转换(一些)非字符串对象。

force_bytes(s, encoding='utf-8', strings_only=False, errors='strict')[源代码]

类似于 smart_bytes,除了惰性实例被解析为bytestrings,而不是保持为惰性对象。

如果 strings_onlyTrue,不转换(一些)非字符串对象。

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

smart_bytes() 在Python 2上的别名和 smart_text() 在Python 3上。此函数返回 str 或惰性字符串。

例如,这适合于在Python 2和3上写入 sys.stdout

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

force_bytes() 在Python 2上的别名和 force_text() 在Python 3上。此函数总是返回 str

iri_to_uri(iri)[源代码]

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

这是 RFC 3987#section-3.1 第3.1节的算法。然而,由于我们假设输入是UTF-8或unicode已经,我们可以简化一些东西从完整的方法。

采用UTF-8字节的IRI,并返回包含编码结果的ASCII字节。

uri_to_iri(uri)[源代码]

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

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

获取ASCII字节的URI,并返回包含编码结果的Unicode字符串。

filepath_to_uri(path)[源代码]

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

此方法将对通常被识别为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 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')

为了简化发电机的选择,使用当前为 Rss201rev2Feedfeedgenerator.DefaultFeed

有关不同版本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)[源代码]

使用给定的元数据字典初始化Feed,该元数据字典应用于整个Feed。

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

所有参数都应该是Unicode对象,除了 categories,它应该是一个Unicode对象序列。

add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs)[源代码]

向Feed中添加项目。所有参数都应该是除了 pubdateupdateddate (它们是 datetime.datetime 对象)之外的Python unicode 对象,enclosure (它是 Enclosure 实例)和 enclosures (它是 Enclosure 实例的列表)。

1.9 版后已移除: enclosure 关键字参数已被弃用,以支持新的 enclosures 关键字参数,它接受 Enclosure 对象的列表。

num_items()[源代码]
root_attributes()[源代码]

返回要放置在根(即Feed/通道)元素上的额外属性。从 write() 调用。

add_root_elements(handler)[源代码]

在根(即Feed/通道)元素中添加元素。从 write() 调用。

item_attributes(item)[源代码]

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

add_item_elements(handler, item)[源代码]

在每个项目(即项目/条目)元素上添加元素。

write(outfile, encoding)[源代码]

将给定编码中的Feed输出到 outfileoutfile 是类似文件的对象。子类应该覆盖此。

writeString(encoding)[源代码]

以字符串形式返回给定编码中的Feed。

latest_post_date()[源代码]

返回Feed中所有项目的最新 pubdateupdateddate。如果没有项目具有这些属性,则返回当前日期/时间。

Enclosure

class Enclosure[源代码]

表示RSS机箱

RssFeed

class RssFeed(SyndicationFeed)[源代码]

Rss201rev2Feed

class Rss201rev2Feed(RssFeed)[源代码]

规格:https://cyber.law.harvard.edu/rss/rss.html

RssUserland091Feed

class RssUserland091Feed(RssFeed)[源代码]

规格:http://backend.userland.com/rss091

Atom1Feed

class Atom1Feed(SyndicationFeed)[源代码]

规格:https://tools.ietf.org/html/rfc4287

django.utils.functional

class cached_property(object, name)[源代码]

@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 可以避免这一点:

from django.utils.functional import cached_property

@cached_property
def friends(self):
    # expensive computation
    ...
    return friends

注意,由于方法现在是一个属性,在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 可以确保属性的值在实例的生命周期内不会意外更改。这可能发生在计算基于 datetime.now() 的方法,或者简单地如果在同一实例上的方法的后续调用之间的短暂间隔中由一些其他进程将改变保存到数据库。

您可以使用 name 参数来创建其他方法的缓存属性。例如,如果你有一个昂贵的 get_friends() 方法,并希望允许调用它而不检索缓存的值,你可以写:

friends = cached_property(get_friends, name='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
allow_lazy(func, *resultclasses)[源代码]

1.10 版后已移除.

keep_lazy() 一样工作,除了它不能用作装饰器。

keep_lazy(func, *resultclasses)
New in Django 1.10.

Django提供了许多效用函数(特别是在 django.utils 中),它们接受一个字符串作为它们的第一个参数,并对该字符串进行操作。这些函数由模板过滤器使用,也可以直接在其他代码中使用。

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

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

例如:

from django.utils import six
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(six.text_type)(fancy_utility_function)

# Or more succinctly:
@keep_lazy(six.text_type)
def fancy_utility_function(s, ...):
    ...

keep_lazy() 装饰器需要一些额外的参数(*args)来指定原始函数可以返回的类型。一个常见的用例是具有返回文本的函数。对于这些,你可以将 six.text_type 类型传递给 keep_lazy (或者甚至更简单,使用下一节中描述的 keep_lazy_text() 装饰器)。

使用这个装饰器意味着你可以编写你的函数,并假设输入是一个合适的字符串,然后在末尾添加对延迟翻译对象的支持。

keep_lazy_text(func)
New in Django 1.10.

keep_lazy(six.text_type)(func) 的快捷方式。

如果你有一个函数返回文本,并希望能够采取惰性参数,同时延迟他们的评价,只需使用这个装饰:

from django.utils import six
from django.utils.functional import keep_lazy, keep_lazy_text

# Our previous example was:
@keep_lazy(six.text_type)
def fancy_utility_function(s, ...):
    ...

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

django.utils.html

通常你应该使用Django的模板来构建HTML,以利用其autoescape机制,在适当的地方使用 django.utils.safestring 中的实用程序。此模块提供一些额外的低级实用程序用于转义HTML。

escape(text)[源代码]

返回给定文本,并带有用于HTML的带符号,引号和尖括号。输入首先通过 force_text(),输出应用 mark_safe()

conditional_escape(text)[源代码]

escape() 类似,除了它不对预先转义的字符串操作,因此它不会双重转义。

format_html(format_string, *args, **kwargs)[源代码]

这类似于 str.format(),除了它适合构建HTML片段。所有args和kwarg在传递给 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_text()

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"

如果您正在寻找一个更强大的解决方案,请查看 漂白 Python库。

html_safe()[源代码]

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

这个装饰器通过在 mark_safe() 中包装 __unicode__() (Python 2)或 __str__() (Python 3)来在装饰类上定义 __html__() 方法。确保 __unicode__()__str__() 方法确实返回不需要HTML转义的文本。

django.utils.http

urlquote(url, safe='/')[源代码]

Python的 urllib.quote() 函数的版本,可以对unicode字符串进行操作。 url在引用前首先进行UTF-8编码。返回的字符串可以安全地用作后续 iri_to_uri() 调用的参数的一部分,而不会出现双引号。实现延迟执行。

urlquote_plus(url, safe='')[源代码]

Python的urllib.quote_plus()函数的版本,可以对unicode字符串进行操作。 url在引用前首先进行UTF-8编码。返回的字符串可以安全地用作后续 iri_to_uri() 调用的参数的一部分,而不会发生双引号。实现延迟执行。

urlencode(query, doseq=0)[源代码]

一个Python urllib.urlencode()函数的版本,可以对unicode字符串进行操作。参数首先转换为UTF-8编码字符串,然后按照正常编码。

cookie_date(epoch_seconds=None)[源代码]

格式化时间以确保与Netscape的Cookie标准兼容。

接受从UTC中的纪元开始以秒表示的浮点数 - 例如由 time.time() 输出的。如果设置为 None,默认为当前时间。

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

http_date(epoch_seconds=None)[源代码]

格式化与HTTP RFC 7231#section-7.1.1.1 指定的 RFC 1123 日期格式匹配的时间。

接受从UTC中的纪元开始以秒表示的浮点数 - 例如由 time.time() 输出的。如果设置为 None,默认为当前时间。

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

base36_to_int(s)[源代码]

将36个字符串转换为整数。在Python 2上,输出保证是 int,而不是 long

int_to_base36(i)[源代码]

将正整数转换为基本36个字符串。在Python 2 i 必须小于 sys.maxint

urlsafe_base64_encode(s)[源代码]

在base64中编码用于URL的bytestring,剥离任何尾随的等号。

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

已被特别标记为“安全”(不需要进一步转义)的 bytes 子类用于HTML输出目的。

class SafeString

已被特别标记为“安全”(不需要进一步转义)的 str 子类用于HTML输出目的。这是在Python 2的 SafeBytes 和在Python 3的 SafeText

class SafeText[源代码]

str (在Python 3中)或 unicode (在Python 2中)子类,已针对HTML输出目的特别标记为“安全”。

class SafeUnicode

SafeText 的历史名称。仅在Python 2下可用。

mark_safe(s)[源代码]

将字符串显式标记为(HTML)输出目的的安全。返回的对象可以在任何地方使用字符串或unicode对象是合适的。

可以在单个字符串上调用多次。

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

标记为安全的字符串将变得不安全,如果修改。例如:

>>> mystr = '<b>Hello World</b>   '
>>> mystr = mark_safe(mystr)
>>> type(mystr)
<class 'django.utils.safestring.SafeBytes'>

>>> mystr = mystr.strip()  # removing whitespace
>>> type(mystr)
<type 'str'>
mark_for_escaping(s)[源代码]

1.10 版后已移除.

显式地将字符串标记为在输出时需要HTML转义。对 SafeData 子类没有影响。

可以在单个字符串上调用多次(生成的转义仅应用一次)。

django.utils.text

slugify(allow_unicode=False)[源代码]

如果 allow_unicodeFalse (默认),则转换为ASCII。将空格转换为连字符。删除不是字母数字,下划线或连字符的字符。转换为小写。还剥离前导和尾随空格。

例如:

slugify(value)

如果 value"Joel is a slug",输出将是 "joel-is-a-slug"

如果要允许Unicode字符,可以将 allow_unicode 参数设置为 True:

slugify(value, allow_unicode=True)

如果 value"你好 World",输出将是 "你好-world"

Changed in Django 1.9:

添加了 allow_unicode 参数。

django.utils.timezone

utc

表示UTC的 tzinfo 实例。

class FixedOffset(offset=None, name=None)[源代码]

tzinfo 子类建模与UTC的固定偏移。 offset 是UTC以东的整数分钟。

get_fixed_timezone(offset)[源代码]

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

offsetdatetime.timedelta 或整数分钟。在UTC以前的时区使用正值,在UTC以外使用负值。

get_default_timezone()[源代码]

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

get_default_timezone_name()[源代码]

返回 默认时区 的名称。

get_current_timezone()[源代码]

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

get_current_timezone_name()[源代码]

返回 当前时区 的名称。

activate(timezone)[源代码]

设置 当前时区timezone 参数必须是 tzinfo 子类的实例,或者如果 pytz 可用,则为时区名称。

deactivate()[源代码]

取消设置 当前时区

override(timezone)[源代码]

这是一个Python上下文管理器,用于设置 当前时区 在有 activate() 的条目上,并在退出时恢复以前活动的时区。如果 timezone 参数是 None,则 当前时区 将在 deactivate() 条目上取消设置。

override 也可用作函数装饰器。

localtime(value, timezone=None)[源代码]

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

此功能在天真的数据时间不工作;使用 make_aware()

now()[源代码]

返回表示当前时间点的 datetime。具体返回什么取决于 USE_TZ 的值:

  • 如果 USE_TZFalse,则这将是表示系统的本地时区中的当前时间的 幼稚 日期时间(即,没有相关联的时区的日期时间)。

  • 如果 USE_TZTrue,这将是一个表示当前时间的UTC时间的 知道的 datetime。注意,now() 将总是返回UTC中的时间,而不考虑 TIME_ZONE 的值;您可以使用 localtime() 转换为当前时区中的时间。

is_aware(value)[源代码]

返回 True 如果 value 知道,False 如果它是幼稚的。该函数假定 valuedatetime

is_naive(value)[源代码]

如果 value 是原生的,则返回 True,如果知道,返回 False。该函数假定 valuedatetime

make_aware(value, timezone=None, is_dst=None)[源代码]

返回表示与 timezone 中的 value 相同的时间点的感知 datetimevalue 是原始 datetime。如果 timezone 设置为 None,则默认为 当前时区

当安装 pytz 时,如果您尝试在同一时间发生两次(从DST恢复时)的DST转换期间使 value 感知,则会引发异常 pytz.AmbiguousTimeError。将 is_dst 设置为 TrueFalse 将分别通过选择时间是转换前还是转换后来避免异常。

当安装 pytz 时,如果您尝试在DST转换期间使 value 感知,使得时间从未发生(进入DST时),则会引发异常 pytz.NonExistentTimeError。将 is_dst 设置为 TrueFalse 将分别向后或向后移动小时以避免异常。例如,is_dst=True 会将不存在的时间从2:30更改为1:30,is_dst=False 会将时间更改为3:30。

当未安装 pytz 时,is_dst 无效。

Changed in Django 1.9:

添加了 is_dst 参数。

make_naive(value, timezone=None)[源代码]

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

django.utils.translation

有关以下使用的完整讨论,请参阅 翻译文档

gettext(message)[源代码]

翻译 message 并以UTF-8字节形式返回

ugettext(message)[源代码]

翻译 message 并以unicode字符串返回

pgettext(context, message)[源代码]

翻译给定 contextmessage,并以unicode字符串返回它。

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

gettext_lazy(message)
ugettext_lazy(message)
pgettext_lazy(context, message)

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

延迟翻译文档

gettext_noop(message)[源代码]
ugettext_noop(message)

标记要翻译的字符串,但不会立即翻译。这可以用于将字符串存储在应该保持基本语言的全局变量中(因为它们可能在外部使用),并且稍后将进行翻译。

ngettext(singular, plural, number)[源代码]

翻译 singularplural,并在UTF-8字节中返回基于 number 的适当字符串。

ungettext(singular, plural, number)[源代码]

翻译 singularplural,并在unicode字符串中返回基于 number 的相应字符串。

npgettext(context, singular, plural, number)[源代码]

翻译 singularplural,并在unicode字符串中返回基于 numbercontext 的适当字符串。

ngettext_lazy(singular, plural, number)[源代码]
ungettext_lazy(singular, plural, number)[源代码]
npgettext_lazy(context, singular, plural, number)[源代码]

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

延迟翻译文档

string_concat(*strings)

字符串连接的延迟变体,需要从多个部分构建的翻译。

activate(language)[源代码]

获取给定语言的翻译对象,并将其激活为当前线程的当前翻译对象。

deactivate()[源代码]

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

deactivate_all()[源代码]

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

override(language, deactivate=False)[源代码]

一个使用 django.utils.translation.activate() 来获取给定语言的翻译对象的Python上下文管理器将其激活为当前线程的翻译对象,并在退出时重新激活以前的活动语言。可选地,如果 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_pathTrue,则函数首先检查所请求的URL,以确定其路径是否以 LANGUAGES 设置中列出的语言代码开头。

to_locale(language)[源代码]

将语言名称(en-us)转换为语言环境名称(en_US)。

templatize(src)[源代码]

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

LANGUAGE_SESSION_KEY

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