公用事业

Werkzeug附带的各种实用功能。

一般帮助

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

A property() 它只评估一次。后续访问将返回缓存值。设置该属性会设置缓存值。删除该属性将清除缓存值，再次访问它将再次对其求值。

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__ ，但这通常并不可取。

Changelog

在 2.1 版本发生变更: 与配合使用 __slots__ 。

在 2.0 版本发生变更: del obj.name 清除缓存值。

参数:

  • fget (t.Callable[[t.Any], _T]) --

  • name (str | None) --

  • doc (str | None) --

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

将请求属性映射到环境变量。这不仅适用于Werkzeug Request对象，还适用于具有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 (_TAccessorValue | None) --

  • load_func (t.Callable[[str], _TAccessorValue] | None) --

  • dump_func (t.Callable[[_TAccessorValue], str] | None) --

  • read_only (bool | None) --

  • doc (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 (_TAccessorValue | None) --

  • load_func (t.Callable[[str], _TAccessorValue] | None) --

  • dump_func (t.Callable[[_TAccessorValue], str] | None) --

  • read_only (bool | None) --

  • doc (str | None) --

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

返回一个响应对象（wsgi应用程序），如果调用该对象，则将客户端重定向到目标位置。支持的代码是301、302、303、305、307和308。300不受支持，因为它不是一个真正的重定向，304是一个请求的答案，该请求具有定义的if-modified-since头。

Changelog

在 0.10 版本加入: 现在可以传入用于响应对象的类。

在 0.6 版本加入: 该位置现在可以是使用 iri_to_uri() 功能。

参数:

  • location (str) -- 响应应重定向到的位置。

  • code (int) -- 重定向状态代码。默认为302。

  • Response (class) -- 在实例化响应时使用的响应类。默认值为 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

Changelog

在 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 。

切勿传递用户提供的文件路径。假定该路径是可信的，因此用户可以手工创建一个路径来访问您不想要的文件。使用 send_from_directory() 以安全地服务于用户提供的路径。

如果WSGI服务器将 file_wrapper 在……里面 environ ，否则使用Werkzeug的内置包装器。或者，如果HTTP服务器支持 X-Sendfile ， use_x_sendfile=True 将告诉服务器发送给定的路径，这比在Python中读取要高效得多。

参数:

  • path_or_file (os.PathLike | str | t.IO[bytes]) -- 要发送的文件的路径，如果给定了相对路径，则为相对于当前工作目录的路径。或者，以二进制模式打开类似文件的对象。确保将文件指针查找到数据的开头。

  • environ (WSGIEnvironment) -- 当前请求的WSGI环境。

  • mimetype (str | None) -- 要为文件发送的MIME类型。如果未提供，它将尝试从文件名检测它。

  • as_attachment (bool) -- 向浏览器指示它应该提供保存文件，而不是显示该文件。

  • download_name (str | None) -- 浏览器在保存文件时将使用的默认名称。默认为传递的文件名。

  • conditional (bool) -- 基于请求标头启用条件响应和范围响应。需要传递文件路径，并且 environ 。

  • etag (bool | str) -- 计算文件的ETag，这需要传递文件路径。也可以是要改用的字符串。

  • last_modified (datetime | int | float | None) -- 上次为文件发送的修改时间(秒)。如果未提供，它将尝试从文件路径检测它。

  • max_age (None | (int | t.Callable[[str | None], int | None])) -- 客户端应缓存文件的时间，以秒为单位。如果设置， Cache-Control 将会是 public ，否则将会是 no-cache 要首选条件缓存，请执行以下操作。

  • use_x_sendfile (bool) -- 设置 X-Sendfile 标头，让服务器高效地发送文件。需要来自HTTP服务器的支持。需要传递文件路径。

  • response_class (type[Response] | None) -- 使用此类构建响应。默认为 Response 。

  • _root_path (os.PathLike | str | None) -- 不要使用。仅供内部使用。使用 send_from_directory() 若要安全地发送路径下的文件，请执行以下操作。

返回类型:

Response

Changelog

在 2.0.2 版本发生变更: send_file 仅设置检测到的 Content-Encoding 如果 as_attachment 已禁用。

在 2.0 版本加入: 改编自Flask的实现。

在 2.0 版本发生变更: download_name 取代了Flask的 attachment_filename 参数。如果 as_attachment=False ，它是通过的 Content-Disposition: inline 取而代之的是。

在 2.0 版本发生变更: max_age 取代了Flask的 cache_timeout 参数。 conditional 已启用，并且 max_age 默认情况下不设置。

在 2.0 版本发生变更: etag 取代了Flask的 add_etags 参数。它可以是要使用的字符串，而不是生成字符串。

在 2.0 版本发生变更: 如果在猜测时返回编码 mimetype 从… download_name ，设置 Content-Encoding 标题。

werkzeug.utils.send_from_directory(directory, path, environ, **kwargs)

使用以下命令从目录中发送文件 send_file() 。

这是从文件夹提供文件的一种安全方式，例如静态文件或上载。用途 safe_join() 以确保来自客户端的路径不会被恶意构建为指向指定目录之外。

如果最终路径不指向现有常规文件，则返回404 NotFound 错误。

参数:

  • directory (os.PathLike | str) -- 该目录是 path 必须位于。这 must not 是由客户端提供的值，否则它将变得不安全。

  • path (os.PathLike | str) -- 要发送的文件的路径，相对于 directory 。这是由客户端提供的路径的一部分，对其进行安全性检查。

  • environ (WSGIEnvironment) -- 当前请求的WSGI环境。

  • kwargs (t.Any) -- 要传递的参数 send_file() 。

返回类型:

Response

Changelog

在 2.0 版本加入: 改编自Flask的实现。

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

基于字符串导入对象。如果要将导入路径用作端点或类似的内容，则此选项非常有用。导入路径可以用点符号指定。 (xml.sax.saxutils.escape ）或使用冒号作为对象分隔符 (xml.sax.saxutils:escape ）

如果 silent 为真，返回值将为 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: str | None = None

操作系统名称，如果可以从字符串中解析出来的话。

browser: str | None = None

浏览器名称，如果可以从字符串中解析出来的话。

version: str | None = None

浏览器版本，如果可以从字符串中解析出来的话。

language: str | None = None

浏览器语言(如果可以从字符串中解析出来的话)。

string: str

原始标头值。

to_header()

转换为标题值。

返回类型:

str

安全助手

werkzeug.security.generate_password_hash(password, method='scrypt', salt_length=16)

安全地散列密码以进行存储。可以使用以下命令将密码与存储的哈希进行比较 check_password_hash() 。

支持以下方式：

  • scrypt ，默认设置。这些参数包括 n ， r ，以及 p ，缺省值为 scrypt:32768:8:1 。看见 hashlib.scrypt() 。

  • pbkdf2 ，不那么安全。这些参数包括 hash_method 和 iterations ，缺省值为 pbkdf2:sha256:600000 。看见 hashlib.pbkdf2_hmac() 。

可以更新默认参数以反映当前的指导原则，如果方法不再被认为是安全的，则可能会弃用和删除这些方法。要迁移旧的哈希，您可以在检查旧的哈希时生成新的哈希，或者您可以通过链接联系用户以重置他们的密码。

参数:

  • password (str) -- 明文密码。

  • method (str) -- 密钥派生函数和参数。

  • salt_length (int) -- 要为盐生成的字符数。

返回类型:

str

Changelog

在 2.3 版本发生变更: 添加了SCRYPT支持。

在 2.3 版本发生变更: Pbkdf2的默认迭代次数增加到600,000次。

在 2.3 版本发生变更: 所有纯散列都已弃用，在Werkzeug 3.0中不受支持。

werkzeug.security.check_password_hash(pwhash, password)

安全地检查给定的存储密码散列，该散列以前使用 generate_password_hash() ，与给定的密码匹配。

如果方法不再被认为是安全的，则可能会被弃用并删除。要迁移旧的哈希，您可以在检查旧的哈希时生成新的哈希，或者您可以通过链接联系用户以重置他们的密码。

参数:

  • pwhash (str) -- 散列密码。

  • password (str) -- 明文密码。

返回类型:

bool

Changelog

在 2.3 版本发生变更: 所有纯散列都已弃用，在Werkzeug 3.0中不受支持。

werkzeug.security.safe_join(directory, *pathnames)

将零个或多个不受信任的路径组件安全地连接到基目录，以避免逃离基目录。

参数:

  • directory (str) -- 受信任的基本目录。

  • pathnames (str) -- 相对于基目录的不受信任的路径组件。

返回:

一条安全的道路，否则 None .

返回类型:

str | None

登录中

Werkzeug使用标准Python logging . 记录器名为 "werkzeug" .

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

如果未设置记录器级别，则将其设置为 INFO 第一次使用。如果没有该级别的处理程序，则 StreamHandler 添加。