Spec-Zone.ru › Werkzeug 2.1

Утилиты

Различные утилитарные функции, поставляемые с 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], werkzeug.utils._T]) –
  • name (Optional[str]) –
  • doc (Optional[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 (Optional[werkzeug._internal._TAccessorValue]) –
  • load_func (Optional[Callable[[str], werkzeug._internal._TAccessorValue]]) –
  • dump_func (Optional[Callable[[werkzeug._internal._TAccessorValue], str]]) –
  • read_only (Optional[bool]) –
  • doc (Optional[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 (Optional[werkzeug._internal._TAccessorValue]) –
  • load_func (Optional[Callable[[str], werkzeug._internal._TAccessorValue]]) –
  • dump_func (Optional[Callable[[werkzeug._internal._TAccessorValue], str]]) –
  • read_only (Optional[bool]) –
  • doc (Optional[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: Теперь местоположение может быть строкой unicode, которая кодируется с помощью функции iri_to_uri().

Параметры
  • location (str) – местоположение, на которое должен перенаправить ответ.
  • 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[os.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.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[os.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'

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

Изменения

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

Параметры

filename (str) – имя файла для обработки

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

str

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

Помощники безопасности

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_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.1.x/utils/

Spec-Zone.ru

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