Django Utils

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

django.utils.cache

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

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

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

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

patch_cache_control(response, **kwargs) [source]

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

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

get_max_age(response) [source]

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

patch_response_headers(response, cache_timeout=None) [source]

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

• Expires
• Cache-Control

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

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

add_never_cache_headers(response) [source]

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

patch_vary_headers(response, newheaders) [source]

Добавляет (или обновляет) заголовок Vary в заданном объекте HttpResponse. newheaders — это список имён заголовков, которые должны быть в Vary. Существующие заголовки в Vary не удаляются.

get_cache_key(request, key_prefix=None) [source]

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

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

learn_cache_key(request, response, cache_timeout=None, key_prefix=None) [source]

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

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

django.utils.dateparse

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

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

parse_date(value) [source]

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

parse_time(value) [source]

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

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

parse_datetime(value) [source]

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

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

parse_duration(value) [source]

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

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

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

Добавлена поддержка формата интервалов PostgreSQL.

django.utils.decorators

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

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

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

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

decorator_from_middleware(middleware_class) [source]

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

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

decorator_from_middleware_with_args(middleware_class) [source]

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

cache_page = decorator_from_middleware_with_args(CacheMiddleware)

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

django.utils.encoding

python_2_unicode_compatible() [source]

Декоратор, который определяет методы __unicode__ и __str__ под Python 2. Под Python 3 он ничего не делает.

Для поддержки Python 2 и 3 с одним кодовым основанием, определите метод __str__, возвращающий текст (используйте six.text_type(), если вы выполняете некоторое преобразование) и примените этот декоратор к классу.

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

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

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

is_protected_type(obj) [source]

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

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

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

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

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

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

Псевдоним smart_text(). Эта функция возвращает str или ленивую строку.

Например, это подходит для записи в sys.stdout.

Псевдоним smart_bytes() в Python 2 (в более старых версиях Django, которые его поддерживают).

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

Псевдоним force_text(). Эта функция всегда возвращает str.

Псевдоним force_bytes() в Python 2 (в более старых версиях Django, которые его поддерживают).

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 байтами, либо строкой.

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

Возвращает строку 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 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) [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]

Спецификация: https://tools.ietf.org/html/rfc4287

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"]

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

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

friends = cached_property(get_friends, name='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

Предупреждение

cached_property не работает должным образом с изменённым именем, если не передано name в форме _Class__attribute:

__friends = cached_property(get_friends, name='_Person__friends')

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_text() для значений.

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

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

cookie_date(epoch_seconds=None) [source]

Устарело начиная с версии 2.1: Используйте http_date() вместо этого, который следует последним RFC.

Форматирует время для обеспечения совместимости со стандартом куки Netscape.

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

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

http_date(epoch_seconds=None) [source]

Форматирует время в соответствии с форматом даты RFC 1123, как указано в 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 в целое число.

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

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

class SafeText [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.SafeText'>

>>> 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) [source]

Преобразует строку в URL-слог следующим образом:

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

Например:

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

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

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

django.utils.timezone

utc

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

class FixedOffset(offset=None, name=None) [source]

Подкласс tzinfo, моделирующий фиксированный смещение от UTC. offset — целое число минут, на восток от UTC.

get_fixed_timezone(offset) [source]

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

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

get_default_timezone() [source]

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

get_default_timezone_name() [source]

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

get_current_timezone() [source]

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

get_current_timezone_name() [source]

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

activate(timezone) [source]

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

deactivate() [source]

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

override(timezone) [source]

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

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

localtime(value=None, timezone=None) [source]

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

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

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

localdate(value=None, timezone=None) [source]

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

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

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

now() [source]

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

• Если USE_TZ равно False, это будет неявный datetime (то есть datetime без связанной временной зоны), представляющий текущее время в локальной временной зоне системы.
• Если USE_TZ равно True, это будет явный datetime, представляющий текущее время в UTC. Обратите внимание, что now() всегда возвращает время в UTC независимо от значения TIME_ZONE; вы можете использовать localtime() для получения времени в текущей временной зоне.

is_aware(value) [source]

Возвращает True если value явный, False если он неявный. Эта функция предполагает, что value является datetime.

is_naive(value) [source]

Возвращает True если value неявный, False если он явный. Эта функция предполагает, что value является datetime.

make_aware(value, timezone=None, is_dst=None) [source]

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

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

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

make_naive(value, timezone=None) [source]

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

django.utils.translation

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

Префикс u у функций ниже происходит из различий в Python 2 между unicode и bytestrings. Если ваш код не поддерживает Python 2, используйте функции без u.

gettext(message) [source]

ugettext(message)

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

pgettext(context, message) [source]

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

Для получения дополнительной информации см. маркеры контекста.

gettext_lazy(message)

ugettext_lazy(message)

pgettext_lazy(context, message)

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

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

gettext_noop(message) [source]

ugettext_noop(message)

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

ngettext(singular, plural, number) [source]

ungettext(singular, plural, number)

Переводит singular и plural и возвращает соответствующую строку на основе number.

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

Переводит singular и plural и возвращает соответствующую строку на основе number и context.

ngettext_lazy(singular, plural, number) [source]

ungettext_lazy(singular, plural, number)

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

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

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

activate(language) [source]

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

deactivate() [source]

Деактивирует текущий активный объект перевода, чтобы дальнейшие вызовы _ выполняли разрешение по отношению к объекту перевода по умолчанию.

deactivate_all() [source]

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

override(language, deactivate=False) [source]

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

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

check_for_language(lang_code) [source]

Проверяет наличие глобального файла языка для данного кода языка (например, ‘fr’, ‘pt_BR’). Это используется для определения доступности языка, указанного пользователем.

get_language() [source]

Возвращает код текущего выбранного языка. Возвращает None, если переводы временно деактивированы (с помощью deactivate_all() или при передаче None в override()).

get_language_bidi() [source]

Возвращает двунаправленную компоновку выбранного языка:

• 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]

Доступно начиная с Django 2.1.

Возвращает 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) [source]

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

templatize(src) [source]

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

LANGUAGE_SESSION_KEY

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