Утилиты

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

Заменяет специальные символы “&”, “<”, “>” и (“) на безопасные для 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__ для работы этой характеристики.

werkzeug.utils.invalidate_cached_property(obj, name)

Очищает кэш для cached_property:

>>> class Test(object):
...     @cached_property
...     def magic_number(self):
...         print("recalculating...")
...         return 42
...
>>> var = Test()
>>> var.magic_number
recalculating...
42
>>> var.magic_number
42
>>> invalidate_cached_property(var, "magic_number")
>>> var.magic_number
recalculating...
42

Вы должны передать имя кэшируемого свойства в качестве второго аргумента.

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

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

Параметры:	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)

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

string

необработанная строка UserAgent

platform

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

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

browser

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

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

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

version

версия браузера. None если не распознана.

language

язык браузера. None если не распознан.

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

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.

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

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

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

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

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