HTTP实用程序

Werkzeug提供了一些函数来解析和生成HTTP头,这些头在实现WSGI中间件或在较低层上操作时非常有用。所有这些功能也从请求和响应对象中公开。

DateTime函数

这些函数简化了在HTTP上下文中使用时间的过程。Werkzeug生产时区感知产品 datetime UTC格式的对象。当将DateTime对象传递给Werkzeug时,它假定任何简单的DateTime都是UTC格式。

当比较来自Werkzeug的DateTime值时,您自己的DateTime对象也必须是时区感知的,或者您必须使来自Werkzeug的值是朴素的。

  • dt = datetime.now(timezone.utc) 获取以UTC表示的当前时间。

  • dt = datetime(..., tzinfo=timezone.utc) 以UTC为单位创建时间。

  • dt = dt.replace(tzinfo=timezone.utc) 通过假设它在UTC中,使幼稚对象意识到。

  • dt = dt.replace(tzinfo=None) 使感知对象变得幼稚。

werkzeug.http.parse_date(value)

解析一个 RFC 2822 日期进入时区感知 datetime.datetime 对象,或 None 如果解析失败。

这是一个包装纸,用来包装 email.utils.parsedate_to_datetime() 。它会返回 None 如果分析失败而不是引发异常,则始终返回支持时区的DateTime对象。如果字符串没有时区信息,则假定它为UTC。

参数:

value (str | None) -- 具有支持的日期格式的字符串。

返回类型:

datetime | None

Changelog

在 2.0 版本发生变更: 返回支持时区的DateTime对象。使用 email.utils.parsedate_to_datetime

werkzeug.http.http_date(timestamp=None)

将DateTime对象或时间戳格式化为 RFC 2822 日期字符串。

这是一个包装纸,用来包装 email.utils.format_datetime() 。它假定朴素的DateTime对象使用UTC,而不是引发异常。

参数:

timestamp (datetime | date | int | float | struct_time | None) -- 要格式化的日期时间或时间戳。默认为当前时间。

返回类型:

str

Changelog

在 2.0 版本发生变更: 使用 email.utils.format_datetime 。接受 date 对象。

标题分析

以下函数可用于解析传入的HTTP头。因为python不提供具有 RFC 2616 ,werkzeug实现了一些自定义数据结构, documented separately .

werkzeug.http.parse_options_header(value)

解析由值组成的标头 key=value 用分号分隔的参数 ; 。例如, Content-Type 标题。

parse_options_header("text/html; charset=UTF-8")
('text/html', {'charset': 'UTF-8'})

parse_options_header("")
("", {})

这是与 dump_options_header()

这将解析有效的参数部分,如中所述 RFC 9110 。将跳过无效部件。

它处理延续和字符集,如 RFC 2231 ,尽管没有RFC那么严格。仅接受ASCII、UTF-8和ISO-8859-1字符集,否则值保持引号。

客户处理引号内的引号字符的方式可能不一致。这个 HTML Standard 将其替换为 %22 in multipart form data. RFC 9110 在HTTP标头中使用反斜杠转义。两者都被解码为 " 性格。

客户端处理非ASCII字符的方式可能不一致。HTML文档必须声明 <meta charset=UTF-8> ,否则浏览器可能会替换为HTML字符引用,该引用可以使用 html.unescape()

参数:

value (str | None) -- 要分析的标头值。

返回:

(value, options) ,在哪里 options 是一种判决书

返回类型:

tuple[str, dict[str, str]]

Changelog

在 2.3 版本发生变更: 无效部分(例如没有值的键、带引号的键和错误引用的值)将被丢弃,而不是视为 None

在 2.3 版本发生变更: 字符集值仅接受ASCII、UTF-8和ISO-8859-1。

在 2.3 版本发生变更: 引用值中的转义引号,如 %22\" ,都得到了处理。

在 2.2 版本发生变更: 选项名称始终转换为小写。

在 2.2 版本发生变更: 这个 multiple 参数已删除。

在 0.15 版本发生变更: RFC 2231 处理参数继续。

在 0.5 版本加入.

werkzeug.http.parse_set_header(value, on_update=None)

分析一个类似头的集合并返回 HeaderSet 对象:

>>> hs = parse_set_header('token, "quoted value"')

返回值是一个不敏感地处理项目大小写并保持项目顺序的对象:

>>> 'TOKEN' in hs
True
>>> hs.index('quoted value')
1
>>> hs
HeaderSet(['token', 'quoted value'])

从创建标题 HeaderSet 再次使用 dump_header() 功能。

参数:
返回:

HeaderSet

返回类型:

HeaderSet

werkzeug.http.parse_list_header(value)

解析由逗号分隔的项列表组成的标头值 RFC 9110

这延伸了 urllib.request.parse_http_list() 若要从值中删除引号,请执行以下操作。

parse_list_header('token, "quoted value"')
['token', 'quoted value']

这是与 dump_header()

参数:

value (str) -- 要分析的标头值。

返回类型:

list[str]

werkzeug.http.parse_dict_header(value)

使用以下命令解析列表头 parse_list_header() ,然后将每一项解析为 key=value 一对。

parse_dict_header('a=b, c="d, e", f')
{"a": "b", "c": "d, e", "f": None}

这是与 dump_header()

如果键没有值,则为 None

它处理值的字符集,如中所述 RFC 2231 。仅接受ASCII、UTF-8和ISO-8859-1字符集,否则值保持引号。

参数:

value (str) -- 要分析的标头值。

返回类型:

dict[str, str | None]

在 3.0 版本发生变更: 不支持传递字节。

在 3.0 版本发生变更: 这个 cls 参数已删除。

Changelog

在 2.3 版本发生变更: 添加了对以下各项的支持 key*=charset''value 编码项。

在 0.9 版本发生变更: 这个 cls 添加了参数。

werkzeug.http.parse_accept_header(value: str | None) Accept
werkzeug.http.parse_accept_header(value: str | None, cls: type[_TAnyAccept]) _TAnyAccept

解析AN Accept header according to RFC 9110

返回一个 Accept 实例,该实例可以根据项目的质量参数对其进行排序和检查。在解析时 Accept-CharsetAccept-Encoding ,或 Accept-Language ,传递相应的 Accept 子类。

参数:
  • value -- 要分析的标头值。

  • cls -- 这个 Accept 类来包装结果。

返回:

的一个实例 cls

Changelog

在 2.3 版本发生变更: 根据RFC 9110进行解析。包含无效项的项目 q 将跳过值。

werkzeug.http.parse_cache_control_header(value: str | None, on_update: Callable[[_TAnyCC], None] | None, cls: None = None) RequestCacheControl
werkzeug.http.parse_cache_control_header(value: str | None, on_update: Callable[[_TAnyCC], None] | None, cls: type[_TAnyCC]) _TAnyCC

分析缓存控件头。响应和请求缓存控件之间的RFC不同,此方法不同。你有责任不使用错误的控制声明。

Changelog

在 0.5 版本加入: 这个 cls 已添加。如果未指定不可变 RequestCacheControl 返回。

参数:
  • value -- 要分析的缓存控件头。

  • on_update -- 每次调用 CacheControl 对象已更改。

  • cls -- 返回对象的类。默认 RequestCacheControl 使用。

返回:

cls 对象。

werkzeug.http.parse_if_range_header(value)

分析可以是etag或日期的if范围头。返回 IfRange 对象。

Changelog

在 2.0 版本发生变更: 如果该值表示日期时间,则它是时区感知的。

在 0.7 版本加入.

参数:

value (str | None) --

返回类型:

IfRange

werkzeug.http.parse_range_header(value, make_inclusive=True)

将范围头解析为 Range 对象。如果标题丢失或格式不正确 None 返回。 ranges 是一个列表 (start, stop) 范围不包含的元组。

Changelog

在 0.7 版本加入.

参数:
  • value (str | None) --

  • make_inclusive (bool) --

返回类型:

Range | None

werkzeug.http.parse_content_range_header(value, on_update=None)

将范围头解析为 ContentRange 对象或 None 如果无法解析。

Changelog

在 0.7 版本加入.

参数:
返回类型:

ContentRange | None

收割台实用程序

以下实用程序可以很好地操作HTTP头,但不解析它们。如果要处理条件响应,或者要代理任意请求,但要删除不受支持的wsgi逐段头,则它们非常有用。还有一个函数可以从解析的数据创建HTTP头字符串。

werkzeug.http.is_entity_header(header)

检查标题是否为实体标题。

Changelog

在 0.5 版本加入.

参数:

header (str) -- 要测试的头。

返回:

True 如果是实体标题, False 否则。

返回类型:

bool

werkzeug.http.is_hop_by_hop_header(header)

检查头是否为HTTP/1.1“逐跳”头。

Changelog

在 0.5 版本加入.

参数:

header (str) -- 要测试的头。

返回:

True 如果是一个HTTP/1.1“逐跳”的头文件, False 否则。

返回类型:

bool

werkzeug.http.remove_entity_headers(headers, allowed=('expires', 'content-location'))

从列表中删除所有实体标题或 Headers 对象。此操作已到位。 ExpiresContent-Location 默认情况下不删除邮件头。原因是 RFC 2616 第10.3.5节规定了应发送的某些实体标题。

Changelog

在 0.5 版本发生变更: 补充 allowed 参数。

参数:
返回类型:

None

werkzeug.http.remove_hop_by_hop_headers(headers)

从列表中删除所有HTTP/1.1“逐跳”头,或 Headers 对象。此操作已到位。

Changelog

在 0.5 版本加入.

参数:

headers (Headers | list[tuple[str, str]]) -- 列表或 Headers 对象。

返回类型:

None

werkzeug.http.is_byte_range_valid(start, stop, length)

检查给定字节内容范围对于给定长度是否有效。

Changelog

在 0.7 版本加入.

参数:
  • start (int | None) --

  • stop (int | None) --

  • length (int | None) --

返回类型:

bool

werkzeug.http.quote_header_value(value, allow_token=True)

在标题值两边添加双引号。如果标头仅包含ASCII令牌字符,则将原样返回。如果标头包含 "\ 字符,则它们将使用附加的 \ 性格。

这是与 unquote_header_value()

参数:
  • value (Any) -- 要引用的价值。将被转换为字符串。

  • allow_token (bool) -- 禁用可将值引起来,即使它只包含令牌字符。

返回类型:

str

在 3.0 版本发生变更: 不支持传递字节。

在 3.0 版本发生变更: 这个 extra_chars 参数将被删除。

Changelog

在 2.3 版本发生变更: 如果该值是空字符串,则用引号将其引用。

在 0.5 版本加入.

werkzeug.http.unquote_header_value(value)

删除双引号并对斜杠转义进行解码 "\ 标题值中的字符。

这是与 quote_header_value()

参数:

value (str) -- 要取消引号的标题值。

返回类型:

str

在 3.0 版本发生变更: 这个 is_filename 参数将被删除。

werkzeug.http.dump_header(iterable)

从项目列表中生成标题值或 key=value 对,用逗号分隔 ,

这是与 parse_list_header()parse_dict_header() ,以及 parse_set_header()

如果值包含非令牌字符,则该值将被引号。

如果值为 None ,关键是单独输出。

在某些标头的某些键中,可以使用特殊的 key*=UTF-8''value 表格,其中 value 是百分比编码的。此函数不会自动生成该格式,但如果给定键以星号结尾 * ,则假定该值具有该形式,不再进一步报价。

dump_header(["foo", "bar baz"])
'foo, "bar baz"'

dump_header({"foo": "bar baz"})
'foo="bar baz"'
参数:

iterable (dict[str, Any] | Iterable[Any]) -- 要从中创建页眉的项。

返回类型:

str

在 3.0 版本发生变更: 这个 allow_token 参数将被删除。

Changelog

在 2.2.3 版本发生变更: 如果关键字以 * ,其价值将不会被引用。

Cookies

从字符串或WSGI环境解析cookie。

同一个键可以多次提供,值按顺序存储。违约 MultiDict 将首先具有第一个值,并且可以使用 MultiDict.getlist() .

参数:
  • header (WSGIEnvironment | str | None) -- 作为字符串的cookie头,或带有 HTTP_COOKIE 关键。

  • cls (type[ds.MultiDict] | None) -- 一个类似dict的类,用于存储已解析的cookie。默认为 MultiDict .

返回类型:

ds.MultiDict[str, str]

在 3.0 版本发生变更: 传递字节数,而 charseterrors 参数,被删除。

Changelog

在 1.0 版本发生变更: 返回A MultiDict 而不是 TypeConversionDict .

在 0.5 版本发生变更: 返回A TypeConversionDict 而不是常规的口述 cls 已添加参数。

创建一个Set-Cookie标头,但不使用 Set-Cookie 前缀。

返回值通常仅限于ASCII,因为绝大多数值都已正确转义,但这不能保证。它按照以下要求通过latin1进行隧道传输 PEP 3333

如果键包含Unicode字符,则返回值不是ASCII安全的。这在技术上与规范不符,但在野外发生。强烈建议不要对密钥使用非ASCII值。

参数:
  • max_age (timedelta | int | None) -- 应该是几秒钟,或者 None (默认)如果cookie只应与客户端的浏览器会话一样长。另外 timedelta 对象也被接受。

  • expires (str | datetime | int | float | None) -- 应该是 datetime 对象或Unix时间戳。

  • path (str | None) -- 将cookie限制为给定路径,默认情况下,它将跨越整个域。

  • domain (str | None) -- 如果要设置跨域Cookie,请使用此选项。例如, domain="example.com" 将设置域可读的Cookie www.example.comfoo.example.com 否则,Cookie将只被设置它的域读取。

  • secure (bool) -- cookie只能通过https提供

  • httponly (bool) -- 不允许javascript访问cookie。这是对cookie标准的扩展,可能不是所有浏览器都支持。

  • charset -- 字符串值的编码。

  • sync_expires (bool) -- 如果定义了最大使用期限,但未定义最大使用期限,则自动设置过期。

  • max_size (int) -- 如果最终头值超过此大小,则发出警告。默认值4093应该是安全的 supported by most browsers .设置为0可禁用此检查。

  • samesite (str | None) -- 限制cookie的范围,以便仅当请求是同一站点时才将其附加到请求。

  • key (str) --

  • value (str) --

返回类型:

str

在 3.0 版本发生变更: 传递字节数,而 charset 参数,则被删除。

Changelog

在 2.3.3 版本发生变更: 这个 path 参数为 / 默认情况下。

在 2.3.1 版本发生变更: 该值允许更多不带引号的字符。

在 2.3 版本发生变更: localhost 域名允许使用不带点的其他名称。前导圆点将被忽略。

在 2.3 版本发生变更: 这个 path 参数为 None 默认情况下。

在 1.0.0 版本发生变更: 'None' 接受 samesite .

条件响应帮助程序

对于条件响应,以下函数可能有用:

werkzeug.http.parse_etags(value)

分析etag头。

参数:

value (str | None) -- 要分析的标记头

返回:

一个 ETags 对象。

返回类型:

ETags

werkzeug.http.quote_etag(etag, weak=False)

引用一个etag。

参数:
  • etag (str) -- 要引用的etag。

  • weak (bool) -- 设置为 True 给它贴上“软弱”的标签。

返回类型:

str

werkzeug.http.unquote_etag(etag)

取消引用单个etag:

>>> unquote_etag('W/"bar"')
('bar', True)
>>> unquote_etag('"bar"')
('bar', False)
参数:

etag (str | None) -- 要取消引号的etag标识符。

返回:

(etag, weak) 元组。

返回类型:

tuple[str, bool] | tuple[None, None]

werkzeug.http.generate_etag(data)

为某些数据生成ETag。

Changelog

在 2.0 版本发生变更: 使用SHA-1。MD5在某些环境中可能不可用。

参数:

data (bytes) --

返回类型:

str

werkzeug.http.is_resource_modified(environ, etag=None, data=None, last_modified=None, ignore_if_range=True)

条件请求的便利方法。

参数:
  • environ (WSGIEnvironment) -- 要检查的请求的wsgi环境。

  • etag (str | None) -- 用于响应比较的ETag。

  • data (bytes | None) -- 或者,响应的数据使用 generate_etag() .

  • last_modified (datetime | str | None) -- 上次修改的可选日期。

  • ignore_if_range (bool) -- 如果 FalseIf-Range 将考虑标题。

返回:

True 如果资源被修改,否则 False .

返回类型:

bool

Changelog

在 2.0 版本发生变更: SHA-1用于生成数据的ETag值。MD5在某些环境中可能不可用。

在 1.0.0 版本发生变更: 对以下方法运行检查 GETHEAD .

常量

werkzeug.http.HTTP_STATUS_CODES

状态代码的dict->默认状态消息对。包装机和其他地方使用这种方法,在整个Werkzeug中将整数状态代码扩展为字符串。

表单数据分析

Werkzeug提供了与请求对象分开的表单解析函数,这样您就可以从普通的wsgi环境中访问表单数据。

表单数据分析器当前支持以下格式:

  • application/x-www-form-urlencoded

  • multipart/form-data

目前不支持嵌套的多部分(werkzeug 0.9),但任何现代Web浏览器都不使用它。

用法示例:

>>> from io import BytesIO
>>> from werkzeug.formparser import parse_form_data
>>> data = (
...     b'--foo\r\nContent-Disposition: form-data; name="test"\r\n'
...     b"\r\nHello World!\r\n--foo--"
... )
>>> environ = {
...     "wsgi.input": BytesIO(data),
...     "CONTENT_LENGTH": str(len(data)),
...     "CONTENT_TYPE": "multipart/form-data; boundary=foo",
...     "REQUEST_METHOD": "POST",
... }
>>> stream, form, files = parse_form_data(environ)
>>> stream.read()
b''
>>> form['test']
'Hello World!'
>>> not files
True

通常,wsgi环境是由wsgi网关提供的,传入数据是它的一部分。如果您想为UnitTesting生成这样的假wsgi环境,您可能需要使用 create_environ() 函数或 EnvironBuilder 相反。

class werkzeug.formparser.FormDataParser(stream_factory=None, max_form_memory_size=None, max_content_length=None, cls=None, silent=True, *, max_form_parts=None)

此类实现对werkzeug的表单数据的分析。它本身可以解析多部分和URL编码的表单数据。它可以子类化和扩展,但对于大多数mimetype,最好使用未接触的流,并将其作为请求对象上的单独属性公开。

参数:
  • stream_factory (TStreamFactory | None) -- 返回新的可读可写文件描述符的可选可调用对象。此可调用函数的工作方式与 Response._get_file_stream()

  • max_form_memory_size (int | None) -- 内存中存储的表单数据要接受的最大字节数。如果数据超过指定的值, RequestEntityTooLarge 引发异常。

  • max_content_length (int | None) -- 如果提供了该值,并且传输的数据比该值长, RequestEntityTooLarge 引发异常。

  • cls (type[MultiDict] | None) -- 要使用的可选dict类。如果未指定或 None 默认值 MultiDict 使用。

  • silent (bool) -- 如果设置为false,则不会捕获分析错误。

  • max_form_parts (int | None) -- 要分析的多部分部件的最大数量。如果超过该值,则会引发 RequestEntityTooLarge 引发异常。

在 3.0 版本发生变更: 这个 charseterrors 参数已删除。

在 3.0 版本发生变更: 这个 parse_functions 属性和 get_parse_func 方法:去除。

Changelog

在 2.2.3 版本发生变更: 添加了 max_form_parts 参数。

在 0.8 版本加入.

werkzeug.formparser.parse_form_data(environ, stream_factory=None, max_form_memory_size=None, max_content_length=None, cls=None, silent=True, *, max_form_parts=None)

分析环境中的表单数据,并将其作为元组返回到表单中 (stream, form, files) .如果传输方法是 POSTPUTPATCH .

如果传输数据的mimetype是 multipart/form-data 文件多部分将用 FileStorage 物体。如果mimetype未知,输入流将被包装并作为第一个参数返回,否则该流为空。

这是常用的 FormDataParser .

参数:
  • environ (WSGIEnvironment) -- 用于解析的wsgi环境。

  • stream_factory (TStreamFactory | None) -- 返回新的可读可写文件描述符的可选可调用对象。此可调用函数的工作方式与 Response._get_file_stream()

  • max_form_memory_size (int | None) -- 内存中存储的表单数据要接受的最大字节数。如果数据超过指定的值, RequestEntityTooLarge 引发异常。

  • max_content_length (int | None) -- 如果提供了该值,并且传输的数据比该值长, RequestEntityTooLarge 引发异常。

  • cls (type[MultiDict] | None) -- 要使用的可选dict类。如果未指定或 None 默认值 MultiDict 使用。

  • silent (bool) -- 如果设置为false,则不会捕获分析错误。

  • max_form_parts (int | None) -- 要分析的多部分部件的最大数量。如果超过该值,则会引发 RequestEntityTooLarge 引发异常。

返回:

形式中的元组 (stream, form, files) .

返回类型:

t_parse_result

在 3.0 版本发生变更: 这个 charseterrors 参数已删除。

Changelog

在 2.3 版本发生变更: 添加了 max_form_parts 参数。

在 0.5.1 版本加入: 添加了 silent 参数。

在 0.5 版本加入: 添加了 max_form_memory_sizemax_content_length ,以及 cls 参数。