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) [source]

Эта функция изменяет заголовок Cache-Control путем добавления всех аргументов ключевых слов к нему. Преобразование выполняется следующим образом:

Все имена параметров ключевых слов преобразуются в нижний регистр, а подчеркивания заменяются дефисами.
Если значение параметра равно True (точно True, а не просто истинному значению), в заголовок добавляется только имя параметра.
Все другие параметры добавляются со своим значением после применения str() к нему.

get_max_age(response) [source]: Возвращает max-age из заголовка ответа Cache-Control как целое число (или None если он не найден или не является целым числом).

patch_response_headers(response, cache_timeout=None) [source]

Добавляет несколько полезных заголовков к заданному объекту HttpResponse.

ETag
Last-Modified
Expires
Cache-Control

Каждый заголовок добавляется только в том случае, если он еще не установлен.

cache_timeout в секундах. По умолчанию используется настройка CACHE_MIDDLEWARE_SECONDS.

add_never_cache_headers(response) [source]: Добавляет заголовок Cache-Control: max-age=0, no-cache, no-store, must-revalidate к ответу, чтобы указать, что страница никогда не должна кэшироваться.

В более старых версиях отправлялся заголовок Cache-Control: max-age=0. Это не гарантировало предотвращения кэширования во всех браузерах.

patch_vary_headers(response, newheaders) [source]

Добавляет (или обновляет) заголовок Vary в заданном объекте HttpResponse.

newheaders — список имен заголовков, которые должны быть в Vary.

Существующие заголовки в Vary не удаляются.

get_cache_key(request, key_prefix=None) [source]

Возвращает ключ кэша, основанный на пути запроса. Он может использоваться на фазе запроса, поскольку извлекает список заголовков для учета из глобальной реестра путей и использует их для построения ключа кэша для проверки.

Если список заголовков не сохранен, страница должна быть перестроена, поэтому эта функция возвращает None.

learn_cache_key(request, response, cache_timeout=None, key_prefix=None) [source]

Определяет, какие заголовки следует учитывать для некоторого пути запроса из объекта ответа. Эти заголовки сохраняются в глобальном реестре путей, так что последующий доступ к этому пути будет знать, какие заголовки учитывать без построения самого объекта ответа.

Список заголовков для генерации ключа кэша хранится в том же кэше, что и сами страницы. Если кэш удаляет некоторые данные из кэша, это означает, что нам нужно один раз создать ответ, чтобы получить заголовок Vary и, таким образом, список заголовков для использования в ключе кэша.

`django.utils.dateparse`

Функции, определенные в этом модуле, обладают следующими свойствами:

Они генерируют ValueError, если их входные данные отформатированы, но не являются допустимой датой или временем.
Они возвращают None если они вообще не отформатированы.
Они принимают разрешение до пикосекунд в качестве входных данных, но усекают их до микросекунд, поскольку Python поддерживает именно это.

parse_date(value) [source]: Разбирает строку и возвращает datetime.date.

parse_time(value) [source]

Разбирает строку и возвращает datetime.time.

Смещения UTC не поддерживаются; если value описывает одно, результат — None.

parse_datetime(value) [source]

Разбирает строку и возвращает datetime.datetime.

Смещения UTC поддерживаются; если value описывает одно, атрибут tzinfo результата — экземпляр FixedOffset.

parse_duration(value) [source]

Разбирает строку и возвращает datetime.timedelta.

Ожидаются данные в формате "DD HH:MM:SS.uuuuuu" или как указано в ISO 8601 (например, P4DT1H15M20S, что эквивалентно 4 1:15:20).

`django.utils.decorators`

method_decorator(decorator, name='') [source]

Преобразует декоратор функции в декоратор метода. Его можно использовать для декорирования методов или классов; в последнем случае, name — имя метода, который нужно декорировать, и он требуется.

decorator также может быть списком или кортежем функций. Они оборачиваются в обратном порядке, чтобы порядок вызовов соответствовал порядку появления функций в списке/кортеже.

См. декорирование представлений на основе классов для примера использования.

Были добавлены возможность декорирования классов, параметр name, и возможность для decorator принимать список/кортеж функций-декораторов.

decorator_from_middleware(middleware_class) [source]: Принимая на вход класс middleware, возвращает декоратор представления. Это позволяет использовать функциональность middleware на уровне отдельных представлений. Middleware создается без параметров.

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

`django.utils.encoding`

python_2_unicode_compatible() [source]

Атрибут, который определяет методы __unicode__ и __str__ под Python 2. В Python 3 он ничего не делает.

Для поддержки Python 2 и 3 с одним кодовым основанием, определите метод __str__ возвращающий текст и примените этот декоратор к классу.

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

Возвращает текстовый объект, представляющий s – unicode в Python 2 и str в Python 3. Обрабатывает байтовые строки с использованием кодека encoding.

Если strings_only равно True, не преобразовывать (некоторые) объекты, не являющиеся строками.

smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict'): Историческое название smart_text(). Доступно только в Python 2.

is_protected_type(obj) [source]

Определяет, является ли экземпляр объекта защищенным типом.

Объекты защищённых типов сохраняются как есть при передаче в force_text(strings_only=True).

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

Аналогично 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') [source]

Возвращает байтовую строку версии s, закодированную как указано в encoding.

Если strings_only равно True, не преобразовывать (некоторые) объекты, не являющиеся строками.

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

Аналогично smart_bytes, за исключением того, что ленивые экземпляры преобразуются в байтовые строки, а не сохраняются как ленивые объекты.

Если strings_only равно True, не преобразовывать (некоторые) объекты, не являющиеся строками.

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

Псевдоним smart_bytes() в Python 2 и smart_text() в Python 3. Эта функция возвращает строку str или ленивую строку.

Например, это подходит для записи в sys.stdout в Python 2 и 3.

force_str(s, encoding='utf-8', strings_only=False, errors='strict'): Псевдоним force_bytes() в Python 2 и force_text() в Python 3. Эта функция всегда возвращает str.

iri_to_uri(iri) [source]

Преобразует часть Международного идентификатора ресурса (IRI) в часть URI, пригодную для включения в URL.

Это алгоритм из раздела 3.1 RFC 3987#section-3.1. Однако, поскольку мы предполагаем, что входной данные уже в UTF-8 или Unicode, мы можем немного упростить метод.

Принимает IRI в байтах UTF-8 и возвращает ASCII байты с закодированным результатом.

uri_to_iri(uri) [source]

Преобразует Унифицированный идентификатор ресурса в Международный идентификатор ресурса.

Это алгоритм из раздела 3.2 RFC 3987#section-3.2.

Принимает URI в ASCII байтах и возвращает строку Unicode с закодированным результатом.

filepath_to_uri(path) [source]

Преобразует путь к файловой системе в часть URI, пригодную для включения в URL. Предполагается, что путь находится в UTF-8 или Unicode.

Этот метод будет кодировать определенные символы, которые обычно распознаются как специальные символы для URI. Обратите внимание, что этот метод не кодирует символ «’, так как это допустимый символ в URI. См. Функцию JavaScript encodeURIComponent() для получения дополнительных сведений.

Возвращает ASCII строку, содержащую закодированный результат.

escape_uri_path(path) [source]: Экранирует небезопасные символы из части пути Унифицированного идентификатора ресурса (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) [source]

Создаёт TagURI.

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

`SyndicationFeed`

class SyndicationFeed [source]

Базовый класс для всех лент агрегации. Подклассы должны предоставлять 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) [source]

Инициализирует ленту с заданным словарем метаданных, который применяется ко всей ленте.

Любые дополнительные ключевые аргументы, которые вы передадите в __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) [source]: Добавляет элемент в ленту. Все аргументы ожидают объекты Python unicode , за исключением pubdate и updateddate, которые являются объектами datetime.datetime , enclosure, который является экземпляром Enclosure , и enclosures, который является списком экземпляров Enclosure .

Устарело начиная с версии 1.9: Ключевой аргумент enclosure устарел в пользу нового ключевого аргумента enclosures , который принимает список объектов Enclosure.

num_items() [source]

root_attributes() [source]: Возвращает дополнительные атрибуты для корневого элемента (т.е. элемента ленты/канала). Вызывается из write().

add_root_elements(handler) [source]: Добавляет элементы в корневой элемент (т.е. элемент ленты/канала). Вызывается из write().

item_attributes(item) [source]: Возвращает дополнительные атрибуты, которые нужно разместить в каждом элементе (т.е. элементе item/entry).

add_item_elements(handler, item) [source]: Добавляет элементы в каждый элемент (т.е. элемент item/entry).

write(outfile, encoding) [source]: Выводит ленту в заданной кодировке в outfile, который является объектом типа файл. Подклассы должны переопределять это.

writeString(encoding) [source]: Возвращает ленту в заданной кодировке в виде строки.

latest_post_date() [source]: Возвращает самую позднюю pubdate или updateddate для всех элементов в ленте. Если ни у одного элемента нет этих атрибутов, возвращается текущая дата/время.

`Enclosure`

class Enclosure [source]: Представляет собой enclosure RSS

`RssFeed`

class RssFeed(SyndicationFeed) [source]

`Rss201rev2Feed`

class Rss201rev2Feed(RssFeed) [source]: Спецификация: https://cyber.law.harvard.edu/rss/rss.html

`RssUserland091Feed`

class RssUserland091Feed(RssFeed) [source]: Спецификация: http://backend.userland.com/rss091

`Atom1Feed`

class Atom1Feed(SyndicationFeed) [source]: Спецификация: https://tools.ietf.org/html/rfc4287

`django.utils.functional`

class cached_property(object, name) [source]

Декоратор @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() будет вычислять 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) [source]

Django предлагает множество утилитных функций (особенно в django.utils), которые принимают строку в качестве своего первого аргумента и выполняют с ней какие-либо действия. Эти функции используются фильтрами шаблонов, а также непосредственно в другом коде.

Если вы напишете свои собственные аналогичные функции и будете работать с переводами, у вас возникнет проблема, как поступить, когда первый аргумент является объектом ленивого перевода. Вы не хотите сразу преобразовывать его в строку, потому что вы можете использовать эту функцию вне представления (и поэтому текущие настройки локали текущей нити не будут корректными).

Для таких случаев используйте декоратор django.utils.functional.allow_lazy() . Он модифицирует функцию таким образом, что если она вызывается с объектом ленивого перевода в качестве одного из аргументов, вычисление функции откладывается до тех пор, пока не потребуется его преобразование в строку.

Например:

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 на Python 3) сюда и убедиться, что ваша функция возвращает только строки Unicode.

Использование этого декоратора означает, что вы можете написать свою функцию и предположить, что вход — это правильная строка, а затем добавить поддержку объектов ленивого перевода в конце.

`django.utils.html`

Обычно вы должны строить HTML с помощью шаблонов Django, чтобы воспользоваться механизмом автоматического экранирования, используя утилиты в django.utils.safestring где это уместно. Этот модуль предоставляет некоторые дополнительные утилиты низкого уровня для экранирования HTML.

escape(text) [source]: Возвращает заданный текст с амперсандами, кавычками и угловыми скобками, закодированными для использования в HTML. Ввод сначала передается через force_text(), а вывод имеет mark_safe() примененным.

conditional_escape(text) [source]: Аналогично escape(), за исключением того, что он не работает со строками, предварительно экранированными, поэтому он не будет выполнять двойное экранирование.

format_html(format_string, *args, **kwargs) [source]

Это аналогично str.format(), за исключением того, что оно подходит для создания фрагментов HTML. Все аргументы и ключевые слова передаются через conditional_escape() перед передачей в str.format().

В случае построения небольших фрагментов 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) [source]

Обертка format_html() для распространенного случая группы аргументов, которые нужно отформатировать с использованием одной и той же строки форматирования, а затем объединить с помощью sep. sep также передается через conditional_escape().

args_generator должен быть итератором, который возвращает последовательность args, которые будут переданы в format_html(). Например:

format_html_join(
    '\n', "<li>{} {}</li>",
    ((u.first_name, u.last_name) for u in users)
)

strip_tags(value) [source]

Пытается удалить все, что похоже на тег HTML из строки, то есть всё, что содержится в <>.

Абсолютно никакой гарантии нет, что результирующая строка будет безопасной для HTML. Поэтому НИКОГДА не помечайте результат вызова strip_tag как безопасный без предварительного экранирования, например, с помощью escape().

Например:

strip_tags(value)

Если value равно "<b>Joel</b> <button>is</button> a <span>slug</span>", то значение возврата будет "Joel is a slug".

Если вам нужна более надёжное решение, взгляните на Python библиотеку bleach.

remove_tags(value, tags) [source]

Устарело начиная с версии 1.8: remove_tags() не может гарантировать безопасность вывода HTML и было устарело из-за соображений безопасности. Рассмотрите использование bleach вместо этого.

Удаляет из вывода список тегов [X]HTML, разделённых пробелами.

Абсолютно никакой гарантии нет, что результирующая строка будет безопасной для HTML. В частности, она не работает рекурсивно, поэтому вывод remove_tags("<sc<script>ript>alert('XSS')</sc</script>ript>", "script") не удалит вложенные теги script. Таким образом, если value является небезопасным, НИКОГДА не помечайте результат вызова remove_tags() как безопасный без предварительного экранирования, например, с помощью escape().

Например:

remove_tags(value, "b span")

Если value равно "<b>Joel</b> <button>is</button> a <span>slug</span>", то значение возврата будет "Joel <button>is</button> a slug".

Обратите внимание, что этот фильтр чувствителен к регистру.

Если value равно "<B>Joel</B> <button>is</button> a <span>slug</span>", то значение возврата будет "<B>Joel</B> <button>is</button> a slug".

html_safe() [source]

Метод __html__() в классе помогает не-Django шаблонам обнаружить классы, вывод которых не требует экранирования HTML.

Этот декоратор определяет метод __html__() у декорированного класса, обернув __unicode__() (Python 2) или __str__() (Python 3) в mark_safe(). Убедитесь, что метод __unicode__() или __str__() действительно возвращает текст, который не требует экранирования HTML.

`django.utils.http`

urlquote(url, safe='/') [source]: Версия функции Python’s urllib.quote(), которая может работать со строками unicode. URL сначала кодируется в UTF-8 перед цитированием. Возвращаемая строка может безопасно использоваться как часть аргумента последующего вызова iri_to_uri() без двойного цитирования. Использует отложенное выполнение.

urlquote_plus(url, safe='') [source]: Версия функции Python’s urllib.quote_plus(), которая может работать со строками unicode. URL сначала кодируется в UTF-8 перед цитированием. Возвращаемая строка может безопасно использоваться как часть аргумента последующего вызова iri_to_uri() без двойного цитирования. Использует отложенное выполнение.

urlencode(query, doseq=0) [source]: Версия функции Python’s urllib.urlencode(), которая может работать со строками unicode. Параметры сначала преобразуются в строки, закодированные в UTF-8, а затем кодируются стандартным способом.

cookie_date(epoch_seconds=None) [source]

Форматирует время для обеспечения совместимости со стандартом файлов cookie Netscape.

Принимает число с плавающей запятой, выраженное в секундах с момента эпохи в UTC – например, то, что выведено time.time(). Если установлено в None, по умолчанию используется текущее время.

Выводит строку в формате Wdy, DD-Mon-YYYY HH:MM:SS GMT.

http_date(epoch_seconds=None) [source]

Форматирует время для соответствия формату даты RFC 1123, как указано в HTTP RFC 7231#section-7.1.1.1.

Выводит строку в формате Wdy, DD Mon YYYY HH:MM:SS GMT.

base36_to_int(s) [source]: Преобразует строку в системе счисления с основанием 36 в целое число. В Python 2 результат гарантированно является целым типом int а не числом с плавающей точкой long.

END_OF_DOCUMENT_MARKER

int_to_base36(i) [source]: Преобразует положительное целое число в строку в системе счисления с основанием 36. В Python 2 i должно быть меньше sys.maxint.

urlsafe_base64_encode(s) [source]: Кодирует байтовую строку в base64 для использования в URL, удаляя любые конечные знаки равенства.

urlsafe_base64_decode(s) [source]: Декодирует закодированную в base64 строку, добавляя обратно любые конечные знаки равенства, которые могли быть удалены.

`django.utils.module_loading`

Функции для работы с модулями Python.

import_string(dotted_path) [source]

Импортирует путь к модулю с точками и возвращает атрибут/класс, обозначенный последним именем в пути. Вызывает 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 [source]: Подкласс bytes, который был специально помечен как «безопасный» (не требует дополнительного экранирования) для целей вывода HTML.

class SafeString: Подкласс str, который был специально помечен как «безопасный» (не требует дополнительного экранирования) для целей вывода HTML. Это SafeBytes в Python 2 и SafeText в Python 3.

class SafeText [source]: Подкласс str (в Python 3) или unicode (в Python 2), который был специально помечен как «безопасный» для целей вывода HTML.

class SafeUnicode: Историческое название SafeText. Доступно только в Python 2.

mark_safe(s) [source]

Явно отмечает строку как безопасную для вывода (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) [source]

Явно отмечает строку как требующую экранирования HTML при выводе. Не имеет эффекта на SafeData подклассы.

Может вызываться несколько раз для одной строки (результативное экранирование применяется только один раз).

`django.utils.text`

slugify(allow_unicode=False) [source]

Преобразует в ASCII, если allow_unicode является False (по умолчанию). Преобразует пробелы в дефисы. Удаляет символы, которые не являются алфавитно-цифровыми, подчеркиваниями или дефисами. Преобразует в нижний регистр. Также удаляет начальные и конечные пробелы.

Например:

slugify(value)

Если value является "Joel is a slug", выход будет "joel-is-a-slug".

Можно установить параметр allow_unicode в True, если вы хотите разрешить символы Unicode:

slugify(value, allow_unicode=True)

Если value является "你好 World", выход будет "你好-world".

Параметр allow_unicode был добавлен.

`django.utils.timezone`

utc: tzinfo экземпляр, представляющий UTC.

class FixedOffset(offset=None, name=None) [source]: Подкласс tzinfo, моделирующий фиксированный смещение от UTC. offset - целое число в минутах к востоку от UTC.

get_fixed_timezone(offset) [source]

Возвращает экземпляр tzinfo, представляющий часовой пояс с фиксированным смещением от UTC.

offset - datetime.timedelta или целое число в минутах. Используйте положительные значения для часовых поясов к востоку от UTC и отрицательные значения для часовых поясов к западу от UTC.

get_default_timezone() [source]: Возвращает экземпляр tzinfo, представляющий по умолчанию часовой пояс.

get_default_timezone_name() [source]: Возвращает имя по умолчанию часового пояса.

get_current_timezone() [source]: Возвращает экземпляр tzinfo, представляющий текущий часовой пояс.

get_current_timezone_name() [source]: Возвращает имя текущего часового пояса.

activate(timezone) [source]: Устанавливает текущий часовой пояс. Аргумент timezone должен быть экземпляром подкласса tzinfo или, если доступен pytz, именем часового пояса.

deactivate() [source]: Снимает установку текущего часового пояса.

END_OF_DOCUMENT_MARKER

override(timezone) [source]: Этот менеджер контекста Python устанавливает текущую временную зону при входе с помощью activate() и восстанавливает ранее активную временную зону при выходе. Если аргумент timezone равен None, то текущая временная зона сбрасывается при входе с помощью deactivate().

override теперь может использоваться как декоратор функции.

localtime(value, timezone=None) [source]

Преобразует объект datetime с известной временной зоной в другую временную зону, по умолчанию в текущую временную зону.

Эта функция не работает с неявными датами и временами; используйте make_aware() вместо неё.

now() [source]

Возвращает datetime, представляющий текущий момент времени. Точное возвращаемое значение зависит от значения USE_TZ:

Если USE_TZ равно False, это будет неявный объект datetime (т.е. объект datetime без связанной временной зоны), представляющий текущее время в локальной временной зоне системы.
Если USE_TZ равно True, это будет явный объект datetime, представляющий текущее время в UTC. Обратите внимание, что now() всегда будет возвращать время в UTC независимо от значения TIME_ZONE; вы можете использовать localtime() для преобразования в время в текущей временной зоне.

is_aware(value) [source]: Возвращает True, если value имеет явную временную зону, и False, если она неявная. Эта функция предполагает, что value является объектом datetime.

is_naive(value) [source]: Возвращает True, если value неявный, и False, если явный. Эта функция предполагает, что value является объектом datetime.

make_aware(value, timezone=None, is_dst=None) [source]

Возвращает явный объект datetime, который представляет ту же точку времени, что и value в timezone, value — неявный datetime. Если timezone установлено в None, оно по умолчанию равно текущей временной зоне.

При установке pytz будет выброшено исключение pytz.AmbiguousTimeError, если вы попытаетесь сделать value явным во время перехода DST, когда одинаковое время встречается дважды (при возвращении из DST). Установка is_dst в True или False позволит избежать исключения, выбирая, является ли время до или после перехода.

При установке pytz будет выброшено исключение pytz.NonExistentTimeError, если вы попытаетесь сделать value явным во время перехода DST, при котором время никогда не происходило (при входе в DST). Установка is_dst в True или False позволит избежать исключения, сместив час назад или вперед на 1 соответственно. Например, is_dst=True изменит несуществующее время 2:30 на 1:30, а is_dst=False — на 3:30.

is_dst не имеет эффекта, если pytz не установлен.

В старых версиях Django, timezone был обязательным аргументом.

Аргумент is_dst был добавлен.

make_naive(value, timezone=None) [source]: Возвращает неявный datetime, который представляет в timezone ту же точку времени, что и value, value — явный datetime. Если timezone установлено в None, оно по умолчанию равно текущей временной зоне.

В старых версиях Django, timezone был обязательным аргументом.

`django.utils.translation`

Для получения полного описания использования см. документацию по переводу.

gettext(message) [source]: Переводит message и возвращает его в строке UTF-8.

ugettext(message) [source]: Переводит message и возвращает его в строке unicode.

pgettext(context, message) [source]

Переводит message с заданным context и возвращает его в строке unicode.

Для получения дополнительной информации см. Контекстуальные метки.

gettext_lazy(message)

ugettext_lazy(message)

pgettext_lazy(context, message)

То же, что и не ленивые версии выше, но с использованием ленивого выполнения.

См. документацию по ленивым переводам.

gettext_noop(message) [source]

ugettext_noop(message): Помечает строки для перевода, но не переводит их сейчас. Это может быть использовано для хранения строк в глобальных переменных, которые должны оставаться на языке оригинала (потому что они могут использоваться внешне), и которые будут переведены позже.

ngettext(singular, plural, number) [source]: Переводит singular и plural и возвращает соответствующую строку на основе number в строке UTF-8.

END_OF_DOCUMENT_MARKER

ungettext(singular, plural, number) [source]: Переводит singular и plural и возвращает соответствующую строку на основе number в строке Unicode.

npgettext(context, singular, plural, number) [source]: Переводит singular и plural и возвращает соответствующую строку на основе number и context в строке Unicode.

ngettext_lazy(singular, plural, number) [source]

ungettext_lazy(singular, plural, number) [source]

npgettext_lazy(context, singular, plural, number) [source]

Аналогично вариантам без добавления отложенного выполнения, но использует отложенное выполнение.

См. документацию по отложенным переводу.

string_concat(*strings): Отложенный вариант конкатенации строк, необходимый для переводов, которые строятся из нескольких частей.

activate(language) [source]: Получает объект перевода для заданного языка и активирует его в качестве текущего объекта перевода для текущего потока.

deactivate() [source]: Деактивирует текущий активный объект перевода, так что дальнейшие вызовы _ будут разрешаться по отношению к объекту перевода по умолчанию.

deactivate_all() [source]: Делает активный объект перевода экземпляром NullTranslations(). Это полезно, когда мы хотим, чтобы отложенные переводы отображались как исходная строка по какой-либо причине.

override(language, deactivate=False) [source]

Объект контекста Python, который использует django.utils.translation.activate() для получения объекта перевода для заданного языка, активирует его в качестве объекта перевода для текущего потока и активирует предыдущий активный язык при выходе. При необходимости он может просто деактивировать временный перевод при выходе с помощью django.utils.translation.deactivate(), если аргумент deactivate равен True. Если вы передадите None в качестве аргумента языка, в контексте будет активирован экземпляр NullTranslations().

override теперь может использоваться в качестве декоратора функции.

check_for_language(lang_code) [source]: Проверяет наличие глобального файла языка для заданного кода языка (например, «fr», «pt_BR»). Это используется для определения доступности языка, указанного пользователем.

get_language() [source]: Возвращает код текущего выбранного языка. Возвращает None, если переводы временно деактивированы (методом deactivate_all() или когда None передано в override()).

До Django 1.8 get_language() всегда возвращало LANGUAGE_CODE при деактивации переводов.

get_language_bidi() [source]

Возвращает расположение BiDi выбранного языка:

False = расположение слева направо
True = расположение справа налево

get_language_from_request(request, check_path=False) [source]

Анализирует запрос, чтобы определить, какой язык пользователь хочет отобразить на системе. Учитываются только языки, указанные в settings.LANGUAGES. Если пользователь запрашивает подязык, где у нас есть основной язык, мы отправляем основной язык.

Если check_path равно True, функция сначала проверяет запрошенный URL на предмет того, начинается ли его путь с кода языка, указанного в настройке LANGUAGES.

to_locale(language) [source]: Преобразует имя языка (en-us) в имя локали (en_US).

templatize(src) [source]: Преобразует шаблон Django в то, что понимает xgettext. Это делается путем перевода тегов перевода Django в стандартные вызовы функции gettext.

LANGUAGE_SESSION_KEY: Ключ сессии, в котором хранится активный язык для текущей сессии.

© Django Software Foundation and individual contributors
Licensed under the BSD License.
https://docs.djangoproject.com/en/1.9/ref/utils/