本文档涵盖了django.utils中的所有稳定模块。django.utils中的大多数模块都是为内部使用而设计的，只有以下部分才能被视为稳定，因此按照internal release deprecation policy可向后兼容。
此模块包含用于控制缓存的辅助函数。它通过管理响应的Vary标头来实现。它包括直接修补响应对象的头部的函数和修改函数的修饰器来做自己的头部修补。
有关Vary头的信息，请参见第14.44节 RFC 2616。
本质上，Vary HTTP头定义了缓存在构建缓存键时应考虑哪些头。对于在Vary中命名的头，具有相同路径但头部内容不同的请求需要获得不同的缓存键，以防止传送错误的内容。
例如，internationalization中间件需要通过Accept-language头区分缓存。
此函数通过向Cache-Control头中添加所有关键字参数来修补它。变换如下：
向给定的HttpResponse对象添加一些有用的标题：
每个标头仅在尚未设置时才添加。
cache_timeout以秒为单位。默认情况下使用CACHE_MIDDLEWARE_SECONDS设置。
在给定的HttpResponse对象中添加（或更新）Vary标题。newheaders是应该在Vary中的标题名称列表。Vary中的现有标题不会被删除。
自1.7版起已弃用： SortedDict已弃用，将在Django 1.9中移除。请改用collections.OrderedDict。
django.utils.datastructures.SortedDict类是一个字典，按照它们的插入顺序保持其键。
创建新SortedDict必须以保证排序的方式完成。例如：
SortedDict({'b': 1, 'a': 2, 'c': 3})
不管用。传入基本的Python dict可能会产生不可靠的结果。相反做：
SortedDict([('b', 1), ('a', 2), ('c', 3)])
此模块中定义的函数共享以下属性：
解析字符串并返回datetime.date。
解析字符串并返回datetime.time。
不支持UTC偏移；如果value描述一个，结果为None。
解析字符串并返回datetime.datetime。
支持UTC偏移；如果value描述一个，则结果的tzinfo属性是FixedOffset实例。
解析字符串并返回datetime.timedelta。
预期采用格式“DD HH：MM：SS.uuuuu”或ISO 8601规定的数据P4DT1H15M20S其等效于4 1:15:20）。
将函数装饰器转换为方法装饰器。有关示例用法，请参见decorating class based views。
给定一个中间件类，返回一个视图装饰器。这使您可以在每个视图的基础上使用中间件功能。中间件创建时没有传递参数。
像decorator_from_middleware，但返回一个函数，接受要传递给middleware_class的参数。例如，cache_page()装饰器是从CacheMiddleware创建的，如下所示：
cache_page = decorator_from_middleware_with_args(CacheMiddleware)
@cache_page(3600)
def my_view(request):
pass
在Python 2下定义__unicode__和__str__方法的装饰器。在Python 3下它什么也不做。
要使用单个代码库支持Python 2和3，请定义返回文本的__str__方法，并将此装饰器应用于类。
返回代表Python 3上的s - unicode和Python 3上的str的文本对象。使用encoding编码解码器处理。
如果strings_only是True，请勿转换（一些）非字符串对象。
smart_text()的历史名称。仅在Python 2下可用。
类似于smart_text，除了延迟实例被解析为字符串，而不是保持为延迟对象。
如果strings_only是True，请勿转换（一些）非字符串对象。
force_text()的历史名称。仅在Python 2下可用。
返回encoding中指定的s的按测试版本。
如果strings_only是True，请勿转换（一些）非字符串对象。
类似于smart_bytes，除了延迟实例被解析为bytestrings，而不是保持为延迟对象。
如果strings_only是True，请勿转换（一些）非字符串对象。
Python 2上的smart_bytes()的别名和Python 3上的smart_text()。此函数返回str或惰性字符串。
例如，这适合于在Python 2和3上写入sys.stdout。
Python 2上的force_bytes()的别名和在Python 3上的force_text()。此函数始终返回str。
将国际化资源标识符（IRI）部分转换为适合包含在URL中的URI部分。
这是 RFC 3987第3.1节的算法。然而，由于我们假设输入是UTF-8或unicode已经，我们可以简化东西一点从完整的方法。
采用UTF-8字节的IRI，并返回包含编码结果的ASCII字节。
将统一资源标识符转换为国际化资源标识符。
这是 RFC 3987第3.2节中的算法。
获取ASCII字节的URI，并返回包含编码结果的Unicode字符串。
样品用量：
>>> 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的定义，请参阅：http://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss t0 >
创建一个TagURI。
请参阅http://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id
所有联合供稿的基类。子类应提供write()。
使用给定的元数据字典初始化Feed，该元数据字典应用于整个Feed。
任何传递到__init__的额外关键字参数将存储在self.feed中。
所有参数都应该是Unicode对象，除了categories，它应该是Unicode对象序列。
向Feed中添加项目。除了pubdate和updateddate，它们是datetime.datetime对象，所有参数都应该是Python unicode enclosure，它是Enclosure类的一个实例。
已添加可选的updateddate参数。
@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
Django提供了许多效用函数（特别是在django.utils），它们接受一个字符串作为它们的第一个参数，并对该字符串进行操作。这些函数由模板过滤器使用，也可以直接在其他代码中使用。
如果你写自己的类似的功能和处理翻译，你会面临的问题，当第一个参数是一个延迟翻译对象做什么。您不想立即将其转换为字符串，因为您可能在视图之外使用此函数（因此当前线程的语言环境设置将不正确）。
对于这种情况，使用django.utils.functional.allow_lazy()装饰器。它修改函数，使得if使用延迟转换作为其参数之一调用，函数求值将被延迟，直到需要将其转换为字符串。
例如：
from django.utils.functional import allow_lazy
def fancy_utility_function(s, ...):
# Do some conversion on string 's'
...
# Replace unicode by str on Python 3
fancy_utility_function = allow_lazy(fancy_utility_function, unicode)
除了要装饰的函数之外，allow_lazy()装饰器还需要一些额外的参数（*args），指定原始函数可以返回的类型。通常，在这里包含unicode（或str）就足够了，并且确保函数只返回Unicode字符串。
使用这个装饰器意味着你可以编写你的函数，并假设输入是一个合适的字符串，然后在末尾添加对延迟翻译对象的支持。
通常，您应该使用Django的模板来构建HTML，以使用其自动缩放机制，并在适当的位置使用django.utils.safestring中的实用程序。此模块提供一些额外的低级实用程序用于转义HTML。
返回给定文本，并带有用于HTML的带符号，引号和尖括号。输入首先通过force_text()，输出具有mark_safe()。
这类似于str.format，除了它适合构建HTML片段。在传递给str.format之前，所有args和kwarg都通过conditional_escape()传递。
对于构建小HTML片段的情况，此函数优先于使用%或str.format的字符串插值，因为它将转义应用于所有参数如Template系统默认应用转义。
所以，而不是写：
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()的包装器，用于需要使用相同格式字符串格式化的一组参数的常见情况，然后使用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)
If value is "<b>Joel</b> <button>is</button> a <span>slug</span>" the return value will be "Joel is a slug".
如果您正在寻找更强大的解决方案，请查看bleach Python库。
自版本1.8后已弃用： remove_tags()无法保证HTML安全输出，并且由于安全问题而被弃用。请考虑使用漂白。
从输出中删除[X] HTML标记名称的空格分隔列表。
绝对不保证结果字符串是HTML安全。特别地，它不递归地工作，所以输出remove_tags（“＆lt； sc＆lt； script＆gt； ript＆gt； alert（'XSS'）＆lt； / sc＆lt； / script＆gt； / t1> “script”）不会删除“嵌套”脚本标记。因此，如果value是不可信的，则不要先对remove_tags()调用的结果标记安全，例如使用escape() 。
例如：
remove_tags(value, "b span")
If value is "<b>Joel</b> <button>is</button> a <span>slug</span>" the return value will be "Joel <button>is</button> a slug".
请注意，此过滤器区分大小写。
If value is "<B>Joel</B> <button>is</button> a <span>slug</span>" the return value will be "<B>Joel</B> <button>is</button> a slug".
类上的__html__()方法可帮助非Django模板检测其输出不需要HTML转义的类。
This decorator defines the __html__() method on the decorated class by wrapping the __unicode__() (Python 2) or __str__() (Python 3) in mark_safe(). 确保__unicode__()或__str__()方法确实返回不需要HTML转义的文本。
Python的urllib.quote()函数，可以对unicode字符串进行操作。url在引用前首先进行UTF-8编码。返回的字符串可以安全地用作后续iri_to_uri()调用的参数的一部分，而不会发生双引号。实现延迟执行。
Python的urllib.quote_plus()函数的版本，可以对unicode字符串进行操作。url在引用前首先进行UTF-8编码。返回的字符串可以安全地用作后续iri_to_uri()调用的参数的一部分，而不会发生双引号。实现延迟执行。
Python的urllib.urlencode()函数的版本，可以对unicode字符串进行操作。参数首先转换为UTF-8编码字符串，然后按照正常编码。
格式化时间以确保与Netscape的Cookie标准兼容。
接受以UTC表示的纪元以秒表示的浮点数，例如由time.time()输出的浮点数。如果设置为None，则默认为当前时间。
输出格式为Wdy， DD-Mon-YYYY HH：MM：SS GMT 。
格式化与HTTP RFC 2616部分3.3.1中指定的 RFC 1123日期格式匹配的时间。
接受以UTC表示的纪元以秒表示的浮点数，例如由time.time()输出的浮点数。如果设置为None，则默认为当前时间。
输出格式为Wdy， DD Mon YYYY GMT。
将正整数转换为基本36个字符串。在Python 2 i必须小于sys.maxint。
使用Python模块的函数。
导入虚线模块路径并返回路径中由姓氏指定的属性/类。如果导入失败，则引发ImportError。例如：
from django.utils.module_loading import import_string
ValidationError = import_string('django.core.exceptions.ValidationError')
等效于：
from django.core.exceptions import ValidationError
自1.7版起已弃用：改用import_string()。
导入虚线模块路径并返回路径中由姓氏指定的属性/类。如果出现问题，则提升ImproperlyConfigured。
使用“安全字符串”的函数和类：可以安全显示而无需在HTML中进一步转义的字符串。将某个标记为“安全字符串”意味着字符串的生成器已经转换了不应该由HTML引擎解释的字符（例如，''
将字符串明确标记为（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'>
tzinfo的子类，建模与UTC的固定偏移。offset是一个表示UTC以东分钟数的整数。
返回一个tzinfo实例，该实例表示与UTC具有固定偏移量的时区。
offset是一个datetime.timedelta实例或一个表示分钟的整数。UTC以东的时区使用正值，UTC以西的时区使用负值。
返回表示default time zone的tzinfo实例。
返回default time zone的名称。
返回表示current time zone的tzinfo实例。
返回current time zone的名称。
设置current time zone。timezone参数必须是tzinfo子类的实例，或者如果pytz可用，则是时区名称。
取消设置current time zone。
This is a Python context manager that sets the current time zone on entry with activate(), and restores the previously active time zone on exit. 如果timezone参数为None，则current time zone在输入时取消设置，而改为使用deactivate()。
override现在可用作函数装饰器。
将感知到的datetime转换为不同的时区，默认为current time zone。
此功能在天真的数据时间不工作；请改用make_aware()。
Returns an aware datetime that represents the same point in time as value in timezone, value being a naive datetime. 如果timezone设置为None，则默认为current time zone。
如果value不存在或由于DST转换而不明确，则此函数可能会引发异常。
在旧版本的Django中，timezone是必需的参数。
Returns an naive datetime that represents in timezone the same point in time as value, value being an aware datetime.如果timezone设置为None，则默认为current time zone。
在旧版本的Django中，timezone是必需的参数。
有关以下用法的完整讨论，请参阅translation documentation。
转换message给定context并返回一个unicode字符串。
有关详细信息，请参阅Contextual markers。
与上面的非惰性版本相同，但使用惰性执行。
标记要翻译的字符串，但不会立即翻译。这可以用于将字符串存储在应该保持基本语言的全局变量中（因为它们可能在外部使用），并且稍后将被翻译。
翻译singular和plural，并在unicode字符串中返回基于number和context的适当字符串。
字符串连接的延迟变体，需要从多个部分构建的翻译。
使用django.utils.translation.activate()来获取给定语言的翻译对象的Python上下文管理器将其作为当前线程的翻译对象激活，并在退出时重新激活上一个活动语言。或者，如果deactivate参数为True，则可以使用django.utils.translation.deactivate()退出退出临时转换。如果传递None作为语言参数，则在上下文中激活NullTranslations()实例。
override现在可用作函数装饰器。
返回当前选择的语言代码。如果暂时停用翻译（通过deactivate_all()或将None传递给override()），则返回None 。
在Django 1.8之前，停用翻译时，get_language()总是返回LANGUAGE_CODE。
分析请求以找到用户希望系统显示哪种语言。仅考虑在settings.LANGUAGES中列出的语言。如果用户请求一个具有主语言的子语言，我们发出主语言。
如果check_path为True，则函数首先检查所请求的URL，以确定其路径是否以LANGUAGES设置中列出的语言代码开头。
存储当前会话的活动语言的会话密钥。
自1.7版起已弃用：改用timezone。
固定偏移距离UTC的东部。
自1.7版起已弃用：改用get_fixed_timezone()。
来自时间模块的代理时区信息。
自1.7版起已弃用：改用get_default_timezone()。
2015年5月13日