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:20
的P4DT1H15M20S
)。
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_only
是True
,不转换(一些)非字符串对象。
-
smart_unicode
(s, encoding='utf-8', strings_only=False, errors='strict')¶ smart_text()
的历史名称。仅在Python 2下可用。
-
force_text
(s, encoding='utf-8', strings_only=False, errors='strict')[源代码]¶ 类似于
smart_text
,除了惰性实例被解析为字符串,而不是保持为惰性对象。如果
strings_only
是True
,不转换(一些)非字符串对象。
-
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_only
是True
,不转换(一些)非字符串对象。
-
force_bytes
(s, encoding='utf-8', strings_only=False, errors='strict')[源代码]¶ 类似于
smart_bytes
,除了惰性实例被解析为bytestrings,而不是保持为惰性对象。如果
strings_only
是True
,不转换(一些)非字符串对象。
-
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字符串。
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')
为了简化发电机的选择,使用当前为 Rss201rev2Feed
的 feedgenerator.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中添加项目。所有参数都应该是除了
pubdate
和updateddate
(它们是datetime.datetime
对象)之外的Pythonunicode
对象,enclosure
(它是Enclosure
实例)和enclosures
(它是Enclosure
实例的列表)。1.9 版后已移除:
enclosure
关键字参数已被弃用,以支持新的enclosures
关键字参数,它接受Enclosure
对象的列表。
-
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()
。
-
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) )
尝试从字符串中删除任何看起来像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编码字符串,然后按照正常编码。
格式化时间以确保与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
格式输出字符串。
-
int_to_base36
(i)[源代码]¶ 将正整数转换为基本36个字符串。在Python 2
i
必须小于 sys.maxint。
django.utils.module_loading
¶
使用Python模块的函数。
django.utils.safestring
¶
使用“安全字符串”的函数和类:可以安全显示而无需在HTML中进一步转义的字符串。将某个标记为“安全字符串”意味着字符串的生成器已经将不应该由HTML引擎解释的字符(例如“<”)转换成适当的实体。
-
class
SafeString
¶ 已被特别标记为“安全”(不需要进一步转义)的
str
子类用于HTML输出目的。这是在Python 2的SafeBytes
和在Python 3的SafeText
。
-
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'>
django.utils.text
¶
-
slugify
(allow_unicode=False)[源代码]¶ 如果
allow_unicode
为False
(默认),则转换为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
¶
-
get_fixed_timezone
(offset)[源代码]¶ 返回表示具有与UTC的固定偏移量的时区的
tzinfo
实例。offset
是datetime.timedelta
或整数分钟。在UTC以前的时区使用正值,在UTC以外使用负值。
-
override
(timezone)[源代码]¶ 这是一个Python上下文管理器,用于设置 当前时区 在有
activate()
的条目上,并在退出时恢复以前活动的时区。如果timezone
参数是None
,则 当前时区 将在deactivate()
条目上取消设置。override
也可用作函数装饰器。
-
localtime
(value, timezone=None)[源代码]¶ 将感知
datetime
转换为不同的时区,默认情况下为 当前时区。此功能在天真的数据时间不工作;使用
make_aware()
。
-
make_aware
(value, timezone=None, is_dst=None)[源代码]¶ 返回表示与
timezone
中的value
相同的时间点的感知datetime
,value
是原始datetime
。如果timezone
设置为None
,则默认为 当前时区。当安装 pytz 时,如果您尝试在同一时间发生两次(从DST恢复时)的DST转换期间使
value
感知,则会引发异常pytz.AmbiguousTimeError
。将is_dst
设置为True
或False
将分别通过选择时间是转换前还是转换后来避免异常。当安装 pytz 时,如果您尝试在DST转换期间使
value
感知,使得时间从未发生(进入DST时),则会引发异常pytz.NonExistentTimeError
。将is_dst
设置为True
或False
将分别向后或向后移动小时以避免异常。例如,is_dst=True
会将不存在的时间从2:30更改为1:30,is_dst=False
会将时间更改为3:30。当未安装
pytz
时,is_dst
无效。Changed in Django 1.9:添加了
is_dst
参数。
django.utils.translation
¶
有关以下使用的完整讨论,请参阅 翻译文档。
-
gettext_lazy
(message)¶
-
ugettext_lazy
(message)¶
-
ugettext_noop
(message)¶ 标记要翻译的字符串,但不会立即翻译。这可以用于将字符串存储在应该保持基本语言的全局变量中(因为它们可能在外部使用),并且稍后将进行翻译。
-
npgettext
(context, singular, plural, number)[源代码]¶ 翻译
singular
和plural
,并在unicode字符串中返回基于number
和context
的适当字符串。
-
string_concat
(*strings)¶ 字符串连接的延迟变体,需要从多个部分构建的翻译。
-
override
(language, deactivate=False)[源代码]¶ 一个使用
django.utils.translation.activate()
来获取给定语言的翻译对象的Python上下文管理器将其激活为当前线程的翻译对象,并在退出时重新激活以前的活动语言。可选地,如果deactivate
参数是True
,则它可以简单地停用具有django.utils.translation.deactivate()
的退出时的临时转换。如果您传递None
作为语言参数,则在上下文中激活NullTranslations()
实例。override
也可用作函数装饰器。
-
get_language
()[源代码]¶ 返回当前选择的语言代码。如果暂时停用翻译(通过
deactivate_all()
或将None
传递给override()
),则返回None
。
-
get_language_from_request
(request, check_path=False)[源代码]¶ 分析请求以找到用户希望系统显示哪种语言。仅考虑在settings.LANGUAGES中列出的语言。如果用户请求一个具有主语言的子语言,我们发出主语言。
如果
check_path
是True
,则函数首先检查所请求的URL,以确定其路径是否以LANGUAGES
设置中列出的语言代码开头。
-
LANGUAGE_SESSION_KEY
¶ 存储当前会话的活动语言的会话密钥。