Утилиты Django

django.utils.cache

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

Сведения о заголовке Vary см. в документе RFC 9110, раздел 12.5.5.

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

Например, промежуточному ПО для интернационализации необходимо различать кэши по заголовку 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, раздел 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 (или в некоторых близких форматах) и возвращают объекты соответствующих классов из модуля datetime Python.
• Они вызывают исключение 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='') [исходный код]

Преобразует декоратор функции в декоратор метода. Его можно использовать для декорирования методов или классов; во втором случае необходимо указать name — имя метода, который требуется декорировать.

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

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

decorator_from_middleware(middleware_class) [исходный код]

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

Предполагается, что промежуточное ПО совместимо со старым стилем Django 1.9 и более ранних версий (с методами вроде process_request(), process_exception() и process_response()).

decorator_from_middleware_with_args(middleware_class) [исходный код]

Подобно 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) [исходный код]

Помечает промежуточное ПО как только синхронное. (Это значение по умолчанию в Django, но такая пометка позволит подготовиться к будущим изменениям, если в последующих выпусках значение по умолчанию изменится.)

async_only_middleware(middleware) [исходный код]

Помечает промежуточное ПО как только асинхронное. При вызове из пути обработки запросов WSGI Django обернёт его в асинхронный цикл событий.

sync_and_async_middleware(middleware) [исходный код]

Помечает промежуточное ПО как совместимое с синхронным и асинхронным режимами, что позволяет избежать преобразования запросов. Чтобы использовать этот декоратор, необходимо реализовать определение типа текущего запроса. Подробности см. в документации по асинхронному промежуточному ПО.

django.utils.encoding

smart_str(s, encoding='utf-8', strings_only=False, errors='strict') [исходный код]

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

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

is_protected_type(obj) [исходный код]

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

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

force_str(s, encoding='utf-8', strings_only=False, errors='strict') [исходный код]

Подобна smart_str(), но ленивые экземпляры преобразуются в строки, а не сохраняются в виде ленивых объектов.

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

smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict') [исходный код]

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

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

force_bytes(s, encoding='utf-8', strings_only=False, errors='strict') [исходный код]

Подобна smart_bytes, но ленивые экземпляры преобразуются в байтовые строки, а не сохраняются в виде ленивых объектов.

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

iri_to_uri(iri) [исходный код]

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

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

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

uri_to_iri(uri) [исходный код]

Преобразует унифицированный идентификатор ресурса (URI) в интернационализированный идентификатор ресурса (IRI).

Это алгоритм из раздела 3.2 документа RFC 3987, раздел 3.2.

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

filepath_to_uri(path) [исходный код]

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

Этот метод кодирует некоторые символы, которые обычно распознаются как специальные символы URI. Обратите внимание, что метод не кодирует символ ‘, поскольку он допустим в URI. Дополнительные сведения см. в функции JavaScript encodeURIComponent().

Возвращает строку ASCII с закодированным результатом.

escape_uri_path(path) [исходный код]

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

get_tag_uri(url, date) [исходный код]

Создает TagURI.

См. статью Как создать хороший идентификатор в Atom.

django.utils.functional

class cached_property(func) [исходный код]

Декоратор @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
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) [исходный код]

Подобно @classmethod, декоратор @classproperty преобразует результат метода с одним аргументом cls в свойство, к которому можно обращаться непосредственно из класса.

keep_lazy(func, *resultclasses) [исходный код]

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) [исходный код]

Сокращенная запись для 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) [исходный код]

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

conditional_escape(text) [исходный код]

Работает подобно escape(), но не обрабатывает уже экранированные строки, поэтому двойного экранирования не происходит.

format_html(format_string, *args, **kwargs) [исходный код]

Работает подобно str.format(), но подходит для создания фрагментов HTML. Первый аргумент format_string не экранируется, но все остальные позиционные и именованные аргументы перед передачей в str.format() обрабатываются функцией conditional_escape(). В конце к результату применяется 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().

format_html_join(sep, format_string, args_generator) [исходный код]

Обертка над 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) [исходный код]

Заменяет все специальные символы 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) [исходный код]

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

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

Например:

strip_tags(value)

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

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

html_safe() [исходный код]

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

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

django.utils.http

urlencode(query, doseq=False) [исходный код]

Версия функции urllib.parse.urlencode() из Python, которая может обрабатывать MultiValueDict и значения, не являющиеся строками.

http_date(epoch_seconds=None) [исходный код]

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

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

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

content_disposition_header(as_attachment, filename) [исходный код]

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

base36_to_int(s) [исходный код]

Преобразует строку в системе счисления с основанием 36 в целое число.

int_to_base36(i) [исходный код]

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

urlsafe_base64_encode(s) [исходный код]

Кодирует байтовую строку в строку base64 для использования в URL-адресах, удаляя все завершающие знаки равенства.

urlsafe_base64_decode(s) [исходный код]

Декодирует строку в кодировке base64, добавляя обратно все завершающие знаки равенства, которые могли быть удалены.

django.utils.module_loading

Функции для работы с модулями Python.

import_string(dotted_path) [исходный код]

Импортирует модуль по пути с разделенными точками и возвращает атрибут или класс, указанный последним именем в пути. Если импорт завершится с ошибкой, вызывает 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 [исходный код]

Подкласс str, специально помеченный как «безопасный» (не требующий дополнительного экранирования) для вывода в HTML.

mark_safe(s) [исходный код]

Явно помечает строку как безопасную для вывода (в 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-слаг следующим образом:

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) [исходный код]

Возвращает экземпляр 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().

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

localdate(value=None, timezone=None) [исходный код]

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

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

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

now() [исходный код]

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

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

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

make_naive(value, timezone=None) [исходный код]

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

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() или если в override() передано значение None).

get_language_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' — нет.

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

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

Если ничего не найдено, вызывается исключение LookupError.

to_locale(language) [исходный код]

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

templatize(src) [исходный код]

Преобразует шаблон Django в формат, понятный для xgettext. Для этого теги перевода Django преобразуются в стандартные вызовы функции gettext.