Spec-Zone.ru › Werkzeug 3.0

Утилиты

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

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

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 (str | None) –
  • doc (str | 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 (str) –
  • default (_TAccessorValue | None) –
  • load_func (t.Callable[[str], _TAccessorValue] | None) –
  • dump_func (t.Callable[[_TAccessorValue], str] | None) –
  • read_only (bool | None) –
  • doc (str | None) –
class werkzeug.utils.header_property(name, default=None, load_func=None, dump_func=None, read_only=None, doc=None)

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

Параметры:
  • name (str) –
  • default (_TAccessorValue | None) –
  • load_func (t.Callable[[str], _TAccessorValue] | None) –
  • dump_func (t.Callable[[_TAccessorValue], str] | None) –
  • read_only (bool | None) –
  • doc (str | 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 (str) – URL, на который должен перенаправить ответ.
  • code (int) – код статуса перенаправления. По умолчанию 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 (int) – код статуса перенаправления.
Тип возвращаемого значения:

Response

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

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

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

END_OF_DOCUMENT_MARKER
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, он используется; в противном случае используется встроенный обработчик Werkzeug. В качестве альтернативы, если HTTP-сервер поддерживает X-Sendfile, use_x_sendfile=True сообщит серверу отправить указанный путь, что намного эффективнее, чем чтение его в Python.

Параметры:
  • path_or_file (os.PathLike | 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 | 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) – Каталог, в котором path должен находиться. Это не должно быть значение, предоставленное клиентом, иначе это станет небезопасным.
  • path (os.PathLike | 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 в случае ошибки импорта.

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

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

Return type:

Any

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

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

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

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

генератор

Return type:

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

New in version 0.5.

Parameters:

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

Return type:

str

URL Helpers

См. URL Helpers.

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

class werkzeug.user_agent.UserAgent(string)

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

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

Parameters:

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

Changelog

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

platform: str | None = None

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

browser: str | None = None

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

version: str | None = None

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

language: str | None = None

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

string: str

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

to_header()

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

Return type:

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

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

Изменено в версии 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.

© 2007 Pallets
Licensed under the BSD 3-clause License.
https://werkzeug.palletsprojects.com/en/3.0.x/utils/

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API