Утилиты Django

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

django.utils.cache

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

Информацию о заголовке Vary см. в разделе RFC 7231#section-7.1.4.

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

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

patch_cache_control(response, **kwargs)[исходный код]

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

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

Добавлена поддержка нескольких имен полей в директиве no-cache.

get_max_age(response)[исходный код]

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

patch_response_headers(response, cache_timeout=None)[исходный код]

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

  • Expires
  • Cache-Control

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

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

add_never_cache_headers(response)[исходный код]

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

patch_vary_headers(response, newheaders)[исходный код]

Добавляет (или обновляет) заголовок Vary в заданный объект HttpResponse. newheaders - это список имен заголовков, которые должны быть в Vary. Если headers содержит звездочку, то заголовок Vary будет состоять из одной звездочки '*', в соответствии с RFC 7231#section-7.1.4. В противном случае, существующие заголовки в Vary не удаляются.

get_cache_key(request, key_prefix=None, method='GET', cache=None)[исходный код]

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

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

learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None)[исходный код]

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

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

django.utils.dateparse

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

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

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

parse_time(value)[исходный код]

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

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

Changed in Django 3.1:

Добавлена поддержка разделителей-запятых для миллисекунд.

parse_datetime(value)[исходный код]

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

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

Changed in Django 3.1:

Добавлена поддержка разделителей-запятых для миллисекунд.

parse_duration(value)[исходный код]

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

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

Changed in Django 3.1:

Добавлена поддержка разделителей-запятых для десятичных дробей в формате ISO 8601 и для формата "DD HH:MM:SS,uuuuuu".

django.utils.decorators

method_decorator(decorator, name='')[исходный код]

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

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

Пример использования см. в decorating class based views.

decorator_from_middleware(middleware_class)[исходный код]

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

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

decorator_from_middleware_with_args(middleware_class)[исходный код]

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

cache_page = decorator_from_middleware_with_args(CacheMiddleware)

@cache_page(3600)
def my_view(request):
    pass
sync_only_middleware(middleware)[исходный код]
New in Django 3.1.

Помечает промежуточное ПО как synchronous-only. (По умолчанию в Django, но это позволяет вам защититься на будущее, если это значение изменится в будущем релизе).

async_only_middleware(middleware)[исходный код]
New in Django 3.1.

Помечает промежуточное ПО как asynchronous-only. Django обернет его в асинхронный цикл событий, когда он будет вызван из пути запроса WSGI.

sync_and_async_middleware(middleware)[исходный код]
New in Django 3.1.

Помечает промежуточное ПО как sync and async compatible, это позволяет избежать преобразования запросов. Для использования этого декоратора необходимо реализовать определение текущего типа запроса. Подробности смотрите в разделе asynchronous middleware documentation.

django.utils.encoding

smart_str(s, encoding='utf-8', strings_only=False, errors='strict')[исходный код]

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

Если strings_only равно True, не конвертируйте (некоторые) нестрокоподобные объекты.

is_protected_type(obj)[исходный код]

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

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

force_str(s, encoding='utf-8', strings_only=False, errors='strict')[исходный код]

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

Если strings_only равно True, не конвертируйте (некоторые) нестрокоподобные объекты.

smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')[исходный код]

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

Если strings_only равно True, не конвертируйте (некоторые) нестрокоподобные объекты.

force_bytes(s, encoding='utf-8', strings_only=False, errors='strict')[исходный код]

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

Если strings_only равно True, не конвертируйте (некоторые) нестрокоподобные объекты.

smart_text(s, encoding='utf-8', strings_only=False, errors='strict')[исходный код]

Не рекомендуется, начиная с версии 3.0.

Псевдоним force_str() для обратной совместимости, особенно в коде, поддерживающем Python 2.

force_text(s, encoding='utf-8', strings_only=False, errors='strict')[исходный код]

Не рекомендуется, начиная с версии 3.0.

Псевдоним force_str() для обратной совместимости, особенно в коде, поддерживающем Python 2.

iri_to_uri(iri)[исходный код]

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

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

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

uri_to_iri(uri)[исходный код]

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

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

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

filepath_to_uri(path)[исходный код]

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

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

Возвращает строку ASCII, содержащую закодированный результат.

Changed in Django 3.1:

Добавлена поддержка pathlib.Path path.

escape_uri_path(path)[исходный код]

Удаляет небезопасные символы из части пути унифицированного идентификатора ресурса (URI).

django.utils.feedgenerator

Образец использования:

>>> from django.utils import feedgenerator
>>> feed = feedgenerator.Rss201rev2Feed(
...     title="Poynter E-Media Tidbits",
...     link="http://www.poynter.org/column.asp?id=31",
...     description="A group 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)[исходный код]

Создает TagURI.

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

SyndicationFeed

class SyndicationFeed[исходный код]

Базовый класс для всех фидов синдикации. Подклассы должны предоставлять функцию write().

__init__(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)[исходный код]

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

Любые дополнительные аргументы ключевых слов, которые вы передадите в __init__, будут сохранены в self.feed.

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

add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs)[исходный код]

Добавляет элемент в ленту. Все аргументы должны быть строками, кроме pubdate и updateddate, которые являются datetime.datetime объектами, и enclosures, который является списком Enclosure экземпляров.

num_items()[исходный код]
root_attributes()[исходный код]

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

add_root_elements(handler)[исходный код]

Добавляет элементы в корневой (т.е. feed/channel) элемент. Вызывается из write().

item_attributes(item)[исходный код]

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

add_item_elements(handler, item)[исходный код]

Добавьте элементы на каждый элемент (т.е. элемент/запись).

write(outfile, encoding)[исходный код]

Выводит фид в заданной кодировке в outfile, который является файлоподобным объектом. Подклассы должны переопределить это.

writeString(encoding)[исходный код]

Возвращает подачу в заданной кодировке в виде строки.

latest_post_date()[исходный код]

Возвращает последние pubdate или updateddate для всех элементов в фиде. Если ни один элемент не имеет ни одного из этих атрибутов, возвращается текущая дата/время UTC.

Enclosure

class Enclosure[исходный код]

Представляет собой корпус RSS

RssFeed

class RssFeed(SyndicationFeed)[исходный код]

Rss201rev2Feed

class Rss201rev2Feed(RssFeed)[исходный код]

Спецификация: https://cyber.harvard.edu/rss/rss.html

RssUserland091Feed

class RssUserland091Feed(RssFeed)[исходный код]

Спецификация: http://backend.userland.com/rss091

Atom1Feed

class Atom1Feed(SyndicationFeed)[исходный код]

Spec: RFC 4287

django.utils.functional

class cached_property(func, name=None)[исходный код]

Декоратор @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"]

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

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

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

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

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

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

x = person.friends         # calls first time
y = person.get_friends()   # calls again
z = person.friends         # does not call
x is z                     # is True
class classproperty(method=None)[исходный код]
New in Django 3.1.

Подобно :py<<<0 >>>, декоратор <<<1 >>> преобразует результат метода с одним аргументом <<<2 >>> в свойство, доступ к которому можно получить непосредственно из класса.

keep_lazy(func, *resultclasses)[исходный код]

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)[исходный код]

Сокращение для 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)[исходный код]

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

conditional_escape(text)[исходный код]

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

format_html(format_string, *args, **kwargs)[исходный код]

Это похоже на str.format(), за исключением того, что оно подходит для построения HTML-фрагментов. Все args и kwargs проходят через conditional_escape() перед передачей в str.format().

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

Поэтому вместо того, чтобы написать:

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

Вместо этого следует использовать:

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

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

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

format_html_join(sep, format_string, args_generator)[исходный код]

Обертка 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)[исходный код]

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

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

Например:

strip_tags(value)

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

Если вы ищете более надежное решение, обратите внимание на библиотеку bleach Python.

html_safe()[исходный код]

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

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

django.utils.http

urlencode(query, doseq=False)[исходный код]

Версия функции Python urllib.parse.urlencode(), которая может работать с MultiValueDict и нестроковыми значениями.

http_date(epoch_seconds=None)[исходный код]

Форматирует время в соответствии с форматом даты 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)[исходный код]

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

int_to_base36(i)[исходный код]

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

urlsafe_base64_encode(s)[исходный код]

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

urlsafe_base64_decode(s)[исходный код]

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

django.utils.module_loading

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

import_string(dotted_path)[исходный код]

Импортирует точечный путь к модулю и возвращает атрибут/класс, обозначенный последним именем в пути. Возвращает 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.

mark_safe(s)[исходный код]

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

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

Может также использоваться в качестве декоративного элемента.

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

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

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

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

django.utils.text

format_lazy(format_string, *args, **kwargs)

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

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

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

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

slugify(value, allow_unicode=False)[исходный код]

Преобразует строку в URL slug by:

  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'
Changed in Django Development version:

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

django.utils.timezone

utc

tzinfo экземпляр, представляющий UTC.

get_fixed_timezone(offset)[исходный код]

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

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

get_default_timezone()[исходный код]

Возвращает экземпляр tzinfo, который представляет default time zone.

get_default_timezone_name()[исходный код]

Возвращает имя default time zone.

get_current_timezone()[исходный код]

Возвращает экземпляр tzinfo, который представляет current time zone.

get_current_timezone_name()[исходный код]

Возвращает имя current time zone.

activate(timezone)[исходный код]

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

deactivate()[исходный код]

Сбрасывает значение current time zone.

override(timezone)[исходный код]

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

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

localtime(value=None, timezone=None)[исходный код]

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

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

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

localdate(value=None, timezone=None)[исходный код]

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

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

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

now()[исходный код]

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

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

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

is_naive(value)[исходный код]

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

make_aware(value, timezone=None, is_dst=None)[исходный код]

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

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

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

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

make_naive(value, timezone=None)[исходный код]

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

django.utils.translation

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

gettext(message)[исходный код]

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

pgettext(context, message)[исходный код]

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

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

gettext_lazy(message)
pgettext_lazy(context, message)

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

См. lazy translations documentation.

gettext_noop(message)[исходный код]

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

ngettext(singular, plural, number)[исходный код]

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

npgettext(context, singular, plural, number)[исходный код]

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

ngettext_lazy(singular, plural, number)[исходный код]
npgettext_lazy(context, singular, plural, number)[исходный код]

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

См. lazy translations documentation.

activate(language)[исходный код]

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

deactivate()[исходный код]

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

deactivate_all()[исходный код]

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

override(language, deactivate=False)[исходный код]

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

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

check_for_language(lang_code)[исходный код]

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

get_language()[исходный код]

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

get_language_bidi()[исходный код]

Возвращает раскладку BiDi выбранного языка:

  • False = расположение слева направо
  • True = расположение справа налево
get_language_from_request(request, check_path=False)[исходный код]

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

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

get_supported_language_variant(lang_code, strict=False)[исходный код]

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

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

Вызывает LookupError, если ничего не найдено.

to_locale(language)[исходный код]

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

templatize(src)[исходный код]

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

LANGUAGE_SESSION_KEY

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

Не рекомендуется, начиная с версии 3.0: Язык не будет храниться в сессии в Django 4.0. Вместо этого используйте cookie LANGUAGE_COOKIE_NAME.

Вернуться на верх