Spec-Zone.ru › Werkzeug 2.2

Утилиты

Различные утилитарные функции, поставляемые с 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 (Callable[[Any], _T]) –
  • name (Optional[str]) –
  • doc (Optional[str]) –
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 (Optional[_TAccessorValue]) –
  • load_func (Optional[Callable[[str], _TAccessorValue]]) –
  • dump_func (Optional[Callable[[_TAccessorValue], str]]) –
  • read_only (Optional[bool]) –
  • doc (Optional[str]) –
class werkzeug.utils.header_property(name, default=None, load_func=None, dump_func=None, read_only=None, doc=None)

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

Параметры:
  • name (str) –
  • default (Optional[_TAccessorValue]) –
  • load_func (Optional[Callable[[str], _TAccessorValue]]) –
  • dump_func (Optional[Callable[[_TAccessorValue], str]]) –
  • read_only (Optional[bool]) –
  • doc (Optional[str]) –
werkzeug.utils.redirect(location, code=302, Response=None)

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

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

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

Добавлена в версии 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. Это сохраняет метод и тело запроса.

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

Параметры:
  • path_or_file (Union[PathLike, str, IO[bytes]]) – Путь к файлу для отправки, относительно текущей рабочей директории, если указан относительный путь. В качестве альтернативы, объект, подобный файлу, открытый в двоичном режиме. Убедитесь, что указатель файла переведён в начало данных.
  • 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, int, float]]) – Время последнего изменения для отправки файла в секундах. Если не указано, будет пытаться определить его по пути к файлу.
  • max_age (Optional[Union[int, Callable[[Optional[str]], Optional[int]]]]) – Время, в секундах, в течение которого клиент должен кешировать файл. Если установлено, Cache-Control будет public, в противном случае он будет no-cache для предпочтения условного кеширования.
  • use_x_sendfile (bool) – Установить заголовок X-Sendfile, чтобы позволить серверу эффективно отправлять файл. Требует поддержки HTTP-сервера. Требует передачи пути к файлу.
  • response_class (Optional[Type[Response]]) – Построить ответ, используя этот класс. По умолчанию Response.
  • _root_path (Optional[Union[PathLike, str]]) – Не использовать. Только для внутреннего использования. Используйте 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.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: Optional[str] = None

Название ОС, если оно можно было разобрать из строки.

browser: Optional[str] = None

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

version: Optional[str] = None

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

language: Optional[str] = None

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

string: str

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

to_header()

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

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

str

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

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, где итерации являются необязательными:

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_join(directory, *pathnames)

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

Параметры:
  • directory (str) – доверенный базовый каталог.
  • pathnames (str) – компоненты пути, не доверенные пользователями, относительно базового каталога.
Возвращает:

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

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

Optional[str]

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

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

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

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

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

Spec-Zone.ru

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