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

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

get_cache_key(request, key_prefix=None, method='GET', cache=None)

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

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

learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None)

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

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

`django.utils.dateparse`

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

Они принимают строки в форматах дат/времени ISO 8601 (или некоторых близких альтернативах) и возвращают объекты из соответствующих классов в модуле 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]

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

Предполагается, что промежуточное ПО совместимо со старым стилем 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)

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

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

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

uri_to_iri(uri)

Преобразует Uniform Resource Identifier в Internationalized Resource Identifier.

Это алгоритм из раздела 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): Экранирует небезопасные символы из части пути Uniform Resource Identifier (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): Возвращает дополнительные атрибуты для каждого элемента (т. е. элемента записи/элемента).

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

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

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

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

`Enclosure`

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

`RssFeed`

class RssFeed(SyndicationFeed)

`Rss201rev2Feed`

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

`RssUserland091Feed`

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

`Atom1Feed`

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

`django.utils.functional`

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

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

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

# the model
class Person(models.Model):

    def friends(self):
        # expensive computation
        ...
        return friends

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

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

{% for friend in person.friends %}

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

from django.utils.functional import cached_property

class Person(models.Model):

    @cached_property
    def friends(self):
        ...

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

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

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

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

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

Из-за того, как работает протокол дескриптора, использование del (или delattr) для cached_property, который ещё не был вызван, вызовет AttributeError.

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

Можно создавать кэшированные свойства для методов. Например, если у вас есть дорогостоящий метод get_friends() и вы хотите позволить вызывать его без извлечения кэшированного значения, вы можете написать:

friends = cached_property(get_friends, 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), которые принимают строку в качестве первого аргумента и что-то с ней делают. Эти функции используются фильтрами шаблонов, а также напрямую в других фрагментах кода.

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

В таких случаях используйте декоратор 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, чтобы использовать его механизм автоматической обработки escape, используя утилиты в django.utils.safestring, где это уместно. Этот модуль предоставляет некоторые дополнительные утилиты низкого уровня для экранирования HTML.

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

conditional_escape(text): Аналогично escape(), за исключением того, что она не работает с предварительно экранированными строками, поэтому не будет двойного экранирования.

format_html(format_string, *args, **kwargs)

Это аналогично str.format(), за исключением того, что оно подходит для построения фрагментов HTML. Все аргументы и ключевые слова передаются через conditional_escape() перед передачей в str.format().

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

Итак, вместо написания:

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

Вы должны вместо этого использовать:

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

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

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

format_html_join(sep, format_string, args_generator)

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

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

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

strip_tags(value)

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

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

Например:

strip_tags(value)

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

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

html_safe()

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

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

`django.utils.http`

urlencode(query, doseq=False): Версия функции 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. Если «человек» переведётся как «личность», то регулярное выражение найдёт persona/(?P<pk>\d+)/$, например, persona/5/.

slugify(value, allow_unicode=False)

Преобразует строку в URL-слаг, выполнив следующие действия:

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

Например:

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

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

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

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

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

`django.utils.timezone`

utc: tzinfo объект, представляющий UTC.

get_fixed_timezone(offset)

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

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

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

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

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

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

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

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

override(timezone)

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

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

localtime(value=None, timezone=None)

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

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

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

localdate(value=None, timezone=None)

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

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

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

now()

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

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

При использовании 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.

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

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

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