Утилиты

Различные утилитарные функции, поставляемые с Werkzeug.

HTML-помощники

class werkzeug.utils.HTMLBuilder(dialect)

Объект-помощник для генерации HTML.

По умолчанию существует два экземпляра этого класса. html экземпляр, и xhtml экземпляр для этих двух диалектов. Класс использует ключевые параметры и позиционные параметры для генерации небольших фрагментов HTML.

Ключевые параметры преобразуются в атрибуты XML/SGML, позиционные аргументы используются как дочерние элементы. Поскольку Python принимает позиционные аргументы перед ключевыми аргументами, рекомендуется использовать список с синтаксисом звёздочки для некоторых дочерних элементов:

>>> html.p(class_='foo', *[html.a('foo', href='foo.html'), ' ',
...                        html.a('bar', href='bar.html')])
'<p class="foo"><a href="foo.html">foo</a> <a href="bar.html">bar</a></p>'

Этот класс обходит некоторые ограничения браузеров и не может использоваться для произвольной генерации SGML/XML. Для этой цели существуют библиотеки lxml и аналогичные.

Вызов билдера экранирует переданную строку:

>>> html.p(html("<foo>"))
'<p>&lt;foo&gt;</p>'

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1.

werkzeug.utils.escape(s)

Заменяет &, <, >, ", и ' на безопасные для HTML последовательности.

None экранируется пустой строкой.

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте MarkupSafe вместо этого.

Parameters: s (Any) –
Return type: str

werkzeug.utils.unescape(s)

Обратный процесс escape(). Это деэкранирует все HTML-сущности, а не только те, что вставлены escape.

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте MarkupSafe вместо этого.

Parameters: s (str) –
Return type: str

Общие помощники

class werkzeug.utils.cached_property(fget, name=None, doc=None)

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

class Example:
    @cached_property
    def value(self):
        # calculate something important here
        return 42

e = Example()
e.value  # evaluates
e.value  # uses cache
e.value = 16  # sets cache
del e.value  # clears cache

Для работы класса необходимо __dict__.

Изменено в версии 2.0: del obj.name очищает кэшированное значение.

Parameters

fget (Callable[[Any], Any]) –
name (Optional[str]) –
doc (Optional[str]) –

Return type

None

werkzeug.utils.invalidate_cached_property(obj, name)

Очищает кэш для cached_property:

>>> class Test(object):
...     @cached_property
...     def magic_number(self):
...         print("recalculating...")
...         return 42
...
>>> var = Test()
>>> var.magic_number
recalculating...
42
>>> var.magic_number
42
>>> invalidate_cached_property(var, "magic_number")
>>> var.magic_number
recalculating...
42

Вы должны передать имя кэшированного свойства как второй аргумент.

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте del obj.name вместо этого.

Parameters

obj (object) –
name (str) –

Return type

None

class werkzeug.utils.environ_property(name, default=None, load_func=None, dump_func=None, read_only=None, doc=None)

Сопоставляет атрибуты запроса с переменными окружения. Это работает не только для объекта запроса Werkzeug, но и для любого другого класса с атрибутом environ:

>>> class Test(object):
...     environ = {'key': 'value'}
...     test = environ_property('key')
>>> var = Test()
>>> var.test
'value'

Если вы передадите второе значение, оно будет использоваться в качестве значения по умолчанию, если ключ не существует. Третье значение может быть преобразователем, который принимает значение и преобразует его. Если возникает ValueError или TypeError, используется значение по умолчанию. Если значение по умолчанию не указано, используется None.

По умолчанию свойство является только для чтения. Вы должны явно включить его, передав read_only=False в конструктор.

class werkzeug.utils.header_property(name, default=None, load_func=None, dump_func=None, read_only=None, doc=None): Аналогично environ_property, но для заголовков.

werkzeug.utils.redirect(location, code=302, Response=None)

Возвращает объект ответа (приложение WSGI), который, при вызове, перенаправляет клиента на целевой URL. Поддерживаемые коды: 301, 302, 303, 305, 307 и 308. 300 не поддерживается, потому что это не настоящее перенаправление, а 304, потому что это ответ на запрос с определёнными заголовками If-Modified-Since.

Журнал изменений

Добавлена в версии 0.10: Теперь можно передать класс, используемый для объекта Response.

Добавлена в версии 0.6: Теперь URL может быть строкой Unicode, которая кодируется с помощью функции iri_to_uri().

Parameters

location (str) – URL, на который должен перенаправить ответ.
code (int) – код статуса перенаправления. По умолчанию 302.
Response (class) – класс Response, который следует использовать при создании ответа. По умолчанию это werkzeug.wrappers.Response если не указано иное.

Return type

Response

werkzeug.utils.append_slash_redirect(environ, code=301)

Перенаправляет на тот же URL, но с добавленным слешем. Поведение этой функции неопределённо, если путь уже заканчивается слешем.

Parameters

environ (WSGIEnvironment) – среда WSGI для запроса, вызывающего перенаправление.
code (int) – код статуса перенаправления.

Return type

Response

werkzeug.utils.send_file(path_or_file, environ, mimetype=None, as_attachment=False, download_name=None, conditional=True, etag=True, last_modified=None, max_age=None, use_x_sendfile=False, response_class=None, _root_path=None)

Отправка содержимого файла клиенту.

Первый аргумент может быть путем к файлу или объектом, подобным файлу. Пути предпочтительнее в большинстве случаев, поскольку Werkzeug может управлять файлом и получать дополнительную информацию из пути. Передача объекта, подобного файлу, требует, чтобы файл был открыт в двоичном режиме, и это в основном полезно при построении файла в памяти с помощью io.BytesIO.

Никогда не передавайте пути к файлам, предоставленные пользователем. Путь предполагается надёжным, поэтому пользователь может создать путь для доступа к файлу, которого вы не имели в виду.

Если сервер WSGI задаёт file_wrapper в environ, он используется, в противном случае используется встроенный wrapper Werkzeug. В качестве альтернативы, если HTTP-сервер поддерживает X-Sendfile, use_x_sendfile=True сообщит серверу о необходимости отправки указанного пути, что намного эффективнее, чем его чтение в Python.

Параметры

path_or_file (Union[os.PathLike, str, BinaryIO]) – Путь к файлу для отправки, относительно текущего каталога, если указан относительный путь. В качестве альтернативы, объект, подобный файлу, открытый в двоичном режиме. Убедитесь, что указатель файла установлен в начало данных.
environ (WSGIEnvironment) – WSGI-среда текущего запроса.
mimetype (Optional[str]) – Тип MIME для отправки файла. Если не указан, он будет пытаться определить его по имени файла.
as_attachment (bool) – Указывает браузеру, что он должен предложить сохранить файл вместо отображения.
download_name (Optional[str]) – Имя по умолчанию, которое браузеры будут использовать при сохранении файла. По умолчанию совпадает с именем файла.
conditional (bool) – Включить условные и диапазонные ответы на основе заголовков запроса. Требует передачи пути к файлу и environ.
etag (Union[bool, str]) – Вычислить ETag для файла, что требует передачи пути к файлу. Также может быть строкой для использования вместо вычисления.
last_modified (Optional[Union[datetime.datetime, int, float]]) – Время последнего изменения файла для отправки в секундах. Если не указано, он попытается определить его по пути к файлу.
max_age (Optional[Union[int, Callable[[Optional[Union[os.PathLike, str]]], int]]]) – Сколько времени клиент должен кэшировать файл в секундах. Если задано, Cache-Control будет public, в противном случае он будет no-cache для предпочтения условного кэширования.
use_x_sendfile (bool) – Установить заголовок X-Sendfile, чтобы сервер эффективно отправлял файл. Требуется поддержка HTTP-сервера. Требует передачи пути к файлу.
response_class (Optional[Type[Response]]) – Построение ответа с использованием этого класса. По умолчанию Response.
_root_path (Optional[Union[os.PathLike, str]]) – Не использовать. Только для внутреннего использования. Используйте send_from_directory() для безопасной отправки файлов по пути.

Тип возвращаемого значения

Response

New in version 2.0: Изменено с реализацией Flask.

Изменено в версии 2.0: download_name заменяет параметр Flask attachment_filename. Если as_attachment=False, он передаётся с Content-Disposition: inline вместо.

Изменено в версии 2.0: max_age заменяет параметр Flask cache_timeout. conditional включено, а max_age по умолчанию не установлено.

Изменено в версии 2.0: etag заменяет параметр Flask add_etags. Он может быть строкой, вместо того, чтобы генерировать её.

Изменено в версии 2.0: Если кодировка возвращается при угадывании mimetype из download_name, устанавливается заголовок Content-Encoding.

werkzeug.utils.import_string(import_name, silent=False)

Импортирует объект на основе строки. Это полезно, если вы хотите использовать пути импорта в качестве точек входа или что-то подобное. Путь импорта может быть указан либо в точечной нотации (xml.sax.saxutils.escape) или с двоеточием в качестве разделителя объекта (xml.sax.saxutils:escape).

Если silent равно True, возвращаемое значение будет None, если импорт завершится ошибкой.

Параметры

import_name (str) – точечное имя объекта для импорта.
silent (bool) – если установлено в True, ошибки импорта игнорируются, и вместо этого возвращается None.

Возвращаемое значение

импортированный объект

Тип возвращаемого значения

Any

werkzeug.utils.find_modules(import_path, include_packages=False, recursive=False)

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

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

Параметры

import_path (str) – точечное имя пакета для поиска дочерних модулей.
include_packages (bool) – установить в True если нужно также возвращать пакеты.
recursive (bool) – установить в True если должна происходить рекурсия.

Возвращаемое значение

генератор

Тип возвращаемого значения

Iterator[str]

werkzeug.utils.validate_arguments(func, args, kwargs, drop_extra=True)

Проверяет, принимает ли функция переданные аргументы и ключевые аргументы. Возвращает новый (args, kwargs) кортеж, который можно безопасно передать в функцию без возникновения TypeError из-за несовместимости сигнатуры функции. Если drop_extra установлено в значение True (что является значением по умолчанию), любые дополнительные позиционные или ключевые аргументы будут автоматически отброшены.

Возникающее исключение содержит три атрибута:

missing: Множество имён аргументов, которые ожидала функция, но которых не хватает.
extra: Словарь ключевых аргументов, с которыми функция не может справиться, но которые были предоставлены.
extra_positional: Список значений, которые были предоставлены в качестве позиционных аргументов, но функция их не может принять.

Это может быть полезно для декораторов, которые передают данные, отправленные пользователем, в функцию представления:

from werkzeug.utils import ArgumentValidationError, validate_arguments

def sanitize(f):
    def proxy(request):
        data = request.values.to_dict()
        try:
            args, kwargs = validate_arguments(f, (request,), data)
        except ArgumentValidationError:
            raise BadRequest('The browser failed to transmit all '
                             'the data expected.')
        return f(*args, **kwargs)
    return proxy

Параметры

func – функция, относительно которой выполняется проверка.
args – кортеж позиционных аргументов.
kwargs – словарь ключевых аргументов.
drop_extra – установите в значение False , если не хотите, чтобы дополнительные аргументы молча отбрасывались.

Возвращает

кортеж в формате (args, kwargs).

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте inspect.signature() вместо этого.

werkzeug.utils.secure_filename(filename)

Принимает имя файла и возвращает его безопасную версию. Это имя файла можно безопасно хранить в обычной файловой системе и передавать в os.path.join(). Возвращаемое имя файла — строка только в ASCII для максимальной переносимости.

В системах Windows функция также гарантирует, что файл не имеет имени одного из специальных устройств.

>>> secure_filename("My cool movie.mov")
'My_cool_movie.mov'
>>> secure_filename("../../../etc/passwd")
'etc_passwd'
>>> secure_filename('i contain cool \xfcml\xe4uts.txt')
'i_contain_cool_umlauts.txt'

Функция может вернуть пустое имя файла. Вам необходимо убедиться, что имя файла уникально и что вы прерываете процесс или генерируете случайное имя файла, если функция вернула пустое.

Журнал изменений

Новое в версии 0.5.

Параметры: filename (str) – имя файла для безопасной обработки
Тип возвращаемого значения: str

werkzeug.utils.bind_arguments(func, args, kwargs)

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

Параметры

func – функция, для которой должны быть связаны аргументы.
args – кортеж позиционных аргументов.
kwargs – словарь ключевых аргументов.

Возвращает

словарь dict связанных ключевых аргументов.

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте Signature.bind() вместо этого.

URL-помощники

Обратитесь к URL-помощникам.

API пользовательского агента

class werkzeug.user_agent.UserAgent(string)

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

Реализация по умолчанию не выполняет анализа, устанавливается только атрибут string. Подкласс может анализировать строку, чтобы установить общие атрибуты или раскрыть другую информацию. Установите werkzeug.wrappers.Request.user_agent_class для использования подкласса.

Параметры: string (str) – значение заголовка для анализа.
Тип возвращаемого значения: None

Новое в версии 2.0: Заменяет предыдущий модуль useragents , но не предоставляет встроенного анализатора.

platform: Optional[str] = None: Имя ОС, если оно могло быть извлечено из строки.

browser: Optional[str] = None: Имя браузера, если оно могло быть извлечено из строки.

version: Optional[str] = None: Версия браузера, если она могла быть извлечена из строки.

language: Optional[str] = None: Язык браузера, если он мог быть извлечён из строки.

string: str: Исходное значение заголовка.

to_header()

Преобразование в значение заголовка.

Тип возвращаемого значения: str

Парсинг пользовательского агента (устарел)

Устарело начиная с версии 2.0: Этот модуль будет удалён в Werkzeug 2.1. Используйте подкласс werkzeug.user_agent.UserAgent для использования специализированного анализатора вместо этого.

class werkzeug.useragents.UserAgent(environ_or_string)

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

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

Параметры: environ_or_string (t.Union[str, WSGIEnvironment]) – значение заголовка для анализа или WSGI-среда, содержащая заголовок.
Тип возвращаемого значения: None

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте подкласс werkzeug.user_agent.UserAgent (обратите внимание на новое имя модуля) для использования специализированного анализатора вместо этого.

Изменено в версии 2.0: Передача WSGI-среды устарела и будет удалена в версии 2.1.

to_header()

Преобразование в значение заголовка.

Тип возвращаемого значения: str

Справочные данные по безопасности

Журнал изменений

Новая версия 0.6.1.

werkzeug.security.generate_password_hash(password, method='pbkdf2:sha256', salt_length=16)

Хеширование пароля с заданным методом и солью с заданной длиной. Формат возвращаемой строки включает использованный метод, чтобы check_password_hash() мог проверить хеш.

Формат хешированной строки выглядит следующим образом:

method$salt$hash

Этот метод не может генерировать пароли без соли, но можно установить параметр method=’plain’, чтобы использовать пароли в открытом виде. Если используется соль, то hmac используется для её добавления к паролю.

Для использования PBKDF2 можно установить метод в pbkdf2:method:iterations , где параметр iterations является необязательным:

pbkdf2:sha256:80000$salt$hash
pbkdf2:sha256$salt$hash

Параметры

password (str) – пароль для хеширования.
method (str) – метод хеширования (поддерживается hashlib). Можно использовать формат pbkdf2:method:iterations для активации PBKDF2.
salt_length (int) – длина соли в символах.

Тип возвращаемого значения

str

werkzeug.security.check_password_hash(pwhash, password)

Проверка пароля по заданному закодированному и хешированному значению пароля. Для поддержки устаревших паролей без соли этот метод поддерживает пароли в открытом виде, хеши md5 и sha1 (с солью и без).

Возвращает True если пароль совпадает, False в противном случае.

Параметры

pwhash (str) – хешированная строка, как возвращает generate_password_hash().
password (str) – текстовый пароль для сравнения с хешем.

Тип возвращаемого значения

bool

werkzeug.security.safe_str_cmp(a, b)

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

Возвращает True если две строки равны, или False если они не равны.

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте hmac.compare_digest() вместо этого.

Журнал изменений

Новая версия 0.7.

Параметры

a (str) –
b (str) –

Тип возвращаемого значения

bool

werkzeug.security.safe_join(directory, *pathnames)

Безопасное объединение нуля или более компонентов пути, не контролируемых пользователем, с базовым каталогом, чтобы избежать выхода за пределы базового каталога.

Параметры

directory (str) – надёжный базовый каталог.
pathnames (str) – неконтролируемые компоненты пути, относительные к базовому каталогу.

Возвращает

Безопасный путь, в противном случае None.

Тип возвращаемого значения

Optional[str]

werkzeug.security.pbkdf2_hex(data, salt, iterations=260000, keylen=None, hashfunc=None)

Аналогично pbkdf2_bin(), но возвращает строку в шестнадцатеричном формате.

Параметры

data (Union[str, bytes]) – данные для вывода.
salt (Union[str, bytes]) – соль для вывода.
iterations (int) – количество итераций.
keylen (Optional[int]) – длина результирующего ключа. Если не указано, используется размер дайджеста.
hashfunc (Optional[Union[str, Callable]]) – функция хеширования. Это может быть строковое имя известной функции хеширования или функция из модуля hashlib. По умолчанию sha256.

Тип возвращаемого значения

str

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте hashlib.pbkdf2_hmac() вместо этого.

Журнал изменений

Новая версия 0.9.

werkzeug.security.pbkdf2_bin(data, salt, iterations=260000, keylen=None, hashfunc=None)

Возвращает двоичный дайджест для алгоритма хеширования PBKDF2 data с заданной salt. Он выполняет iterations итераций и создаёт ключ длиной keylen байт. По умолчанию используется функция хеширования SHA-256; можно указать другую функцию из модуля hashlib hashfunc.

Параметры

data (Union[str, bytes]) – данные для вывода.
salt (Union[str, bytes]) – соль для вывода.
iterations (int) – количество итераций.
keylen (Optional[int]) – длина результирующего ключа. Если не указано, используется размер дайджеста.
hashfunc (Optional[Union[str, Callable]]) – функция хеширования. Это может быть строковое имя известной функции хеширования или функция из модуля hashlib. По умолчанию sha256.

Тип возвращаемого значения

bytes

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте hashlib.pbkdf2_hmac() вместо этого.

Журнал изменений

Новая версия 0.9.

Ведение журнала

Werkzeug использует стандартный Python logging. Логгер называется "werkzeug".

import logging
logger = logging.getLogger("werkzeug")

Если уровень логгера не задан, он будет установлен в INFO при первом использовании. Если для этого уровня нет обработчика, добавляется StreamHandler.