Django Utils

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

`django.utils.cache`

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

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

По существу, заголовок HTTP Vary определяет, какие заголовки должен учитывать кэш при построении своего ключа кэша. Запросы с одинаковым путем, но разным содержимым заголовков для заголовков, указанных в 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:

Expires
Cache-Control

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

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

add_never_cache_headers(response) [source]

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

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

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

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

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

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

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

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

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

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

`django.utils.dateparse`

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

Они принимают строки в форматах дат/времени ISO 8601 (или некоторых близких альтернатив) и возвращают объекты соответствующих классов из модуля Python’s datetime.
Они генерируют 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 результата является экземпляром datetime.timezone.

parse_duration(value) [source]

Разбирает строку и возвращает 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()).

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

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

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

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

`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#section-3.1, немного упрощённый, так как входной параметр предполагается строкой, а не произвольным потоком байтов.

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

uri_to_iri(uri) [source]

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

Это алгоритм из раздела 3.2 RFC 3987#section-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="https://www.poynter.org/tag/e-media-tidbits/",
...     description="A group blog by the sharpest minds in online media/journalism/publishing.",
...     language="en",
... )
>>> feed.add_item(
...     title="Hello",
...     link="https://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]: Возвращает дополнительные атрибуты для размещения в каждом элементе (т. е. элемент элемента/записи).

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

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) [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) для cached_property, который не был обращен, вызывает 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

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): ...

`django.utils.html`

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

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

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

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

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

В случае построения небольших фрагментов 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() для значений.

Устарело начиная с версии 5.0: Поддержка вызова format_html() без передачи аргументов или ключевых слов устарела.

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

json_script(value, element_id=None, encoder=None) [source]

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

strip_tags(value) [source]

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

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

Например:

strip_tags(value)

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

Если вам нужна более надёжная функция, рассмотрите использование стороннего инструмента для очистки HTML.

html_safe() [source]

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

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

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

END_OF_DOCUMENT_MARKER

content_disposition_header(as_attachment, filename) [source]: Создаёт значение заголовка 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. Если «человек» переведён на «персона», то регулярное выражение будет соответствовать persona/(?P<pk>\d+)/$, например, persona/5/.

slugify(value, allow_unicode=False) [source]

Преобразует строку в 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`

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 также пригоден в качестве декоратора функции.

END_OF_DOCUMENT_MARKER ```

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

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

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

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

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

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

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

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

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, оно по умолчанию использует текущий часовой пояс.

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

`django.utils.translation`

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

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

pgettext(context, message) [source]

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

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

gettext_lazy(message)

pgettext_lazy(context, message)

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

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

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

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

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

ngettext_lazy(singular, plural, number) [source]

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

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

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

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

END_OF_DOCUMENT_MARKER

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.

get_supported_language_variant(lang_code, strict=False) [source]

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

lang_code имеет максимальную допустимую длину 500 символов. LookupError возбуждается, если lang_code превышает этот предел, и strict равно True, или если нет обобщенного варианта и strict равно False.

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

Возбуждает LookupError, если ничего не найдено.

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

В более старых версиях значения lang_code длиной более 500 символов обрабатывались без возбуждения LookupError.

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

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

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