Утилиты

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

HTML-помощники

class werkzeug.utils.HTMLBuilder(dialect)

Объект-помощник для генерации HTML.

По умолчанию существует два экземпляра этого класса. Один для html диалекта и один для xhtml диалекта. Класс использует именованные параметры и позиционные параметры для генерации небольших фрагментов HTML.

Именованные параметры преобразуются в атрибуты XML/SGML, позиционные аргументы используются в качестве дочерних элементов. Поскольку Python принимает позиционные аргументы перед именованными, рекомендуется использовать список с синтаксисом звездочки для некоторых дочерних элементов:

>>> html.p(class_='foo', *[html.a('foo', href='foo.html'), ' ',
...                        html.a('bar', href='bar.html')])
u'<p class="foo"><a href="foo.html">foo</a> <a href="bar.html">bar</a></p>'

Этот класс работает вокруг некоторых ограничений браузера и не может использоваться для произвольной генерации SGML/XML. Для этой цели существуют библиотеки lxml и аналогичные.

Вызов билдера экранирует переданную строку:

>>> html.p(html("<foo>"))
u'<p>&lt;foo&gt;</p>'

werkzeug.utils.escape(s, quote=None)

Заменяет специальные символы “&”, “<”, “>” и “(“ на безопасные для HTML последовательности.

Существует специальная обработка для None, которая экранирует в пустую строку.

Изменено в версии 0.9: quote теперь неявно включен.

Параметры:	s – строка для экранирования. quote – игнорируется.

werkzeug.utils.unescape(s)

Обратная функция для escape. Эта функция деэкранирует все HTML-сущности, а не только XML-сущности, вставленные escape.

Параметры:	s – строка для деэкранирования.

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

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

Декоратор, преобразующий функцию в ленивую собственность. Функция, обернутая, вызывается в первый раз для получения результата, а затем этот рассчитанный результат используется при следующем обращении к значению:

class Foo(object):

    @cached_property
    def foo(self):
        # calculate something important here
        return 42

Класс должен иметь __dict__ для работы этой собственности.

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 в конструктор.

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

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

werkzeug.utils.redirect(location, code=302, Response=None)

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

Добавлен в версии 0.6: Адрес теперь может быть строкой Unicode, которая кодируется с помощью функции iri_to_uri().

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

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

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

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

Параметры:	environ – WSGI окружение запроса, который вызывает перенаправление. code – код статуса перенаправления.

werkzeug.utils.import_string(import_name, silent=False)

Импортирует объект на основе строки. Это полезно, если вы хотите использовать пути импорта в качестве точек входа или что-то подобное. Путь импорта может быть указан как в точечной нотации (xml.sax.saxutils.escape) или с двоеточием в качестве разделителя объекта (xml.sax.saxutils:escape).

Если silent равно True, возвращаемое значение будет None в случае ошибки импорта.

Параметры:	import_name – точечное имя импортируемого объекта. silent – если равно True, ошибки импорта игнорируются, и возвращается None.
Возвращает:	импортированный объект

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

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

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

Параметры:	import_path – точечное имя пакета для поиска дочерних модулей. include_packages – равно True если должны возвращаться и пакеты. recursive – равно True если должна происходить рекурсия.
Возвращает:	генератор

werkzeug.utils.validate_arguments(func, args, kwargs, drop_extra=True)

Проверяет, принимает ли функция аргументы и именованные аргументы. Возвращает новый кортеж (args, kwargs), который можно безопасно передать функции, не вызывая TypeError, потому что сигнатура функции несовместима. Если drop_extra равно True (что является значением по умолчанию), любые дополнительные позиционные или именованные аргументы автоматически отбрасываются.

Возникающее исключение имеет три атрибута:

missing

Множество имён аргументов, которые функция ожидала, но которых не было.

extra

Словарь именованных аргументов, которые функция не может обработать, но которые были предоставлены.

extra_positional

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

Это может быть полезно для декораторов, которые передают предоставленные пользователем данные в функцию представления:

from werkzeug.utils import ArgumentValidationError, validate_arguments

def sanitize(f):
    def proxy(request):
        data = request.values.to_dict()
        try:
            args, kwargs = validate_arguments(f, (request,), data)
        except ArgumentValidationError:
            raise BadRequest('The browser failed to transmit all '
                             'the data expected.')
        return f(*args, **kwargs)
    return proxy

Параметры:	func – функция, по отношению к которой выполняется валидация. args – кортеж позиционных аргументов. kwargs – словарь именованных аргументов. drop_extra – присвоено False если вы не хотите, чтобы дополнительные аргументы отбрасывались молча.
Возвращает:	кортеж в формате (args, kwargs).

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(u'i contain cool \xfcml\xe4uts.txt')
'i_contain_cool_umlauts.txt'

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

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

Параметры:	filename – имя файла для защиты

werkzeug.utils.bind_arguments(func, args, kwargs)

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

Параметры:	func – функция, для которой должны быть связаны аргументы. args – кортеж позиционных аргументов. kwargs – словарь ключевых аргументов.
Возвращает:	словарь dict связанных ключевых аргументов.

Справочники URL

Обратитесь к Справочникам URL.

Парсинг UserAgent

class werkzeug.useragents.UserAgent(environ_or_string)

Представляет собой user agent. Передайте ему WSGI-среду или строку user agent, и вы сможете проверить некоторые детали из строки user agent через атрибуты. Существуют следующие атрибуты:

string

сырая строка user agent

platform

платформа браузера. В настоящее время распознаются следующие платформы:

• aix
• amiga
• android
• blackberry
• bsd
• chromeos
• dragonflybsd
• freebsd
• hpux
• ipad
• iphone
• irix
• linux
• macos
• netbsd
• openbsd
• sco
• solaris
• symbian
• wii
• windows

browser

название браузера. В настоящее время распознаются следующие браузеры:

• aol *
• ask *
• baidu *
• bing *
• camino
• chrome
• edge
• firefox
• galeon
• google *
• kmeleon
• konqueror
• links
• lynx
• mozilla
• msie
• msn
• netscape
• opera
• safari
• seamonkey
• webkit
• yahoo *

(Браузеры, помеченные звёздочкой (*) являются роботами.)

version

версия браузера

language

язык браузера

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

werkzeug.security.generate_password_hash(password, method='pbkdf2:sha256', salt_length=8)

Хэширование пароля с заданным методом и солью с заданной длиной строки. Формат возвращаемой строки включает метод, который был использован, чтобы check_password_hash() мог проверить хеш.

Формат хэшированной строки выглядит следующим образом:

method$salt$hash

Этот метод не может генерировать незасоленные пароли, но можно установить параметр method=’plain’ для того, чтобы принудительно использовать пароли в открытом тексте. Если используется соль, то для соления пароля внутри используется hmac.

Если требуется PBKDF2, его можно включить, установив метод в pbkdf2:method:iterations, где iterations – необязателен:

pbkdf2:sha256:80000$salt$hash
pbkdf2:sha256$salt$hash

Параметры:	password – пароль для хэширования. method – метод хэширования для использования (который поддерживается hashlib). Можно также использовать формат pbkdf2:<method>[:iterations] для включения PBKDF2. salt_length – длина соли в символах.

werkzeug.security.check_password_hash(pwhash, password)

проверка пароля по заданному засоленному и хэшированному значению пароля. Для поддержки устаревших незасоленных паролей этот метод поддерживает пароли в открытом тексте, хэши md5 и sha1 (как засоленные, так и незасоленные).

Возвращает True если пароль совпал, False в противном случае.

Параметры:	pwhash – хэшированная строка, как возвращается generate_password_hash(). password – пароль в открытом тексте для сравнения с хэшем.

werkzeug.security.safe_str_cmp(a, b)

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

Возвращает True если две строки равны, или False если они не равны.

Введено в версии 0.7.

werkzeug.security.safe_join(directory, *pathnames)

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

Параметры:	directory – надёжный базовый каталог. pathnames – компоненты пути, не доверяя их, относительно базового каталога.
Возвращает:	безопасный путь, иначе None.

werkzeug.security.pbkdf2_hex(data, salt, iterations=150000, keylen=None, hashfunc=None)

Как pbkdf2_bin(), но возвращает строку в шестнадцатеричном кодировании.

Введено в версии 0.9.

Параметры:	data – данные для вывода. salt – соль для вывода. iterations – количество итераций. keylen – длина результирующего ключа. Если не указано, будет использоваться размер дайджеста. hashfunc – функция хэширования для использования. Это может быть строковое имя известной функции хэширования или функция из модуля hashlib. По умолчанию используется sha256.

werkzeug.security.pbkdf2_bin(data, salt, iterations=150000, keylen=None, hashfunc=None)

Возвращает двоичный дайджест для алгоритма хэширования PBKDF2 data с заданной salt. Он выполняет iterations итераций и генерирует ключ длиной keylen байт. По умолчанию используется SHA-256 как функция хэширования; можно предоставить другую функцию из модуля hashlib hashfunc.

Введено в версии 0.9.

Параметры:	data – данные для вывода. salt – соль для вывода. iterations – количество итераций. keylen – длина результирующего ключа. Если не указано, будет использован размер дайджеста. hashfunc – функция хэширования для использования. Это может быть строковое имя известной функции хэширования или функция из модуля hashlib. По умолчанию используется sha256.