Утилиты

Различные утилитарные функции, поставляемые с 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)

Сопоставляет атрибуты запроса с переменными окружения. Это работает не только для объекта запроса Werzeug, но и для любого другого класса с атрибутом 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: Теперь можно передать класс, используемый для объекта Response.

Параметры:	location – адрес перенаправления. code – код статуса перенаправления. По умолчанию 302. Response (класс) – класс 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)

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

string

сырая строка пользовательского агента

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.