`tornado.httputil` — 操作 HTTP 标头和 URL¶

客户端和服务器共享的 HTTP 实用程序代码。

此模块还定义了 HTTPServerRequest 类，该类通过 tornado.web.RequestHandler.request 公开。

class tornado.httputil.HTTPHeaders(__arg: Mapping[str, List[str]])[source]¶

class tornado.httputil.HTTPHeaders(__arg: Mapping[str, str])

class tornado.httputil.HTTPHeaders(*args: Tuple[str, str])

class tornado.httputil.HTTPHeaders(**kwargs: str)

一个字典，它为所有键维护 Http-Header-Case。

通过一对新方法支持每个键的多个值，add() 和 get_list()。常规字典接口每个键返回一个值，多个值用逗号连接。

>>> h = HTTPHeaders({"content-type": "text/html"})
>>> list(h.keys())
['Content-Type']
>>> h["Content-Type"]
'text/html'

>>> h.add("Set-Cookie", "A=B")
>>> h.add("Set-Cookie", "C=D")
>>> h["set-cookie"]
'A=B,C=D'
>>> h.get_list("set-cookie")
['A=B', 'C=D']

>>> for (k,v) in sorted(h.get_all()):
...    print('%s: %s' % (k,v))
...
Content-Type: text/html
Set-Cookie: A=B
Set-Cookie: C=D

add(name: str, value: str) → None[source]¶: 为给定键添加一个新值。

get_list(name: str) → List[str][source]¶: 将给定标头的所有值作为列表返回。

get_all() → Iterable[Tuple[str, str]][source]¶

返回所有 (name, value) 对的可迭代对象。

如果一个标头有多个值，则将返回多个具有相同名称的配对。

parse_line(line: str) → None[source]¶

使用单个标头行更新字典。

>>> h = HTTPHeaders()
>>> h.parse_line("Content-Type: text/html")
>>> h.get('content-type')
'text/html'

classmethod parse(headers: str) → HTTPHeaders[source]¶

从 HTTP 标头文本返回一个字典。

>>> h = HTTPHeaders.parse("Content-Type: text/html\r\nContent-Length: 42\r\n")
>>> sorted(h.items())
[('Content-Length', '42'), ('Content-Type', 'text/html')]

在版本 5.1 中更改：引发 HTTPInputError 而不是 KeyError 和 ValueError 的混合。

class tornado.httputil.HTTPServerRequest(method: Optional[str] = None, uri: Optional[str] = None, version: str = 'HTTP/1.0', headers: Optional[HTTPHeaders] = None, body: Optional[bytes] = None, host: Optional[str] = None, files: Optional[Dict[str, List[HTTPFile]]] = None, connection: Optional[HTTPConnection] = None, start_line: Optional[RequestStartLine] = None, server_connection: Optional[object] = None)[source]¶

单个 HTTP 请求。

所有属性类型为 str，除非另有说明。

method¶: HTTP 请求方法，例如“GET”或“POST”

uri¶: 请求的 uri。

path¶: uri 的路径部分

query¶: uri 的查询部分

version¶: 请求中指定的 HTTP 版本，例如“HTTP/1.1”

headers¶: 请求头部的 HTTPHeaders 字典类对象。它类似于不区分大小写的字典，并具有针对重复头的附加方法。

body¶: 如果存在，则为请求正文的字节字符串。

remote_ip¶: 客户端的 IP 地址，以字符串形式表示。如果设置了 HTTPServer.xheaders，则会传递负载均衡器在 X-Real-Ip 或 X-Forwarded-For 头部中提供的真实 IP 地址。

Changed in version 3.1: 现在支持 X-Forwarded-For 的列表格式。

protocol¶: 使用的协议，要么是“http”，要么是“https”。如果设置了 HTTPServer.xheaders，则会传递负载均衡器在 X-Scheme 头部中报告的协议。

host¶: 请求的主机名，通常取自 Host 头部。

arguments¶: GET/POST 参数在 arguments 属性中可用，该属性将参数名映射到值的列表（以支持单个名称的多个值）。名称类型为 str，而参数为字节字符串。请注意，这与 RequestHandler.get_argument 不同，后者将参数值作为 Unicode 字符串返回。

query_arguments¶: 与 arguments 格式相同，但仅包含从查询字符串中提取的参数。

新版本为 3.2。

body_arguments¶: 与 arguments 格式相同，但仅包含从请求正文中提取的参数。

新版本为 3.2。

files¶: 文件上传在 files 属性中可用，该属性将文件名映射到 HTTPFile 的列表。

connection¶: HTTP 请求附属于单个 HTTP 连接，可以通过“connection”属性访问。由于连接通常在 HTTP/1.1 中保持打开状态，因此可以在单个连接上按顺序处理多个请求。

Changed in version 4.0: 从 tornado.httpserver.HTTPRequest 移动。

property cookies: Dict[str, Morsel]¶: http.cookies.Morsel 对象的字典。

full_url() → str[source]¶: 重建此请求的完整 URL。

request_time() → float[source]¶: 返回此请求执行所花费的时间。

get_ssl_certificate(binary_form: bool = False) → Union[None, Dict, bytes][source]¶

返回客户端的 SSL 证书（如果有）。

要使用客户端证书，HTTPServer 的 ssl.SSLContext.verify_mode 字段必须设置，例如：

ssl_ctx = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
ssl_ctx.load_cert_chain("foo.crt", "foo.key")
ssl_ctx.load_verify_locations("cacerts.pem")
ssl_ctx.verify_mode = ssl.CERT_REQUIRED
server = HTTPServer(app, ssl_options=ssl_ctx)

默认情况下，返回值是一个字典（如果没有客户端证书，则为 None）。如果 binary_form 为真，则返回证书的 DER 编码形式。有关更多详细信息，请参阅标准库中的 SSLSocket.getpeercert()。 https://docs.pythonlang.cn/library/ssl.html#sslsocket-objects

exception tornado.httputil.HTTPInputError[source]¶: 用于来自远程源的格式错误的 HTTP 请求或响应的异常类。

版本 4.0 中新增。

exception tornado.httputil.HTTPOutputError[source]¶: 用于 HTTP 输出错误的异常类。

版本 4.0 中新增。

class tornado.httputil.HTTPServerConnectionDelegate[source]¶

实现此接口以处理来自 HTTPServer 的请求。

版本 4.0 中新增。

start_request(server_conn: object, request_conn: HTTPConnection) → HTTPMessageDelegate[source]¶

当新的请求开始时，此方法由服务器调用。

参数

server_conn – 是一个表示持久连接（例如 TCP 级别连接）的不透明对象。
request_conn – 是一个 HTTPConnection 对象，用于单个请求/响应交换。

此方法应返回一个 HTTPMessageDelegate。

on_close(server_conn: object) → None[source]¶

当连接已关闭时，此方法被调用。

参数: server_conn – 是一个服务器连接，它之前已传递给 start_request。

class tornado.httputil.HTTPMessageDelegate[source]¶

实现此接口以处理 HTTP 请求或响应。

版本 4.0 中新增。

headers_received(start_line: Union[RequestStartLine, ResponseStartLine], headers: HTTPHeaders) → Optional[Awaitable[None]][source]¶

当 HTTP 头部已接收并解析时调用。

参数

start_line – 一个 RequestStartLine 或 ResponseStartLine，具体取决于这是客户端还是服务器消息。
headers – 一个 HTTPHeaders 实例。

一些 HTTPConnection 方法只能在 headers_received 期间调用。

可以返回一个 Future；如果这样做，主体将不会在它完成之前读取。

data_received(chunk: bytes) → Optional[Awaitable[None]][source]¶

当收到数据块时调用。

可以返回一个 Future 用于流量控制。

finish() → None[source]¶: 在收到最后一块数据后调用。

on_connection_close() → None[source]¶

如果连接在请求完成之前关闭，则调用此方法。

如果调用了headers_received，则会调用finish或on_connection_close，但不会同时调用两者。

class tornado.httputil.HTTPConnection[source]¶

应用程序使用此接口来编写它们的响应。

版本 4.0 中新增。

write_headers(start_line: Union[RequestStartLine, ResponseStartLine], headers: HTTPHeaders, chunk: Optional[bytes] = None) → Future[None][source]¶

写入HTTP标头块。

参数

start_line – RequestStartLine或ResponseStartLine.
headers – 一个 HTTPHeaders 实例。
chunk – 第一个（可选）数据块。这是一个优化，以便可以与它们的标头在同一调用中写入小的响应。

start_line 的 version 字段被忽略。

返回一个用于流控制的未来。

Changed in version 6.0: The callback argument was removed.

write(chunk: bytes) → Future[None][source]¶

写入主体数据块。

返回一个用于流控制的未来。

Changed in version 6.0: The callback argument was removed.

finish() → None[source]¶: 指示已写入最后一个主体数据。

tornado.httputil.url_concat(url: str, args: Union[None, Dict[str, str], List[Tuple[str, str]], Tuple[Tuple[str, str], ...]]) → str[source]¶

连接 url 和参数，无论 url 是否具有现有的查询参数。

args 可以是字典或键值对列表（后者允许多个具有相同键的值）。

>>> url_concat("http://example.com/foo", dict(c="d"))
'http://example.com/foo?c=d'
>>> url_concat("http://example.com/foo?a=b", dict(c="d"))
'http://example.com/foo?a=b&c=d'
>>> url_concat("http://example.com/foo?a=b", [("c", "d"), ("c", "d2")])
'http://example.com/foo?a=b&c=d&c=d2'

class tornado.httputil.HTTPFile[source]¶

表示通过表单上传的文件。

为了向后兼容，它的实例属性也可以作为字典键访问。

filename
body
content_type

tornado.httputil.parse_body_arguments(content_type: str, body: bytes, arguments: Dict[str, List[bytes]], files: Dict[str, List[HTTPFile]], headers: Optional[HTTPHeaders] = None) → None[source]¶

解析表单请求体。

支持 application/x-www-form-urlencoded 和 multipart/form-data。 content_type 参数应为字符串，body 应为字节字符串。 arguments 和 files 参数是字典，将用解析后的内容更新。

tornado.httputil.parse_multipart_form_data(boundary: bytes, data: bytes, arguments: Dict[str, List[bytes]], files: Dict[str, List[HTTPFile]]) → None[source]¶

解析 multipart/form-data 体。

boundary 和 data 参数都是字节字符串。 arguments 和 files 参数中给出的字典将用 body 的内容更新。

Changed in version 5.1: 现在识别 RFC 2231/5987 (filename*=) 格式中的非 ASCII 文件名。

tornado.httputil.format_timestamp(ts: Union[int, float, tuple, struct_time, datetime]) → str[source]¶

以 HTTP 使用的格式格式化时间戳。

参数可以是 time.time 返回的数字时间戳，time.gmtime 返回的时间元组，或 datetime.datetime 对象。朴素的 datetime.datetime 对象被假定为表示 UTC；感知对象在格式化之前被转换为 UTC。

>>> format_timestamp(1359312200)
'Sun, 27 Jan 2013 18:43:20 GMT'

class tornado.httputil.RequestStartLine(method, path, version)¶

RequestStartLine(method, path, version)

创建 RequestStartLine(method, path, version) 的新实例

method¶: 字段号 0 的别名

path¶: 字段号 1 的别名

version¶: 字段号 2 的别名

tornado.httputil.parse_request_start_line(line: str) → RequestStartLine[source]¶

返回 HTTP 1.x 请求行的 (method, path, version) 元组。

响应是 collections.namedtuple。

>>> parse_request_start_line("GET /foo HTTP/1.1")
RequestStartLine(method='GET', path='/foo', version='HTTP/1.1')

class tornado.httputil.ResponseStartLine(version, code, reason)¶

ResponseStartLine(version, code, reason)

创建 ResponseStartLine(version, code, reason) 的新实例

code¶: 字段号 1 的别名

reason¶: 字段号 2 的别名

version¶: 字段号 0 的别名

tornado.httputil.parse_response_start_line(line: str) → ResponseStartLine[source]¶

返回 HTTP 1.x 响应行的 (版本, 代码, 原因) 元组。

响应是 collections.namedtuple。

>>> parse_response_start_line("HTTP/1.1 200 OK")
ResponseStartLine(version='HTTP/1.1', code=200, reason='OK')

tornado.httputil.encode_username_password(username: Union[str, bytes], password: Union[str, bytes]) → bytes[source]¶

以 HTTP 身份验证中使用的格式编码用户名/密码对。

返回值是一个字节串，形式为 username:password。

版本 5.1 中的新增功能。

tornado.httputil.split_host_and_port(netloc: str) → Tuple[str, Optional[int]][source]¶

从 netloc 返回 (host, port) 元组。

如果未提供，则返回的 port 将为 None。

版本 4.1 中的新增功能。

tornado.httputil.qs_to_qsl(qs: Dict[str, List]) → Iterable[Tuple[str, AnyStr]][source]¶: 生成器，将 parse_qs 的结果转换回名称-值对。

版本 5.0 中的新增功能。

tornado.httputil.parse_cookie(cookie: str) → Dict[str, str][source]¶

将 Cookie HTTP 标头解析为名称/值对字典。

此函数试图模仿浏览器 cookie 解析行为；它特别不遵循任何与 cookie 相关的 RFC（因为浏览器也不遵循）。

使用的算法与 Django 版本 1.9.10 中使用的算法相同。

版本 4.4.2 中的新增功能。

tornado.httputil — 操作 HTTP 标头和 URL¶

`tornado.httputil` — 操作 HTTP 标头和 URL¶