Django Utils

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

`django.utils.cache`

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

Сведения о заголовке Vary см. в RFC 7231#section-7.1.4.

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

Например, middleware локализации Accept-language потребовалось бы различать кэши по заголовку Accept-language.

patch_cache_control(response, **kwargs)

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

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

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

patch_response_headers(response, cache_timeout=None)

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

Expires
Cache-Control

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

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

add_never_cache_headers(response)

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

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

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

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

parse_datetime(value)

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

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

parse_duration(value)

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

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

`django.utils.decorators`

method_decorator(decorator, name='') [source]

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

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

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

decorator_from_middleware(middleware_class) [source]

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

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

decorator_from_middleware_with_args(middleware_class) [source]

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

cache_page = decorator_from_middleware_with_args(CacheMiddleware)

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

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

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

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

`django.utils.encoding`

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

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

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

is_protected_type(obj) [source]

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

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

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

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

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

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

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

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

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

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

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

iri_to_uri(iri) [source]

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

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

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

uri_to_iri(uri) [source]

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

Это алгоритм из раздела 3.2 RFC 3987#section-3.2.

Принимает URI в ASCII-байтах и возвращает строку с закодированным результатом.

filepath_to_uri(path) [source]

Преобразует путь к файлу в систему URI, подходящий для включения в URL. Предполагается, что путь — это либо байты UTF-8, либо строка, либо Path.

Этот метод кодирует определённые символы, которые обычно распознаются как специальные символы URI. Обратите внимание, что этот метод не кодирует символ ‘, так как он является допустимым символом в URI. Для получения дополнительной информации см. функцию encodeURIComponent() JavaScript.

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

escape_uri_path(path) [source]: Экранирует небезопасные символы из части пути Унифицированного идентификатора ресурса (URI).

`django.utils.feedgenerator`

Пример использования:

>>> from django.utils import feedgenerator
>>> feed = feedgenerator.Rss201rev2Feed(
...     title="Poynter E-Media Tidbits",
...     link="http://www.poynter.org/column.asp?id=31",
...     description="A group blog by the sharpest minds in online media/journalism/publishing.",
...     language="en",
... )
>>> feed.add_item(
...     title="Hello",
...     link="http://www.holovaty.com/test/",
...     description="Testing.",
... )
>>> with open('test.rss', 'w') as fp:
...     feed.write(fp, 'utf-8')

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

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

get_tag_uri(url, date) [source]

Создаёт TagURI.

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

`SyndicationFeed`

class SyndicationFeed [source]

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

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

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

num_items() [source]

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

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

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

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

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

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

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

`Enclosure`

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

`RssFeed`

class RssFeed(SyndicationFeed) [source]

`Rss201rev2Feed`

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

`RssUserland091Feed`

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

`Atom1Feed`

class Atom1Feed(SyndicationFeed) [source]: Спецификация: 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)

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

x = person.friends         # calls first time
y = person.get_friends()   # calls again
z = person.friends         # does not call
x is z                     # is True

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

class classproperty(method=None) [source]: Подобно @classmethod, декоратор @classproperty преобразует результат метода с одним аргументом cls в свойство, к которому можно получить доступ непосредственно из класса.

END_OF_DOCUMENT_MARKER

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) [source]: Возвращает заданный текст с амперсандом, кавычками и угловыми скобками, закодированными для использования в HTML. Входные данные сначала преобразуются в строку, а выходные данные содержат mark_safe().

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

format_html(format_string, *args, **kwargs) [source]

Это аналогично 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) [source]

Обёртка для 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) [source]

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

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

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

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

strip_tags(value) [source]

Пытается удалить всё, что похоже на тег 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() [source]

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

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

`django.utils.http`

urlencode(query, doseq=False) [source]: Версия функции Python urllib.parse.urlencode(), которая может работать с MultiValueDict и значениями, не являющимися строками.

http_date(epoch_seconds=None) [source]

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

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

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

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

END_OF_DOCUMENT_MARKER ```

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

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

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

`django.utils.module_loading`

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

import_string(dotted_path) [source]

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

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

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

from django.core.exceptions import ValidationError

`django.utils.safestring`

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

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

mark_safe(s) [source]

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

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

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

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

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

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

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

`django.utils.text`

format_lazy(format_string, *args, **kwargs)

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

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

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

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

slugify(value, allow_unicode=False) [source]

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

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

Например:

>>> 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, представляющий по умолчанию часовой пояс.

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

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

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

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

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

override(timezone)

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

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

localtime(value=None, timezone=None)

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

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

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

END_OF_DOCUMENT_MARKER

localdate(value=None, timezone=None)

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

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

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

now()

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

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

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

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

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

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

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

`django.utils.translation`

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

gettext(message) [source]: Переводит message и возвращает его как строку.

pgettext(context, message) [source]

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

Дополнительную информацию см. в разделе о контекстуальных маркерах.

gettext_lazy(message)

pgettext_lazy(context, message)

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

См. документацию по ленивым переводам.

gettext_noop(message) [source]: Помечает строки для перевода, но не переводит их сейчас. Это можно использовать для хранения строк в глобальных переменных, которые должны остаться на языке оригинала (потому что они могут использоваться внешне) и будут переведены позже.

ngettext(singular, plural, number) [source]: Переводит singular и plural и возвращает соответствующую строку на основе number.

npgettext(context, singular, plural, number) [source]: Переводит singular и plural и возвращает соответствующую строку на основе number и context.

ngettext_lazy(singular, plural, number) [source]

npgettext_lazy(context, singular, plural, number) [source]

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

См. документацию по ленивым переводам.

activate(language) [source]: Извлекает объект перевода для заданного языка и активирует его как текущий объект перевода для текущей потоковой нити.

END_OF_DOCUMENT_MARKER

deactivate() [source]: Деактивирует текущий активный объект перевода, чтобы дальнейшие вызовы _ ссылались на объект перевода по умолчанию.

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

override(language, deactivate=False) [source]

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

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

check_for_language(lang_code) [source]: Проверяет, существует ли глобальный файл языка для данного кода языка (например, «fr», «pt_BR»). Это используется для определения того, доступен ли предоставленный пользователем язык.

get_language() [source]: Возвращает текущий выбранный код языка. Возвращает None при временной деактивации переводов (с помощью deactivate_all() или когда None передаётся в override()).

get_language_bidi() [source]

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

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

get_language_from_request(request, check_path=False) [source]

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

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

get_supported_language_variant(lang_code, strict=False) [source]

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

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

Возбуждает исключение LookupError, если ничего не найдено.

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

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

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