Утилиты

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

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

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

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

Если класс определяет __slots__, он должен добавить _cache_{name} как слот. В качестве альтернативы, он может добавить __dict__, но это обычно нежелательно.

Изменения

Изменено в версии 2.1: Работает с __slots__.

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

Параметры:

• fget (t.Callable[[t.Any], _T])
• name (строка | None)
• doc (строка | 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 в конструктор.

Параметры:

• name (строка)
• default (_TAccessorValue | None)
• load_func (t.Callable[[строка], _TAccessorValue] | None)
• dump_func (t.Callable[[_TAccessorValue], строка] | None)
• read_only (bool | None)
• doc (строка | None)

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

Аналогично environ_property, но для заголовков.

Параметры:

• name (строка)
• default (_TAccessorValue | None)
• load_func (t.Callable[[строка], _TAccessorValue] | None)
• dump_func (t.Callable[[_TAccessorValue], строка] | None)
• read_only (bool | None)
• doc (строка | None)

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

Параметры:

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

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

Response

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

Перенаправление на текущий URL с добавленной слешей.

Если текущий URL — /user/42, URL перенаправления будет 42/. При объединении с текущим URL во время обработки ответа или браузером, это даст /user/42/.

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

Параметры:

• environ (WSGIEnvironment) – Используйте путь и запрос из этой среды WSGI для создания URL перенаправления.
• code (целое число) – код статуса перенаправления.

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

Response

Изменения

Изменено в версии 2.1: Создает относительный URL, который изменяет только последний сегмент. Актуально, когда текущий путь имеет несколько сегментов.

Изменено в версии 2.1: Значение по умолчанию для кода статуса — 308 вместо 301. Это сохраняет метод и тело запроса.

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.

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

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

Параметры:

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

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

Response

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

Изменено в версии 2.0.2: send_file только устанавливает обнаруженный Content-Encoding если as_attachment отключен.

Добавлен в версии 2.0: Адаптировано из реализации Flask.

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

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

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

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

werkzeug.utils.send_from_directory(directory, path, environ, **kwargs)

Отправка файла из директории с помощью send_file().

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

Если конечный путь не указывает на существующий обычный файл, возвращается ошибка 404 NotFound.

Параметры:

• directory (os.PathLike[str] | str) – Директория, в которой path должен находиться. Это не должно быть значение, предоставленное клиентом, в противном случае безопасность нарушается.
• path (os.PathLike[str] | str) – Путь к файлу для отправки, относительно directory. Это часть пути, предоставленного клиентом, которая проверяется на безопасность.
• environ (WSGIEnvironment) – WSGI-среда для текущего запроса.
• kwargs (t.Any) – Аргументы для передачи в send_file().

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

Response

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

Добавлен в версии 2.0: Адаптировано из реализации Flask.

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

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

Changelog

Добавлен в версии 0.5.

Параметры:

filename (str) – имя файла для защиты

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

str

URL-помощники

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

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

class werkzeug.user_agent.UserAgent(string)

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

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

Параметры:

string (str) – значение заголовка для разбора.

Changelog

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

platform: str | None = None

Имя ОС, если оно могло быть прочитано из строки.

browser: str | None = None

Имя браузера, если оно могло быть прочитано из строки.

version: str | None = None

Версия браузера, если она могла быть прочитана из строки.

language: str | None = None

Язык браузера, если он мог быть прочитан из строки.

string: str

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

to_header()

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

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

str

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

werkzeug.security.generate_password_hash(password, method='scrypt', salt_length=16)

Надежно хеширует пароль для хранения. Пароль можно сравнить с сохраненным хешем, используя check_password_hash().

Поддерживаются следующие методы:

• scrypt, по умолчанию. Параметрами являются n, r, и p, значение по умолчанию scrypt:32768:8:1. См. hashlib.scrypt().
• pbkdf2, менее защищённый метод. Параметрами являются hash_method и iterations, по умолчанию pbkdf2:sha256:600000. См. hashlib.pbkdf2_hmac().

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

Параметры:

• password (str) – Текстовый пароль.
• method (str) – Функция и параметры вывода ключа.
• salt_length (int) – Количество символов для генерации соли.

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

str

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

Изменено в версии 3.1: По умолчанию количество итераций для pbkdf2 было увеличено до 1 000 000.

Изменено в версии 2.3: Добавлена поддержка Scrypt.

Изменено в версии 2.3: По умолчанию количество итераций для pbkdf2 было увеличено до 600 000.

Изменено в версии 2.3: Все простые хеши устарели и не будут поддерживаться в Werkzeug 3.0.

werkzeug.security.check_password_hash(pwhash, password)

Надежно проверяет, соответствует ли предоставленный хэш сохраненного пароля, ранее сгенерированный с помощью generate_password_hash(), заданному паролю.

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

Параметры:

• pwhash (str) – Хешированное пароль.
• password (str) – Текстовый пароль.

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

bool

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

Изменено в версии 2.3: Все простые хеши устарели и не будут поддерживаться в Werkzeug 3.0.

werkzeug.security.safe_join(directory, *pathnames)

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

Параметры:

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

Возвращает:

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

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

str | None

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

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

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

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