Django Utils

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

django.utils.cache

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

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

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

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

patch_cache_control(response, **kwargs)

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

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

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

Добавлена поддержка нескольких имён полей в директиве no-cache.

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 к ответу, чтобы указать, что страница никогда не должна кэшироваться.

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

Была добавлена директива private.

patch_vary_headers(response, newheaders)

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

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

Была добавлена обработка звёздочки '*' в соответствии с RFC 7231#section-7.1.4.

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.

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

Добавлена поддержка разделителей запятых для миллисекунд.

parse_datetime(value)

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

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

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

Добавлена поддержка разделителей запятых для миллисекунд.

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 3.1:

Добавлена поддержка разделителей запятых для десятичных дробей в формате ISO 8601 и для формата "DD HH:MM:SS,uuuuuu".

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]

Новое в Django 3.1.

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

async_only_middleware(middleware) [source]

Новое в Django 3.1.

Помечает миддлварь как только асинхронный. Django обернёт его в асинхронную очередь событий, когда он будет вызван из пути WSGI-запроса.

sync_and_async_middleware(middleware) [source]

Новое в Django 3.1.

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

django.utils.encoding

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

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

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

is_protected_type(obj)

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

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

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

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

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

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

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

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

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

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

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

smart_text(s, encoding='utf-8', strings_only=False, errors='strict')

Устарело начиная с версии 3.0.

Псевдоним force_str() для обратной совместимости, особенно в коде, поддерживающем Python 2.

force_text(s, encoding='utf-8', strings_only=False, errors='strict')

Устарело начиная с версии 3.0.

Псевдоним force_str() для обратной совместимости, особенно в коде, поддерживающем Python 2.

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. Для получения дополнительных сведений см. функцию encodeURIComponent() JavaScript.

Возвращает ASCII-строку, содержащую закодированный результат.

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

Добавлена поддержка pathlib.Path path.

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 Weblog 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()

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

add_root_elements(handler)

Добавляет элементы в корневой элемент (т. е. ленты/канала). Вызывается из 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 аргументом в виде свойства. Кэшированный результат сохраняется до тех пор, пока существует экземпляр, поэтому если экземпляр передаётся, а функция вызывается повторно, возвращается кэшированный результат.

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

# 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, name='friends')

Аргумент name необходим только для поддержки Python < 3.6.

Хотя 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]

Новое в Django 3.1.

Аналогично @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().

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

В старых версиях ' преобразуется в его десятичный код ' вместо эквивалентного шестнадцатеричного кода '.

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)

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

http_date(epoch_seconds=None)

Форматирует время в соответствии с форматом даты 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)

Преобразует строку в системе счисления по основанию 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) [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-сленг, выполнив:

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

Например:

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

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

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

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() вместо этого.

localdate(value=None, timezone=None)

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

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

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

now()

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

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

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

Исключение 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 по местному времени).

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

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

to_locale(language)

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

templatize(src)

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

LANGUAGE_SESSION_KEY

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

Устарело начиная с версии 3.0: Язык больше не будет храниться в сессии в Django 4.0. Используйте cookie LANGUAGE_COOKIE_NAME вместо этого.