Утилиты Django¶

django.utils.cache¶

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

For information on the Vary header, see 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)[исходный код]¶

Adds (or updates) the Vary header in the given HttpResponse object. newheaders is a list of header names that should be in Vary. If headers contains an asterisk, then Vary header will consist of a single asterisk '*', according to RFC 9110#section-12.5.5. Otherwise, existing headers in Vary aren’t removed.

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: The name parameter is deprecated and will be removed in Django 5.0 as it’s unnecessary as of Python 3.6.

class classproperty(method=None)[исходный код]¶

Подобно :py<<<0 >>>, декоратор <<<1 >>> преобразует результат метода с одним аргументом <<<2 >>> в свойство, доступ к которому можно получить непосредственно из класса.

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

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

Similar to escape(), except that it doesn’t operate on preescaped strings, so it will not double escape.

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

Это похоже на str.format(), за исключением того, что оно подходит для построения HTML-фрагментов. Все args и kwargs проходят через 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)
)

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

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

Changed in Django Development version:

В старых версиях требовался аргумент 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".

Если вы ищете более надежное решение, обратите внимание на библиотеку bleach Python.

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

Formats the time to match the RFC 1123#section-5.2.14 date format as specified by 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.

Конструирует значение заголовка HTTP Content-Disposition из заданного 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: When using pytz, the pytz.AmbiguousTimeError exception is raised if you try to make value aware during a DST transition where the same time occurs twice (when reverting from DST). Setting is_dst to True or False will avoid the exception by choosing if the time is pre-transition or post-transition respectively.

When using pytz, the pytz.NonExistentTimeError exception is raised if you try to make value aware during a DST transition such that the time never occurred. For example, if the 2:00 hour is skipped during a DST transition, trying to make 2:30 aware in that time zone will raise an exception. To avoid that you can use is_dst to specify how make_aware() should interpret such a nonexistent time. If is_dst=True then the above time would be interpreted as 2:30 DST time (equivalent to 1:30 local time). Conversely, if is_dst=False the time would be interpreted as 2:30 standard time (equivalent to 3:30 local time).

Параметр 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.