Django Utils

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

`django.utils.cache`

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

Для получения информации о заголовке Vary см. RFC 9110#section-12.5.5.

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

Например, middleware для Accept-language потребуется различать кэши по заголовку Accept-language.

patch_cache_control(response, **kwargs)

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

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

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

patch_response_headers(response, cache_timeout=None)

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

Expires
Cache-Control

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

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

add_never_cache_headers(response)

Добавляет заголовок Expires к текущей дате и времени.

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

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

patch_vary_headers(response, newheaders): Добавляет (или обновляет) заголовок Vary в заданном объекте HttpResponse. newheaders - это список имён заголовков, которые должны быть в Vary Если в headers содержится звездочка, то заголовок Vary будет содержать единственную звездочку '*', в соответствии с RFC 9110#section-12.5.5. В противном случае существующие заголовки в Vary не удаляются.

get_cache_key(request, key_prefix=None, method='GET', cache=None)

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

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

learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None)

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

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

`django.utils.dateparse`

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

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

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

parse_time(value)

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

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

parse_datetime(value)

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

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

parse_duration(value)

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

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

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

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

sync_only_middleware(middleware) [source]: Помечает middleware как синхронный только. (По умолчанию в Django, но это позволяет вам подготовиться к будущим изменениям, если значение по умолчанию когда-либо изменится в будущей версии.)

async_only_middleware(middleware) [source]: Помечает middleware как асинхронный только. Django обернет его в асинхронную циклическую очередь, когда он вызывается из пути WSGI-запроса.

END_OF_DOCUMENT_MARKER

sync_and_async_middleware(middleware) [source]: Помечает миддлвейр как совместимый с синхронными и асинхронными запросами (совместимый с синхронными и асинхронными запросами), это позволяет избежать преобразования запросов. Вы должны реализовать определение типа текущего запроса, чтобы использовать этот декоратор. Подробнее см. в документации по асинхронному миддлвейру (документация по асинхронному миддлвейру).

`django.utils.encoding`

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

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

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

is_protected_type(obj) [source]

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

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

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

Аналогично smart_str(), за исключением того, что ленивые экземпляры разрешаются в строки, а не сохраняются как ленивые объекты.

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

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

iri_to_uri(iri) [source]

Преобразует часть Идентификатора ресурса с интернационализацией (IRI) в часть URI, подходящую для включения в URL.

Это алгоритм из раздела 3.1 RFC 3987#раздел-3.1, немного упрощённый, так как входной параметр предполагается строкой, а не произвольным потоком байтов.

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

uri_to_iri(uri) [source]

Преобразует идентификатор универсального ресурса в идентификатор ресурса с интернационализацией.

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

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

filepath_to_uri(path) [source]

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

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

Все параметры должны быть строками, за исключением categories, которое должно быть последовательностью строк.

add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs) [source]: Добавляет элемент в ленту. Все аргументы ожидают быть строками, за исключением pubdate и updateddate, которые являются объектами datetime.datetime, и 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.

`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]: Спецификация: RFC 4287

`django.utils.functional`

class cached_property(func, name=None) [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"]

Из-за того, как работает протокол дескриптора, использование del (или delattr) на экземпляре, к которому ещё не обращались, вызывает AttributeError.

Помимо потенциальных преимуществ производительности, @cached_property может гарантировать, что значение атрибута не изменится неожиданно в течение жизни экземпляра. Это может произойти с методом, вычисление которого основано на datetime.now(), или если изменение было сохранено в базе данных другим процессом в короткий промежуток времени между последующими вызовами метода на том же экземпляре.

Вы можете сделать кэшированные свойства методов. Например, если у вас был дорогой метод get_friends() и вы хотели позволить вызов без получения кэшированного значения, вы можете написать:

friends = cached_property(get_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

Устарело начиная с версии 4.1: Параметр name устарел и будет удален в Django 5.0, так как он не нужен начиная с Python 3.6.

class classproperty(method=None) [source]: Аналогично @classmethod, декоратор @classproperty преобразует результат метода с одним аргументом cls в свойство, к которому можно получить доступ непосредственно из класса.

keep_lazy(func, *resultclasses) [source]

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

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

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

Например:

from django.utils.functional import keep_lazy, keep_lazy_text


def fancy_utility_function(s, *args, **kwargs):
    # Do some conversion on string 's'
    ...


fancy_utility_function = keep_lazy(str)(fancy_utility_function)


# Or more succinctly:
@keep_lazy(str)
def fancy_utility_function(s, *args, **kwargs):
    ...

Декоратор keep_lazy() принимает несколько дополнительных аргументов (*args), определяющих тип(ы), которые может возвращать исходная функция. Частый случай использования — функции, возвращающие текст. Для них можно передать тип str в keep_lazy (или использовать декоратор keep_lazy_text(), описанный в следующем разделе).

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

keep_lazy_text(func) [source]

Сокращение для keep_lazy(str)(func).

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

from django.utils.functional import keep_lazy, keep_lazy_text


# Our previous example was:
@keep_lazy(str)
def fancy_utility_function(s, *args, **kwargs):
    ...


# Which can be rewritten as:
@keep_lazy_text
def fancy_utility_function(s, *args, **kwargs):
    ...

Модуль HTML-утилит

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

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

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

format_html(format_string, *args, **kwargs)

Это аналогично 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_str() для значений.

format_html_join(sep, format_string, args_generator)

Обёртка над 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))

json_script(value, element_id=None, encoder=None)

Экранирует все специальные символы HTML/XML с помощью их Unicode-экранирования, делая значение безопасным для использования в JavaScript. Также оборачивает закодированный JSON в тег <script>. Если параметр element_id не равен None, тегу <script> задаётся переданный идентификатор. Например:

>>> json_script({"hello": "world"}, element_id="hello-data")
'<script id="hello-data" type="application/json">{"hello": "world"}</script>'

Для сериализации данных будет использоваться encoder, по умолчанию django.core.serializers.json.DjangoJSONEncoder. Подробнее о сериализаторе см. в разделе Сериализация JSON.

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

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

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

Добавлен аргумент encoder.

strip_tags(value)

Пытается удалить всё, что похоже на тег 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()

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

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

Модуль HTTP-утилит

urlencode(query, doseq=False) [source]: Версия функции Python urllib.parse.urlencode(), которая может работать со значениями MultiValueDict и нестрокового типа.

http_date(epoch_seconds=None) [source]

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

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

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

content_disposition_header(as_attachment, filename) [source]: Новое в Django 4.2.

Строит значение HTTP-заголовка Content-Disposition из заданных filename в соответствии с RFC 6266. Возвращает None если as_attachment равно False и filename равно None, в противном случае возвращает строку, подходящую для HTTP-заголовка Content-Disposition.

base36_to_int(s) [source]: Преобразует строку в системе счисления с основанием 36 в целое число.

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

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

mark_safe(s) [source]

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

Может быть вызван несколько раз для одной строки.

Также может использоваться как декоратор.

Для построения фрагментов HTML обычно следует использовать django.utils.html.format_html().

Строка, помеченная как безопасная, снова станет небезопасной при модификации. Например:

>>> mystr = "<b>Hello World</b>   "
>>> mystr = mark_safe(mystr)
>>> type(mystr)
<class 'django.utils.safestring.SafeString'>

>>> mystr = mystr.strip()  # removing whitespace
>>> type(mystr)
<type 'str'>

`django.utils.text`

format_lazy(format_string, *args, **kwargs)

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

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

urlpatterns = [
    path(
        format_lazy("{person}/<int:pk>/", person=pgettext_lazy("URL", "person")),
        PersonDetailView.as_view(),
    ),
]

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

slugify(value, allow_unicode=False)

Преобразует строку в URL-слог, выполняя следующие действия:

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

Например:

>>> slugify(" Joel is a slug ")
'joel-is-a-slug'

Если требуется разрешить символы Юникода, передайте allow_unicode=True. Например:

>>> slugify("你好 World", allow_unicode=True)
'你好-world'

`django.utils.timezone`

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

Устарело начиная с версии 4.1: Это псевдоним для datetime.timezone.utc. Используйте datetime.timezone.utc напрямую.

get_fixed_timezone(offset)

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

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

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

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

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

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

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

deactivate(): Сбрасывает текущий часовой пояс.

override(timezone)

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

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

localtime(value=None, timezone=None)

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

Если value опущено, оно по умолчанию равно now().

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

END_OF_DOCUMENT_MARKER ```

localdate(value=None, timezone=None)

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

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

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

now()

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

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

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

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

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

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

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

Параметр is_dst не влияет при использовании реализаций часовых поясов, отличных от pytz.

Параметр is_dst устарел и будет удален в Django 5.0.

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

`django.utils.translation`

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

gettext(message): Переводит message и возвращает его в виде строки.

pgettext(context, message)

Переводит message с учётом context и возвращает его в виде строки.

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

gettext_lazy(message)

pgettext_lazy(context, message)

То же, что и неленивые версии выше, но с отложенным выполнением.

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

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

ngettext(singular, plural, number): Переводит singular и plural и возвращает соответствующую строку в зависимости от number.

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

ngettext_lazy(singular, plural, number)

npgettext_lazy(context, singular, plural, number)

То же, что и неленивые версии выше, но с отложенным выполнением.

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

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

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

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

override(language, deactivate=False)

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

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

check_for_language(lang_code): Проверяет, существует ли глобальный файл языка для данного кода языка (например, ‘fr’, ‘pt_BR’). Это используется для определения доступности языка, указанного пользователем.

get_language(): Возвращает текущий код языка. Возвращает None если переводы временно деактивированы (с помощью deactivate_all() или когда None передаётся в override()).

get_language_bidi()

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

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

get_language_from_request(request, check_path=False)

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

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

get_supported_language_variant(lang_code, strict=False)

Возвращает lang_code если оно есть в настройке LANGUAGES, возможно, выбирая более общий вариант. Например, 'es' возвращается, если lang_code равно 'es-ar' и 'es' есть в LANGUAGES, но 'es-ar' нет.

Если strict равно False (по умолчанию), может быть возвращён вариант, специфичный для страны, когда ни код языка, ни его общий вариант не найдены. Например, если только 'es-co' есть в LANGUAGES, то он возвращается для lang_codeов, таких как 'es' и 'es-ar'. Эти соответствия не возвращаются, если strict=True.

Вызывает LookupError если ничего не найдено.

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

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

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