Django Utils

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

django.utils.cache

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

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

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

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

patch_cache_control(response, **kwargs) [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 результата — экземпляр datetime.timezone.

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

В более старых версиях атрибут 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.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"]

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

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

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

friends = cached_property(get_friends, name='friends')

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

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

Более старые версии Django требуют аргумент name для всех версий Python.

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

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

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

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

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

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

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 в целое число.

int_to_base36(i) [source]

Преобразует положительное целое число в строку в системе счисления с основанием 36.

urlsafe_base64_encode(s) [source]

Кодирует байтовую строку в строку base64 для использования в URL, удаляя любые trailing равные знаки.

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

В более ранних версиях возвращает байтовую строку вместо строки.

urlsafe_base64_decode(s) [source]

Декодирует закодированную строку base64, добавляя обратно любые trailing равные знаки, которые могли быть удалены.

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

В более ранних версиях s может быть байтовой строкой.

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

slugify(value, allow_unicode=False) [source]

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

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

Например:

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

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

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

Устаревшее с версии 2.2: Используйте datetime.timezone вместо этого.

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

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

make_naive(value, timezone=None) [source]

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

django.utils.translation

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

Префикс u у функций ниже происходит из различий в Python 2 между строками unicode и строками bytestring. Если ваш код не поддерживает 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]

Возвращает компоновку 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]

Новая функция в Django 2.1.

Возвращает 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.

LANGUAGE_SESSION_KEY

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