Django Utils

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

`django.utils.cache`

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

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

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

Например, middleware для международной локализации должен различать кэши по заголовку 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): Добавляет заголовок Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private в ответ, чтобы указать, что страница никогда не должна кэшироваться.

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

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

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

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

decorator_from_middleware(middleware_class) [source]

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

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

decorator_from_middleware_with_args(middleware_class) [source]

Как decorator_from_middleware, но возвращает функцию, принимающую аргументы, которые нужно передать в middleware_class. Например, декоратор cache_page() создается из CacheMiddleware следующим образом:

cache_page = decorator_from_middleware_with_args(CacheMiddleware)

@cache_page(3600)
def my_view(request):
    pass

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

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

END_OF_DOCUMENT_MARKER

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

`django.utils.encoding`

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

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

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

is_protected_type(obj) [source]

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

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

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

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

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

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

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

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

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

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

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

iri_to_uri(iri) [source]

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

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

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

uri_to_iri(uri) [source]

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

Это алгоритм из раздела 3.2 RFC 3987#section-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="http://www.poynter.org/column.asp?id=31",
...     description="A group blog by the sharpest minds in online media/journalism/publishing.",
...     language="en",
... )
>>> feed.add_item(
...     title="Hello",
...     link="http://www.holovaty.com/test/",
...     description="Testing.",
... )
>>> with open('test.rss', 'w') as fp:
...     feed.write(fp, 'utf-8')

Для упрощения выбора генератора используйте feedgenerator.DefaultFeed, который в данный момент Rss201rev2Feed

Определения различных версий RSS см.: https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss

get_tag_uri(url, date)

Создает TagURI.

См. https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id

`SyndicationFeed`

class SyndicationFeed

Базовый класс для всех лент новостей. Подклассы должны предоставлять 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)

Инициализирует ленту заданным словарем метаданных, которые применяются ко всей ленте.

Любые дополнительные ключевые аргументы, которые вы передадите в __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): Добавляет элемент в ленту. Все аргументы, кроме pubdate и updateddate, которые являются datetime.datetime объектами, а также enclosures, который является списком Enclosure экземпляров, ожидаются как строки.

num_items()

root_attributes(): Возвращает дополнительные атрибуты для корневого (т.е. feed/channel) элемента. Вызывается из write().

add_root_elements(handler): Добавляет элементы в корневой (т.е. feed/channel) элемент. Вызывается из write().

item_attributes(item): Возвращает дополнительные атрибуты для каждого элемента (т.е. item/entry).

add_item_elements(handler, item): Добавляет элементы в каждый элемент (т.е. item/entry).

write(outfile, encoding): Выводит ленту в заданной кодировке в outfile, что является объектом типа файла. Подклассы должны переопределять этот метод.

writeString(encoding): Возвращает ленту в заданной кодировке как строку.

latest_post_date(): Возвращает самую последнюю pubdate или updateddate для всех элементов в ленте. Если ни один из элементов не имеет этих атрибутов, возвращает текущую дату/время UTC.

`Enclosure`

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

`RssFeed`

class RssFeed(SyndicationFeed)

`Rss201rev2Feed`

class Rss201rev2Feed(RssFeed): Спецификация: https://cyber.harvard.edu/rss/rss.html

`RssUserland091Feed`

class RssUserland091Feed(RssFeed): Спецификация: http://backend.userland.com/rss091

`Atom1Feed`

class Atom1Feed(SyndicationFeed): Спецификация: RFC 4287

`django.utils.functional`

class cached_property(func, name=None) [source]

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

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

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

Декоратор 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, ...):
    ...

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

`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. Все аргументы и ключевые аргументы передаются через conditional_escape() перед передачей в str.format().

В случае построения небольших фрагментов HTML эта функция предпочтительнее интерполяции строк с использованием % или str.format() напрямую, потому что она применяет экранирование ко всем аргументам — точно так же, как система шаблонов применяет экранирование по умолчанию.

Таким образом, вместо написания:

mark_safe("%s <b>%s</b> %s" % (
    some_html,
    escape(some_text),
    escape(some_other_text),
))

Следует использовать:

format_html("{} <b>{}</b> {}",
    mark_safe(some_html),
    some_text,
    some_other_text,
)

Это имеет преимущество, что вам не нужно применять escape() к каждому аргументу и не возникнет ошибки и уязвимости XSS, если вы забудете один.

Обратите внимание, что хотя эта функция использует str.format() для интерполяции, некоторые форматы, предоставляемые str.format() (например, форматирование чисел), не будут работать, так как все аргументы передаются через conditional_escape(), которая (в конечном итоге) вызывает force_str() для значений.

format_html_join(sep, format_string, args_generator)

Оборачивает format_html(), для общего случая группы аргументов, которые нужно отформатировать с использованием одной и той же строки формата, а затем объединить с помощью sep. sep также передаётся через conditional_escape().

args_generator должен быть итератором, возвращающим последовательность args, которые будут переданы format_html(). Например:

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

strip_tags(value)

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

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

Например:

strip_tags(value)

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

Если вам нужна более надёжная функция, взгляните на Python-библиотеку bleach.

html_safe()

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

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

`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 7231#section-7.1.1.1.

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

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

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

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

urlsafe_base64_encode(s) [source]: Кодирует байтовую строку в строку base64 для использования в URL, удаляя любые хвостовые знаки равенства.

urlsafe_base64_decode(s) [source]: Декодирует закодированную строку base64, добавляя обратно любые хвостовые знаки равенства, которые могли быть удалены.

`django.utils.module_loading`

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

import_string(dotted_path) [source]

Импортирует путь к модулю с точками и возвращает атрибут/класс, обозначенный последним именем в пути. Вызывает ImportError, если импорт не удался. Например:

from django.utils.module_loading import import_string
ValidationError = import_string('django.core.exceptions.ValidationError')

эквивалентно:

from django.core.exceptions import ValidationError

`django.utils.safestring`

Функции и классы для работы с «безопасными строками»: строки, которые могут быть отображены безопасно без дальнейшего экранирования в HTML. Отметка чего-либо как «безопасной строки» означает, что производитель строки уже преобразовал символы, которые не должны интерпретироваться движком HTML (например, ‘<’) в соответствующие сущности.

class SafeString [source]: Подкласс str, который был специально помечен как «безопасный» (не требует дальнейшего экранирования) для целей вывода HTML.

mark_safe(s) [source]

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

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

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

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

Пометенная как безопасная строка станет небезопасной снова, если будет изменена. Например:

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

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

`django.utils.text`

format_lazy(format_string, *args, **kwargs)

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

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

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

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

slugify(value, allow_unicode=False)

Преобразует строку в URL-слэг, выполняя:

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

Например:

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

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

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

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

В более старых версиях начальные и конечные дефисы и символы подчеркивания не удалялись.

`django.utils.timezone`

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

get_fixed_timezone(offset)

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

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

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

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

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

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

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

deactivate(): Снимает установку текущего часового пояса.

override(timezone)

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

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

localtime(value=None, timezone=None)

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

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

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

END_OF_DOCUMENT_MARKER

localdate(value=None, timezone=None)

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

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

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

now()

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

Если USE_TZ равно False, это будет неявное значение 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, is_dst=None): Возвращает datetime с учетом часового пояса, представляющий ту же точку времени, что и value в timezone, value — это неявное datetime. Если timezone установлено на None, используется текущий часовой пояс.

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

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

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

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

make_naive(value, timezone=None): Возвращает неявное datetime, которое представляет в timezone ту же точку времени, что и value, value — явное datetime. Если timezone установлено на 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() или когда None передаётся в override()).

get_language_bidi()

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

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

get_language_from_request(request, check_path=False)

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

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

get_supported_language_variant(lang_code, strict=False)

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

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

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

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

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

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