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。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) -- 要格式化的日期时间或时间戳。默认为当前时间。
- 返回类型:
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
是一种判决书- 返回类型:
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()
功能。
- werkzeug.http.parse_list_header(value)¶
解析由逗号分隔的项列表组成的标头值 RFC 9110 。
这延伸了
urllib.request.parse_http_list()
若要从值中删除引号,请执行以下操作。parse_list_header('token, "quoted value"') ['token', 'quoted value']
这是与
dump_header()
。
- 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字符集,否则值保持引号。
在 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-Charset
,Accept-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 版本加入.
- werkzeug.http.parse_range_header(value, make_inclusive=True)¶
将范围头解析为
Range
对象。如果标题丢失或格式不正确 None 返回。 ranges 是一个列表(start, stop)
范围不包含的元组。Changelog
在 0.7 版本加入.
- werkzeug.http.parse_content_range_header(value, on_update=None)¶
将范围头解析为
ContentRange
对象或 None 如果无法解析。Changelog
在 0.7 版本加入.
- 参数:
value (str | None) -- 要分析的内容范围头。
on_update (Callable[[ContentRange], None] | None) -- 每次调用
ContentRange
对象已更改。
- 返回类型:
ContentRange | None
收割台实用程序¶
以下实用程序可以很好地操作HTTP头,但不解析它们。如果要处理条件响应,或者要代理任意请求,但要删除不受支持的wsgi逐段头,则它们非常有用。还有一个函数可以从解析的数据创建HTTP头字符串。
- werkzeug.http.is_entity_header(header)¶
检查标题是否为实体标题。
Changelog
在 0.5 版本加入.
- werkzeug.http.is_hop_by_hop_header(header)¶
检查头是否为HTTP/1.1“逐跳”头。
Changelog
在 0.5 版本加入.
- werkzeug.http.remove_entity_headers(headers, allowed=('expires', 'content-location'))¶
从列表中删除所有实体标题或
Headers
对象。此操作已到位。 Expires 和 Content-Location 默认情况下不删除邮件头。原因是 RFC 2616 第10.3.5节规定了应发送的某些实体标题。Changelog
在 0.5 版本发生变更: 补充 allowed 参数。
- werkzeug.http.remove_hop_by_hop_headers(headers)¶
从列表中删除所有HTTP/1.1“逐跳”头,或
Headers
对象。此操作已到位。Changelog
在 0.5 版本加入.
- werkzeug.http.is_byte_range_valid(start, stop, length)¶
检查给定字节内容范围对于给定长度是否有效。
Changelog
在 0.7 版本加入.
- werkzeug.http.quote_header_value(value, allow_token=True)¶
在标题值两边添加双引号。如果标头仅包含ASCII令牌字符,则将原样返回。如果标头包含
"
或\
字符,则它们将使用附加的\
性格。这是与
unquote_header_value()
。在 3.0 版本发生变更: 不支持传递字节。
在 3.0 版本发生变更: 这个
extra_chars
参数将被删除。Changelog
在 2.3 版本发生变更: 如果该值是空字符串,则用引号将其引用。
在 0.5 版本加入.
- werkzeug.http.unquote_header_value(value)¶
删除双引号并对斜杠转义进行解码
"
和\
标题值中的字符。这是与
quote_header_value()
。在 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"'
在 3.0 版本发生变更: 这个
allow_token
参数将被删除。Changelog
在 2.2.3 版本发生变更: 如果关键字以
*
,其价值将不会被引用。
条件响应帮助程序¶
对于条件响应,以下函数可能有用:
- werkzeug.http.parse_etags(value)¶
分析etag头。
- werkzeug.http.quote_etag(etag, weak=False)¶
引用一个etag。
- werkzeug.http.unquote_etag(etag)¶
取消引用单个etag:
>>> unquote_etag('W/"bar"') ('bar', True) >>> unquote_etag('"bar"') ('bar', False)
- werkzeug.http.generate_etag(data)¶
为某些数据生成ETag。
Changelog
在 2.0 版本发生变更: 使用SHA-1。MD5在某些环境中可能不可用。
- 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) -- 如果 False , If-Range 将考虑标题。
- 返回:
True 如果资源被修改,否则 False .
- 返回类型:
Changelog
在 2.0 版本发生变更: SHA-1用于生成数据的ETag值。MD5在某些环境中可能不可用。
在 1.0.0 版本发生变更: 对以下方法运行检查
GET
和HEAD
.
常量¶
- 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 版本发生变更: 这个
charset
和errors
参数已删除。在 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)
.如果传输方法是 POST , PUT 或 PATCH .如果传输数据的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 版本发生变更: 这个
charset
和errors
参数已删除。Changelog
在 2.3 版本发生变更: 添加了
max_form_parts
参数。在 0.5.1 版本加入: 添加了
silent
参数。在 0.5 版本加入: 添加了
max_form_memory_size
,max_content_length
,以及cls
参数。