Django Utils

django.utils.cache

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

Для получения информации о заголовке Vary см. RFC 9110 Раздел 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 Раздел 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 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()).

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 Раздел 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. См. функцию encodeURIComponent() JavaScript для получения дополнительной информации.

Возвращает строку 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

django.utils.functional

class cached_property(func) [source]

Декоратор @cached_property кэширует результат метода с единственным аргументом self как свойство. Кэшированный результат сохраняется до тех пор, пока существует экземпляр, поэтому если экземпляр передаётся и функция вызывается повторно, будет возвращено кэшированное значение.

Рассмотрим типичный случай, когда представление (view) может вызвать метод модели для выполнения вычислений, прежде чем поместить экземпляр модели в контекст, где шаблон может вызвать метод ещё раз:

# 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
person.__dict__.pop("friends", None)

# 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 должен быть итератором, который возвращает аргументы для передачи в format_html(), либо последовательности позиционных аргументов, либо отображения ключевых аргументов.

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

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

Или словари могут использоваться для ключевых аргументов:

format_html_join(
    "\n",
    '<li data-id="{id}">{id} {title}</li>',
    ({"id": b.id, "title": b.title} for b in books),
)

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

Была добавлена поддержка отображений в args_generator.

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

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

>>> 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 как безопасный, не экранируя его сначала, например, с помощью 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, раздел 5.2.14, указанным в HTTP RFC 9110, раздел 5.6.7.

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

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

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. Если «person» переведётся на «persona», регулярное выражение будет соответствовать persona/(?P<pk>\d+)/$, например, persona/5/.

slugify(value, allow_unicode=False) [source]

Преобразует строку в URL-слаг путём:

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

Например:

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

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

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, это будет неявное время (т.е. время без связанного часового пояса), представляющее текущее время в системном локальном часовом поясе.
• Если 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) [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]

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

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]

Возвращает биди-формат выбранного языка:

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