Django Utils

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

`django.utils.cache`

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

Дополнительную информацию о заголовке Vary см. в RFC 2616#section-14.44 разделе 14.44.

По существу, заголовок Vary HTTP определяет, какие заголовки должен учитывать кеш при построении ключа кеша. Запросы с одинаковым путём, но разным содержимым заголовков для заголовков, указанных в Vary, должны получать разные ключи кеша, чтобы предотвратить доставку неправильного содержимого.

Например, middleware для Accept-language потребовалось бы различать кеши по заголовку 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]: Добавляет заголовки в ответ, чтобы указать, что страница никогда не должна кешироваться.

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 ответа, но мы хотим предотвратить генерацию ответа.

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

`django.utils.datastructures`

class SortedDict [source]

Устарело начиная с версии 1.7: SortedDict устарело и будет удалено в Django 1.9. Используйте collections.OrderedDict вместо этого.

Класс django.utils.datastructures.SortedDict — это словарь, который сохраняет свои ключи в порядке их вставки.

Создание нового SortedDict

Создание нового SortedDict должно быть выполнено таким образом, чтобы порядок был гарантирован. Например:

SortedDict({'b': 1, 'a': 2, 'c': 3})

не сработает. Передача простого Python dict может привести к непредсказуемым результатам. Вместо этого сделайте следующее:

SortedDict([('b', 1), ('a', 2), ('c', 3)])

`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) [source]: Преобразует декоратор функции в декоратор метода. См. декорирование представлений на основе классов для примера использования.

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

END_OF_DOCUMENT_MARKER

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 см. в: http://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss

get_tag_uri(url, date) [source]

Создает TagURI.

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

Необязательный аргумент updateddate был добавлен.

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]: Представляет вложение RSS

RssFeed

class RssFeed(SyndicationFeed) [source]

Rss201rev2Feed

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

RssUserland091Feed

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

Atom1Feed

class Atom1Feed(SyndicationFeed) [source]: Спецификация: http://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() будет пересчитывать друзей при каждом вызове, значение кэшированного свойства сохранится, пока вы его не удалите, как описано выше:

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 urllib.quote() , которая может работать со строками unicode. Ссылка сначала кодируется в UTF-8 перед цитированием. Возвращённая строка может безопасно использоваться в качестве части аргумента последующего вызова iri_to_uri() без возникновения двойного цитирования. Используется отложенное выполнение.

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

urlencode(query, doseq=0) [source]: Версия функции Python 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, как указано в разделе 3.3.1 спецификации HTTP RFC 2616#section-3.3.1.

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

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

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

END_OF_DOCUMENT_MARKER ```

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

import_by_path(dotted_path, error_prefix='') [source]: Устаревшее начиная с версии 1.7: Используйте import_string() вместо этого.

Импортирует путь к модулю с точками и возвращает атрибут/класс, определенный последним именем в пути. Вызывает ImproperlyConfigured в случае возникновения проблем.

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

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

Например:

slugify(value)

Если value равно "Joel is a slug", результат будет "joel-is-a-slug".

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

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

Эта функция может генерировать исключение, если value не существует или является неоднозначным из-за переходов по времени.

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

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 байтовой строки.

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

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

END_OF_DOCUMENT_MARKER

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 теперь может использоваться как декоратор функции.

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.utils.tzinfo`

Устарело начиная с версии 1.7: Используйте timezone вместо этого.

class FixedOffset [source]: Фиксированный смещение в минутах к востоку от UTC.

Устарело начиная с версии 1.7: Используйте get_fixed_timezone() вместо этого.

class LocalTimezone [source]: Прокси-информация о часовом поясе из модуля time.

Устарело начиная с версии 1.7: Используйте get_default_timezone() вместо этого.

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