Утилиты Django

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

django.utils.cache

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

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

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

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

patch_cache_control( ответ , ** kwargs )

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

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

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

get_max_age( ответ )

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

patch_response_headers( ответ , cache_timeout = None )

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

  • Expires
  • Cache-Control

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

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

add_never_cache_headers( ответ )

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

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

Директива private добавлена.

patch_vary_headers( ответ , новые заголовки )

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

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

Управление звездочкой в ​​соответствии с RFC 7231 # section-7.1.4 был добавлен.

get_cache_key( запрос , key_prefix = None , method = 'GET' , cache = None )

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

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

learn_cache_key( запрос , ответ , cache_timeout = None , key_prefix = None , cache = None )

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

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

django.utils.dateparse

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

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

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

parse_time( значение )

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

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

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

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

parse_datetime( значение )

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

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

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

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

parse_duration( значение )

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

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

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

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

django.utils.decorators

method_decorator( декоратор , name = '' ) [источник]

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

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

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

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( промежуточное ПО ) [источник]
Новое в Django 3.1.

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

async_only_middleware( промежуточное ПО ) [источник]
Новое в Django 3.1.

У Marks есть промежуточное ПО, предназначенное только для асинхронной обработки . Django заключит его в асинхронный цикл обработки событий, когда он будет вызван из пути запроса WSGI.

sync_and_async_middleware( промежуточное ПО ) [источник]
Новое в Django 3.1.

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

django.utils.encoding

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

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

Если strings_only есть True , не преобразует некоторые нестроковые объекты.

is_protected_type( obj )

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

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

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

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

Если strings_only есть True , не преобразует некоторые нестроковые объекты.

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

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

Если strings_only есть True , не преобразует некоторые нестроковые объекты.

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

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

Если strings_only есть True , не преобразует некоторые нестроковые объекты.

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) в часть URI, которая подходит для включения в URL.

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

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

uri_to_iri( ури )

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

Это алгоритм, вдохновленный разделом 3.2 RFC 3987 # раздел-3.2 .

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

filepath_to_uri( путь )

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

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

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

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

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

escape_uri_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 , дата )

Создайте TagURI .

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

SyndicationFeed

класс SyndicationFeed

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

__init__( Название , ссылка , описание , язык = None , author_email = None , author_name = None , author_link = None , подзаголовок = None , категории = None , FEED_URL = None , feed_copyright = None , feed_guid = None , ТТЛ = 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 = Нет , ** kwargs )

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

num_items()
root_attributes()

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

add_root_elements( обработчик )

Добавляет элементы к корневому элементу (то есть потоку или каналу). Вызывается с тех пор write() .

item_attributes( элемент )

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

add_item_elements( обработчик , предмет )

Добавляет элементы для каждого элемента в ленте.

write( выход , кодировка )

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

writeString( кодировка )

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

latest_post_date()

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

Enclosure

класс Enclosure

Представляет приложение RSS.

RssFeed

классRssFeed ( SyndicationFeed )

Rss201rev2Feed

классRss201rev2Feed ( RssFeed )

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

RssUserland091Feed

классRssUserland091Feed ( RssFeed )

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

Atom1Feed

классAtom1Feed ( SyndicationFeed )

Технические характеристики: RFC 4287

django.utils.functional

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

Из-за того, как работает протокол дескриптора , использование 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
classclassproperty ( method = None ) [источник]
Новое в Django 3.1.

Подобно этому @classmethod , @classproperty декоратор преобразует результат метода с одним cls аргументом в свойство, к которому можно получить доступ непосредственно из класса.

keep_lazy( func , * resultclasses ) [источник]

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

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

Для подобных случаев используйте декоратор 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( текст )

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

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

В более старых версиях ' был преобразован в его десятичный код &#39; вместо эквивалентного шестнадцатеричного кода &#x27; .

conditional_escape( текст )

Аналогично 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( значение )

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

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

Например :

strip_tags(value)

Если value есть , возвращаемое значение будет ."<b>Joël</b> <button>est</button> une <span>limace</span>" "Joël est une limace"

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

html_safe()

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

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

django.utils.http

urlencode( запрос , доза q = Ложь )

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

http_date( epoch_seconds = Нет )

Форматирует дату / время в соответствии с форматом даты RFC 1123 # section-5.2.14, как определеноRFC 7231 # section-7.1.1.1 стандарта HTTP.

Принимает число с плавающей запятой, выраженное в секундах от начального времени Unix в формате 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 (например, «<»), в соответствующие объекты.

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

slugify( значение , allow_unicode = False )

Преобразуйте строку в URL-адрес, чтобы:

  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.

get_fixed_timezone( смещение )

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

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

get_default_timezone()

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

get_default_timezone_name()

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

get_current_timezone()

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

get_current_timezone_name()

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

activate( часовой пояс )

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

deactivate()

Отключает текущий часовой пояс .

override( часовой пояс )

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

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

localtime( значение = Нет , часовой пояс = Нет )

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

Если value не указано, используется значение по умолчанию now() .

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

localdate( значение = Нет , часовой пояс = Нет )

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

Если value не указано, используется значение по умолчанию now() .

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

now()

Возвращает объект, datetime представляющий текущий момент времени («сейчас»). Возвращаемое точное значение зависит от значения USE_TZ :

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

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

is_naive( значение )

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

make_aware( значение , часовой пояс = Нет , is_dst = Нет )

Возвращает 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( значение , часовой пояс = Нет )

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

django.utils.translation

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

gettext( сообщение )

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

pgettext( контекст , сообщение )

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

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

gettext_lazy( сообщение )
pgettext_lazy( контекст , сообщение )

Такое же поведение, как и у не отложенных версий выше, но с использованием отложенного выполнения.

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

gettext_noop( сообщение )

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

ngettext( единственное , множественное , число )

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

npgettext( контекст , единственное , множественное число , число )

Переводит singulier и pluriel возвращает соответствующую строку на основе nombre и context .

ngettext_lazy( единственное , множественное , число )
npgettext_lazy( контекст , единственное , множественное число , число )

Такое же поведение, как и у не отложенных версий выше, но с использованием отложенного выполнения.

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

activate( язык )

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

deactivate()

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

deactivate_all()

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

override( язык , деактивировать = False )

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

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

check_for_language( lang_code )

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

get_language()

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

get_language_bidi()

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

  • False = расположение слева направо
  • True = расположение справа налево
get_language_from_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 , последний возвращается для языковых кодов, таких как 'es' и 'es-ar' . Эти совпадения не возвращаются, когда strict=True .

Генерировать, LookupError если ничего не найдено.

to_locale( язык )

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

templatize( SRC )

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

LANGUAGE_SESSION_KEY

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

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

Copyright ©2021 All rights reserved