Django Utils

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

`django.utils.cache`

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

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

В сущности, заголовок 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 9110#section-12.5.5. В противном случае существующие заголовки в Vary не удаляются.

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

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

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

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

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

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

`django.utils.dateparse`

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

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

parse_date(value): Парсит строку и возвращает datetime.date.

parse_time(value)

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

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

parse_datetime(value)

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

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

parse_duration(value)

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

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

`django.utils.decorators`

method_decorator(decorator, name='')

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

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

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

decorator_from_middleware(middleware_class)

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

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

decorator_from_middleware_with_args(middleware_class)

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

cache_page = decorator_from_middleware_with_args(CacheMiddleware)


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

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

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

END_OF_DOCUMENT_MARKER

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

`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, не преобразовывать (некоторые) объекты, не являющиеся строками.

iri_to_uri(iri)

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

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

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

uri_to_iri(uri)

Преобразует универсальный идентификатор ресурса (URI) в международный идентификатор ресурса (IRI).

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

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

filepath_to_uri(path)

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

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

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

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

`django.utils.feedgenerator`

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

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

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

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

get_tag_uri(url, date)

Создает TagURI.

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

`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) [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 в представлении и шаблоне одинаковый, применение декоратора @cached_property к методу friends() позволит избежать этого:

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

class classproperty(method=None) [source]: Аналогично @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, *args, **kwargs):
    # Do some conversion on string 's'
    ...


fancy_utility_function = keep_lazy(str)(fancy_utility_function)


# Or more succinctly:
@keep_lazy(str)
def fancy_utility_function(s, *args, **kwargs): ...

Декоратор keep_lazy() принимает несколько дополнительных аргументов (*args), определяющих тип(ы), которые может возвращать исходная функция. Частый случай использования — функции, возвращающие текст. Для них можно передать тип str в keep_lazy (или использовать декоратор keep_lazy_text(), описанный в следующем разделе).

Использование этого декоратора означает, что вы можете написать свою функцию и предположить, что вход — это обычная строка, а затем добавить поддержку ленивых объектов перевода в конце.

keep_lazy_text(func) [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, *args, **kwargs): ...


# Which can be rewritten as:
@keep_lazy_text
def fancy_utility_function(s, *args, **kwargs): ...

`django.utils.html`

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

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

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

format_html(format_string, *args, **kwargs)

Аналогично str.format(), но подходит для построения фрагментов HTML. Первый аргумент format_string не экранируется, но все остальные аргументы и ключевые слова передаются через conditional_escape() перед передачей в str.format(). Наконец, к выводу применяется mark_safe().

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

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

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

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

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

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

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

Устарело начиная с версии 5.0: Поддержка вызова format_html() без передачи аргументов или ключевых слов устарела.

format_html_join(sep, format_string, args_generator)

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

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

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

json_script(value, element_id=None, encoder=None)

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

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

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

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

Был добавлен аргумент encoder.

strip_tags(value)

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

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

Например:

strip_tags(value)

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

Если вам нужна более надежная задача, рассмотрите использование стороннего инструмента для очистки HTML.

html_safe()

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

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

`django.utils.http`

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

http_date(epoch_seconds=None) [source]

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

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

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

content_disposition_header(as_attachment, filename) [source]: Добавлено в Django 4.2.

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

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

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. Если «person» переведен на «persona», регулярное выражение будет совпадать с persona/(?P<pk>\d+)/$, например, persona/5/.

slugify(value, allow_unicode=False)

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

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

Например:

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

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

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

`django.utils.timezone`

get_fixed_timezone(offset)

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

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

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

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

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

END_OF_DOCUMENT_MARKER

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): Возвращает осознанное datetime, представляющее ту же точку во времени, что и value в timezone, value — неосознанная datetime. Если timezone установлено на None, оно по умолчанию устанавливается на текущую временную зону.

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): Извлекает объект перевода для данного языка и активирует его как текущий объект перевода для текущей нити.

END_OF_DOCUMENT_MARKER

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.

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