Инструменты

Общие инструменты

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

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

Parameters:

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

Return type:

str

URL-помощники

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

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

class werkzeug.user_agent.UserAgent(string)

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

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

Parameters:

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

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

Return type:

str

Безопасные помощники

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

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

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

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

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

Parameters:

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

Return type:

str

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

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

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

werkzeug.security.check_password_hash(pwhash, password)

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

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

Parameters:

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

Return type:

bool

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

werkzeug.security.safe_join(directory, *pathnames)

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

Parameters:

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

Returns:

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

Return type:

str | None

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

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

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

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