Django Utils

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

`django.utils.cache`

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

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

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

Например, среда 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
Expires
Cache-Control

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

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

Изменено в Django 1.11:

В более ранних версиях также устанавливался заголовок Last-Modified.

Устарело начиная с версии 1.11: Поскольку настройка USE_ETAGS устарела, эта функция не будет устанавливать заголовок ETag по окончании устаревания в Django 2.1.

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

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.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 также может быть списком или кортежем функций. Они обернуты в обратном порядке, так что порядок вызовов соответствует порядку, в котором функции появляются в списке/кортеже.

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

decorator_from_middleware(middleware_class) [source]

Принимая класс middleware, возвращает декоратор представления. Это позволяет использовать функциональность middleware на уровне отдельных представлений. Middleware создаётся без передачи параметров.

Предполагается middleware, совместимый со старым стилем Django 1.9 и более ранними версиями (имеющий методы, такие как process_request(), process_exception(), и process_response()).

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__, возвращающий текст (используйте six.text_type(), если вы выполняете какое-то преобразование) и примените этот декоратор к классу.

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 для всех элементов в ленте. Если ни один из элементов не имеет ни одного из этих атрибутов, возвращает текущую дату/время UTC.

Изменено в Django 1.11:
В более ранних версиях возвращалась текущая дата/время без какой-либо информации о часовом поясе.

`Enclosure`

class Enclosure [source]: Представляет вложение RSS

`RssFeed`

class RssFeed(SyndicationFeed) [source]

`Rss201rev2Feed`

class Rss201rev2Feed(RssFeed) [source]: Спецификация: https://cyber.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 в представлении и шаблоне одинаков, декорирование метода friends() с помощью @cached_property может этого избежать:

from django.utils.functional import cached_property

class Person(models.Model):

    @cached_property
    def friends(self):
        ...

Обратите внимание, что поскольку метод теперь является свойством, в коде 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]: Устаревшее с версии 1.10.

Работает как keep_lazy(), за исключением того, что его нельзя использовать в качестве декоратора.

END_OF_DOCUMENT_MARKER

keep_lazy(func, *resultclasses) [source]

Новая функция в Django 1.10.

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

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

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

Например:

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

Новая функция в 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`

Обычно для построения 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.

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

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

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

cookie_date(epoch_seconds=None) [source]

Форматирует время для обеспечения совместимости со стандартом куки 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.

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

Выводит строку в формате 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.

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'>

Изменено в Django 1.11:

Добавлена поддержка использования в качестве декоратора.

mark_for_escaping(s) [source]

Устаревшее с версии 1.10.

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

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

`django.utils.text`

format_lazy(format_string, *args, **kwargs)

Добавлено в Django 1.11.

Версия str.format() для случаев, когда format_string, args, и/или kwargs содержат ленивые объекты. Первый аргумент — строка, которая должна быть отформатирована. Например:

from django.utils.text import format_lazy
from django.utils.translation import pgettext_lazy

urlpatterns = [
    url(format_lazy(r'{person}/(?P<pk>\d+)/$', person=pgettext_lazy('URL', 'person')),
        PersonDetailView.as_view()),
]

Этот пример позволяет переводчикам переводить часть URL. Если «person» переведётся на «persona», регулярное выражение будет соответствовать persona/(?P<pk>\d+)/$, например persona/5/.

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".

`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 или именем часовой зоны.

deactivate() [source]: Снимает установку текущей часовой зоны.

override(timezone) [source]

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

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

localtime(value=None, timezone=None) [source]

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

Если value опущено, по умолчанию используется now().

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

Изменено в Django 1.11:

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

localdate(value=None, timezone=None) [source]

Новое в Django 1.11.

Использует localtime() для преобразования осознанного datetime в date() в другой часовой зоне, по умолчанию в текущую часовую зону.

Если value опущено, по умолчанию используется now().

Эта функция не работает с неосознанными датами и временем.

now() [source]

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

Если USE_TZ равно False, это будет неосознанное время (т. е. время без связанной часовой зоны), представляющее текущее время в локальной часовой зоне системы.
Если USE_TZ равно True, это будет осознанное время, представляющее текущее время в 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.AmbiguousTimeError возникает, если вы пытаетесь сделать value осознанным во время перехода DST, когда одно и то же время происходит дважды (при возвращении из DST). Установка is_dst в True или False позволит избежать исключения, выбрав, является ли время до перехода или после него.

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

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

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

ngettext_lazy(singular, plural, number) [source]

ungettext_lazy(singular, plural, number) [source]

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

Аналогично вышеуказанным функциям, но с использованием отложенного выполнения.

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

string_concat(*strings): Устарело начиная с версии 1.11: Используйте django.utils.text.format_lazy() вместо этого. string_concat(*strings) можно заменить на format_lazy('{}' * len(strings), *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()).

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: Ключ сессии, в котором хранится активный язык для текущей сессии.

END_OF_DOCUMENT_MARKER

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