WSGI帮助者

以下类和函数旨在使使用wsgi规范更容易或在wsgi层上操作。此模块的所有功能都在高级 请求/响应对象 .

迭代器/流帮助器

这些类和函数简化了使用wsgi应用程序迭代器和输入流的工作。

class werkzeug.wsgi.ClosingIterator(iterable, callbacks=None)

wsgi规范要求所有中间件和网关都遵守 close 应用程序返回的ITerable的回调。因为向返回的iterable添加另一个close操作很有用，并且添加自定义iterable是一项无聊的任务，所以此类可用于：

return ClosingIterator(app(environ, start_response), [cleanup_session,
                                                      cleanup_locals])

如果只有一个关闭函数，则可以传递它而不是列表。

如果应用程序使用响应对象并在响应启动时完成处理，则不需要关闭迭代器：：

try:
    return response(environ, start_response)
finally:
    cleanup_session()
    cleanup_locals()
参数:

  • iterable (t.Iterable[bytes]) --

  • callbacks (None | (t.Callable[[], None] | t.Iterable[t.Callable[[], None]])) --

class werkzeug.wsgi.FileWrapper(file, buffer_size=8192)

此类可用于转换 file -像一个物体变成一个物体。它产生 buffer_size 阻止，直到文件完全读取。

您不应该直接使用这个类，而应该使用 wrap_file() 使用wsgi服务器的文件包装支持（如果可用）的函数。

Changelog

在 0.5 版本加入.

如果将此对象与 Response 您必须使用 direct_passthrough 模式。

参数:

  • file (t.IO[bytes]) -- 一 file -像一个物体 read() 方法。

  • buffer_size (int) -- 一次迭代的字节数。

class werkzeug.wsgi.LimitedStream(stream, limit, is_max=False)

对流进行包装，使其不会读取超过给定限制的内容。这是用来限制 wsgi.input 发送到 Content-Length 标题值或 Request.max_content_length 。

当在已经达到限制之后尝试读取时， on_exhausted() 被称为。当限制为最大值时，将引发 RequestEntityTooLarge 。

如果从流中读取返回零字节或引发错误， on_disconnect() 被调用，这引发了 ClientDisconnected 。当限制为最大值且读取了零字节时，不会引发错误，因为它可能是流的末尾。

如果在基础流(如太大的文件或无限流)耗尽之前达到限制，则不能安全地读取流的其余内容。根据服务器对此的处理方式，客户端可能会显示“连接重置”失败，而不是看到413响应。

参数:

  • stream (t.IO[bytes]) -- 要从中读取的流。必须是可读的二进制IO对象。

  • limit (int) -- 不超过读取的字节数限制。应该是 Content-Length 标题值或 request.max_content_length 。

  • is_max (bool) -- 无论是给定的 limit 是 request.max_content_length 而不是 Content-Length 标头值。这会更改耗尽和断开连接事件的处理方式。

Changelog

在 2.3 版本发生变更: 手柄 max_content_length 不同于 Content-Length 。

在 2.3 版本发生变更: 机具 io.RawIOBase 而不是 io.IOBase 。

exhaust()

通过读取直到达到限制或客户端断开连接，返回剩余数据来耗尽流。

Changelog

在 2.3 版本发生变更: 返回剩余数据。

在 2.2.3 版本发生变更: 处理包装的流返回的字节数少于请求的情况。

返回类型:

bytes

property is_exhausted: bool

当前流位置是否已达到限制。

on_disconnect(error=None)

当尝试的读取在达到限制之前收到零字节时调用。这表示客户端在发送完整的请求正文之前断开了连接。

默认行为是引发 ClientDisconnected ，除非该限制是最大值，并且没有出现错误。

Changelog

在 2.3 版本发生变更: 添加了 error 参数。如果限制是最大值且未引发错误，则不执行任何操作。

在 2.3 版本发生变更: 任何返回值都将被忽略。

参数:

error (Exception | None) --

返回类型:

None

on_exhausted()

在达到限制后尝试读取时调用。

默认行为是不执行任何操作，除非限制是最大值，在这种情况下它会引发 RequestEntityTooLarge 。

Changelog

在 2.3 版本发生变更: 加薪 RequestEntityTooLarge 如果限制是最大值。

在 2.3 版本发生变更: 任何返回值都将被忽略。

返回类型:

None

readable()

返回是否打开对象进行读取。

如果为false，read（）将引发oserror。

返回类型:

bool

readall()

使用多个Read()调用，直到EOF为止。

返回类型:

bytes

tell()

返回当前流位置。

Changelog

在 0.9 版本加入.

返回类型:

int

werkzeug.wsgi.wrap_file(environ, file, buffer_size=8192)

包装文件。这将使用wsgi服务器的文件包装器（如果可用），或者使用通用的 FileWrapper .

Changelog

在 0.5 版本加入.

如果使用来自WSGI服务器的文件包装器，重要的是不要从应用程序内部迭代它，而是原封不动地传递它。如果要在响应对象内传递文件包装器，则必须设置 Response.direct_passthrough 至 True 。

有关文件包装器的详细信息，请参阅 PEP 333 .

参数:

  • file (t.IO[bytes]) -- 一 file -像一个物体 read() 方法。

  • buffer_size (int) -- 一次迭代的字节数。

  • environ (WSGIEnvironment) --

返回类型:

t.Iterable[bytes]

环境帮助者

这些函数在WSGI环境中运行。它们提取有用的信息或执行常见的操作：

werkzeug.wsgi.get_host(environ, trusted_hosts=None)

返回给定WSGI环境的主机。

这个 Host 最好使用标题，然后 SERVER_NAME 如果没有设置的话。仅当该端口不同于协议的标准端口时，返回的主机才会包含该端口。

或者，使用验证主机是否受信任 host_is_trusted() 抚养一个 SecurityError 如果不是。

参数:

  • environ (WSGIEnvironment) -- 一个WSGI环境字典。

  • trusted_hosts (t.Iterable[str] | None) -- 受信任主机名列表。

返回:

主机，必要时带端口。

抛出:

SecurityError -- 如果主机不受信任。

返回类型:

str

werkzeug.wsgi.get_content_length(environ)

返回 Content-Length 以整型表示的标头值。如果未给出标头或 Transfer-Encoding 标头为 chunked ， None 返回以指示流请求。如果值不是整数或负数，则返回0。

参数:

environ (WSGIEnvironment) -- 从中获取内容长度的WSGI环境。

返回类型:

int | None

Changelog

在 0.9 版本加入.

werkzeug.wsgi.get_input_stream(environ, safe_fallback=True, max_content_length=None)

返回经过包装的WSGI输入流，以便可以安全地读取它，而不需要经过 Content-Length 标题值或 max_content_length 。

如果 Content-Length 超过 max_content_length 一种 RequestEntityTooLarge ` 413 Content Too Large 出现错误。

如果WSGI服务器设置 environ["wsgi.input_terminated"] ，则表示服务器处理终止流，因此直接读取是安全的。例如，知道如何安全地处理分块请求的服务器将设置此设置。

如果 max_content_length 已设置，则可以在以下情况下在流上强制执行 wsgi.input_terminated 已经设置好了。否则，除非用户显式禁用此安全回退，否则将返回空流。

如果在基础流(如太大的文件或无限流)耗尽之前达到限制，则不能安全地读取流的其余内容。根据服务器对此的处理方式，客户端可能会显示“连接重置”失败，而不是看到413响应。

参数:

  • environ (WSGIEnvironment) -- 包含流的WSGI环境。

  • safe_fallback (bool) -- 在以下情况下返回空流 Content-Length 未设置。禁用此功能将允许无限数据流，这可能会带来拒绝服务风险。

  • max_content_length (int | None) -- 内容长度或流请求的最大长度不能超过。

返回类型:

t.IO[bytes]

Changelog

在 2.3.2 版本发生变更: max_content_length 仅适用于流请求，如果服务器设置 wsgi.input_terminated 。

在 2.3 版本发生变更: 检查 max_content_length 如果超过该值，则引发错误。

在 0.9 版本加入.

werkzeug.wsgi.get_current_url(environ, root_only=False, strip_querystring=False, host_only=False, trusted_hosts=None)

从WSGI环境中的部件重新创建请求的URL。

URL是IRI，而不是URI，因此它可能包含Unicode字符。使用 iri_to_uri() 将其转换为ASCII。

参数:

  • environ (WSGIEnvironment) -- 从中获取URL部件的WSGI环境。

  • root_only (bool) -- 只构建根路径，不包括剩余的路径或查询字符串。

  • strip_querystring (bool) -- 不包括查询字符串。

  • host_only (bool) -- 只需搭建方案和托管即可。

  • trusted_hosts (t.Iterable[str] | None) -- 验证主机所依据的受信任主机名列表。

返回类型:

str

werkzeug.wsgi.host_is_trusted(hostname, trusted_list)

检查主机是否与受信任名称列表匹配。

参数:

  • hostname (str) -- 要检查的名称。

  • trusted_list (Iterable[str]) -- 要匹配的有效名称列表。如果名称以点开头，它将匹配所有子域。

返回类型:

bool

Changelog

在 0.9 版本加入.

便利助手

werkzeug.wsgi.responder(f)

将函数标记为响应程序。用它修饰一个函数，它将自动调用返回值作为wsgi应用程序。

例子：：

@responder
def application(environ, start_response):
    return Response('Hello World!')
参数:

f (t.Callable[..., WSGIApplication]) --

返回类型:

WSGIApplication

werkzeug.testapp.test_app(req)

转储环境的简单测试应用程序。您可以使用它检查Werkzeug是否正常工作：

>>> from werkzeug.serving import run_simple
>>> from werkzeug.testapp import test_app
>>> run_simple('localhost', 3000, test_app)
 * Running on http://localhost:3000/

应用程序显示来自wsgi环境、python解释器和已安装的库的重要信息。

参数:

req (Request) --

返回类型:

Response

字节、字符串和编码

HTTP请求中的值以字节形式表示（或编码为）ASCII。WSGI规范 (PEP 3333 )决定一直使用 str 键入以表示值。为此，使用ISO-8859-1字符集对原始字节进行解码以生成一个字符串。

WSGI环境中的字符串仅限于ISO-8859-1代码点。如果从环境中读取的字符串可能包含该字符集之外的字符，则必须首先将其解码为ISO-8859-1字节，然后使用正确的字符集（通常为UTF-8）编码为字符串。当向环境写入时，则相反。这就是所谓的“WSGI编码舞蹈”。

Werkzeug提供了自动处理这一问题的功能，因此您不需要了解内部工作。同时使用此页面上的函数 EnvironHeaders() 从wsgi环境中读取数据。

应用程序应避免手动创建或修改wsgi环境，除非它们处理正确的编码或解码步骤。Werkzeug中的所有高级接口将根据需要应用编码和解码。

原始请求URI和路径编码

这个 PATH_INFO 在环境中是百分比解码后的路径值。例如，原始路径 /hello%2fworld 从wsgi服务器到werkzeug显示为 /hello/world .这将丢失斜杠是原始字符而不是路径分隔符的信息。

WSGi规范 (PEP 3333 ）不提供获取原始值的方法，因此无法在路径中路由某些类型的数据。解决此问题的最兼容方法是以查询字符串而不是路径发送有问题的数据。

但是，许多WSGI服务器都使用原始路径添加了一个非标准的environ key。为了匹配这种行为，Werkzeug的测试客户机和开发服务器将把原始值添加到 REQUEST_URI 和 RAW_URI 钥匙。如果要基于此值路由，可以使用中间件替换 PATH_INFO 在环境中到达应用程序之前。但是，请记住，这些钥匙是非标准的，不能保证存在。