Django Utils

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

`django.utils.cache`

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

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

Изменено в Django 1.8.8:
В более ранних версиях отправлялся Cache-Control: max-age=0. Это не всегда надёжно предотвращало кэширование во всех браузерах.

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`

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

Они поднимают 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).

`django.utils.decorators`

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

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

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

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

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

Добавлена возможность декорации классов, параметр name, и возможность для decorator принимать список/кортеж декораторских функций.

decorator_from_middleware(middleware_class) [source]

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

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

decorator_from_middleware_with_args(middleware_class) [source]

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

cache_page = decorator_from_middleware_with_args(CacheMiddleware)

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

`django.utils.encoding`

python_2_unicode_compatible() [source]

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

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

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

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

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

smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict'): Историческое название smart_text(). Доступно только в Python 2.

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

force_unicode(s, encoding='utf-8', strings_only=False, errors='strict'): Историческое название force_text(). Доступно только в Python 2.

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_bytes() в Python 2 и smart_text() в Python 3. Эта функция возвращает байтовую строку или ленивую строку.

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

force_str(s, encoding='utf-8', strings_only=False, errors='strict'): Псевдоним force_bytes() в Python 2 и force_text() в Python 3. Эта функция всегда возвращает строку.

iri_to_uri(iri) [source]

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

Это алгоритм из раздела 3.1 RFC 3987#section-3.1. Однако, поскольку мы предполагаем, что входной параметр уже является UTF-8 или unicode, мы можем немного упростить процедуру.

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

uri_to_iri(uri) [source]

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

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

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

filepath_to_uri(path) [source]

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

Этот метод закодирует определенные символы, которые обычно считаются специальными символами для 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.

Все параметры должны быть объектами Unicode, за исключением categories, которое должно быть последовательностью объектов Unicode.

add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs) [source]: Добавляет элемент в ленту. Все аргументы должны быть объектами Python unicode за исключением pubdate и updateddate, которые являются объектами datetime.datetime, enclosure, который является экземпляром Enclosure, и enclosures, которое является списком экземпляров Enclosure.

Устарело начиная с версии 1.9: Ключевой аргумент enclosure устарел в пользу нового ключевого аргумента enclosures, который принимает список объектов Enclosure.

num_items() [source]

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

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

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

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

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

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

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

`Enclosure`

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

`RssFeed`

class RssFeed(SyndicationFeed) [source]

`Rss201rev2Feed`

class Rss201rev2Feed(RssFeed) [source]: Спецификация: https://cyber.law.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(object, name) [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 может избежать этого:

from django.utils.functional import cached_property

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

Обратите внимание, что поскольку метод теперь является свойством, в коде 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

allow_lazy(func, *resultclasses) [source]: Устарело начиная с версии 1.10.

Действует как keep_lazy(), за исключением того, что не может использоваться в качестве декоратора.

END_OF_DOCUMENT_MARKER

keep_lazy(func, *resultclasses) [source]

Новая в Django 1.10.

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

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

В таких случаях используйте декоратор django.utils.functional.keep_lazy(). Он изменяет функцию таким образом, что если она вызывается с объектом ленивого перевода в качестве одного из аргументов, вычисление функции откладывается до тех пор, пока он не потребуется для преобразования в строку.

Например:

from django.utils import six
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(six.text_type)(fancy_utility_function)

# Or more succinctly:
@keep_lazy(six.text_type)
def fancy_utility_function(s, ...):
    ...

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

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

keep_lazy_text(func) [source]

Новая в Django 1.10.

Сокращение для keep_lazy(six.text_type)(func).

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

from django.utils import six
from django.utils.functional import keep_lazy, keep_lazy_text

# Our previous example was:
@keep_lazy(six.text_type)
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. Вход сначала передается через force_text(), а выход имеет применённый 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__() в декорируемом классе, оборачивая __unicode__() (Python 2) или __str__() (Python 3) в mark_safe(). Убедитесь, что метод __unicode__() или __str__() действительно возвращает текст, не требующий эскейпинга HTML.

`django.utils.http`

urlquote(url, safe='/') [source]: Версия функции Python urllib.quote() , которая может работать со строками unicode. URL сначала кодируется в UTF-8, а затем цитируется. Возвращаемая строка может безопасно использоваться в качестве аргумента в последующем вызове iri_to_uri() без возникновения двойного цитирования. Использует ленивое выполнение.

urlquote_plus(url, safe='') [source]: Версия функции Python urllib.quote_plus(), которая может работать со строками unicode. URL сначала кодируется в UTF-8, а затем цитируется. Возвращаемая строка может безопасно использоваться в качестве аргумента в последующем вызове iri_to_uri() без возникновения двойного цитирования. Использует ленивое выполнение.

urlencode(query, doseq=0) [source]: Версия функции Python urllib.urlencode(), которая может работать со строками unicode. Параметры сначала преобразуются в строки, закодированные в UTF-8, а затем кодируются обычным способом.

cookie_date(epoch_seconds=None) [source]

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

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

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

END_OF_DOCUMENT_MARKER

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 в целое число. В Python 2 результат гарантированно будет int, а не long.

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

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

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

Загрузка модулей Django

Функции для работы с модулями 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

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

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

class SafeString: Подкласс str , который был специально помечен как «безопасный» (не требует дополнительного экранирования) для целей вывода HTML. В Python 2 это SafeBytes, а в Python 3 — SafeText.

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

class SafeUnicode: Историческое название SafeText. Доступно только в Python 2.

mark_safe(s) [source]

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

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

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

Строка, помеченная как безопасная, снова станет небезопасной при модификации. Например:

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

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

mark_for_escaping(s) [source]

Устарело начиная с версии 1.10.

Явно отмечает строку как требующую экранирования HTML при выводе. Не оказывает никакого влияния на подклассы SafeData.

Можно вызывать несколько раз на одной строке (результативное экранирование применяется только один раз).

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

slugify(allow_unicode=False) [source]

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

Например:

slugify(value)

Если value равен "Joel is a slug", вывод будет "joel-is-a-slug".

Можно установить параметр allow_unicode на True, чтобы разрешить символы Юникода:

slugify(value, allow_unicode=True)

Если value равен "你好 World", вывод будет "你好-world".

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

Добавлен параметр allow_unicode.

Функции выбора часовых поясов

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 или, если доступен pytz, именем временной зоны.

deactivate() [source]: Снимает установку текущей временной зоны.

override(timezone) [source]

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

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

localtime(value, timezone=None) [source]

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

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

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

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

is_dst не оказывает никакого влияния, когда pytz не установлен.

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

Аргумент is_dst был добавлен.

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

`django.utils.translation`

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

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

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

pgettext(context, message) [source]

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

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

gettext_lazy(message)

ugettext_lazy(message)

pgettext_lazy(context, message)

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

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

gettext_noop(message) [source]

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

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

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

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

ngettext_lazy(singular, plural, number) [source]

ungettext_lazy(singular, plural, number) [source]

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

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

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

string_concat(*strings): Ленивый вариант конкатенации строк, необходимый для переводов, которые строятся из нескольких частей.

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.

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

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

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

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