Утилиты Django¶

django.utils.cache¶

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

Информацию о заголовке Vary см. в разделе RFC 9110#section-12.5.5.

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

Например, промежуточное ПО internationalization должно различать кэши по заголовку Accept-language.

patch_cache_control(response, **kwargs)[исходный код]¶

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

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

get_max_age(response)[исходный код]¶

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

patch_response_headers(response, cache_timeout=None)[исходный код]¶

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

• Expires
• Cache-Control

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

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

add_never_cache_headers(response)[исходный код]¶

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

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

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

patch_vary_headers(response, newheaders)[исходный код]¶

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

get_cache_key(request, key_prefix=None, method='GET', cache=None)[исходный код]¶

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

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

learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None)[исходный код]¶

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

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

django.utils.dateparse¶

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

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

parse_date(value)[исходный код]¶

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

parse_time(value)[исходный код]¶

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

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

parse_datetime(value)[исходный код]¶

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

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

parse_duration(value)[исходный код]¶

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

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

django.utils.decorators¶

method_decorator(decorator, name='')[исходный код]¶

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

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

Пример использования см. в decorating class based views.

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

Помечает промежуточное ПО как synchronous-only. (По умолчанию в Django, но это позволяет вам защититься на будущее, если значение по умолчанию изменится в будущем релизе).

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

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

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

Помечает промежуточное ПО как sync and async compatible, что позволяет избежать преобразования запросов. Для использования этого декоратора необходимо реализовать определение текущего типа запроса. Подробности смотрите в разделе asynchronous middleware documentation.

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(), за исключением того, что экземпляры lazy разрешаются в строки, а не сохраняются как объекты lazy.

Если 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, за исключением того, что экземпляры lazy разрешаются в байтовые строки, а не сохраняются как объекты lazy.

Если strings_only равно True, не конвертируйте (некоторые) нестрокоподобные объекты.

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

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

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

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

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

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

Это алгоритм из раздела 3.2 книги RFC 3987#section-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="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

django.utils.functional¶

class cached_property(func, name=None)[исходный код]¶

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

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

# the model
class Person(models.Model):
    def friends(self):
        # expensive computation
        ...
        return friends


# in the view:
if person.friends():
    ...

И в шаблоне у вас будет:

{% for friend in person.friends %}

Здесь friends() будет вызван дважды. Поскольку экземпляр person в представлении и шаблоне один и тот же, украшение метода friends() методом @cached_property позволяет избежать этого:

from django.utils.functional import cached_property


class Person(models.Model):
    @cached_property
    def friends(self):
        ...

Обратите внимание, что поскольку метод теперь является свойством, в коде Python к нему нужно будет обращаться соответствующим образом:

# in the view:
if person.friends:
    ...

Кэшированное значение может рассматриваться как обычный атрибут экземпляра:

# clear it, requiring re-computation next time it's called
del person.friends  # or delattr(person, "friends")

# set a value manually, that will persist on the instance until cleared
person.friends = ["Huckleberry Finn", "Tom Sawyer"]

Из-за того, как работает descriptor protocol, использование 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

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

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 не экранируется, но все остальные аргументы и kwargs проходят через 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() для значений.

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

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

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

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

json_script(value, element_id=None, encoder=None)[исходный код]¶

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

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

Энкодер, по умолчанию :class:django.core.serializers.json.DjangoJSONEncoder, будет использоваться для сериализации данных. Смотрите JSON сериализация для получения дополнительных сведений об этом сериализаторе.

Changed in Django 4.1:

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

Changed in Django 4.2:

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

strip_tags(value)[исходный код]¶

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

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

Например:

strip_tags(value)

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

Если вы ищете более надежное решение, рассмотрите возможность использования сторонних средств санации HTML.

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

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

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

django.utils.http¶

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

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

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

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

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

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

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

New in Django 4.2.

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

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 slug by:

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¶

utc¶

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

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

get_fixed_timezone(offset)[исходный код]¶

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

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

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

Возвращает экземпляр tzinfo, который представляет default time zone.

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

Возвращает имя default time zone.

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

Возвращает экземпляр tzinfo, который представляет current time zone.

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

Возвращает имя current time zone.

activate(timezone)[исходный код]¶

Устанавливает значение current time zone. Аргумент timezone должен быть экземпляром подкласса tzinfo или именем часового пояса.

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

Сбрасывает значение current time zone.

override(timezone)[исходный код]¶

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

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

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

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

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

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

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

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

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

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

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

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

• Если USE_TZ равно False, то это будет naive datetime (т.е. время без связанного часового пояса), которое представляет текущее время в локальном часовом поясе системы.
• Если USE_TZ равно True, это будет aware 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, то по умолчанию возвращается current time zone.

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

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

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

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

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

Возвращает наивный datetime, который представляет в timezone тот же момент времени, что и value, value являющийся осознанным datetime. Если timezone задано None, то по умолчанию возвращается current time zone.

django.utils.translation¶

Для полного обсуждения использования следующего смотрите translation documentation.

gettext(message)[исходный код]¶

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

pgettext(context, message)[исходный код]¶

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

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

gettext_lazy(message)¶

pgettext_lazy(context, message)¶

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

См. lazy translations documentation.

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

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

См. lazy translations documentation.

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

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

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

Деактивирует активный в данный момент объект перевода, так что дальнейшие _ вызовы будут снова разрешаться в объект перевода по умолчанию.

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

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

override(language, deactivate=False)[исходный код]¶

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

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

check_for_language(lang_code)[исходный код]¶

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

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

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

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

Возвращает раскладку BiDi выбранного языка:

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

get_language_from_request(request, check_path=False)[исходный код]¶

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

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

get_supported_language_variant(lang_code, strict=False)[исходный код]¶

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

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

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

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

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

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

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