Tornado 操作HTTP表头和URL

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

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

class tornado.httputil.HTTPHeaders(*args, **kwargs)

为​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

为给定键添加新值。

get_list(name: str) → List[str]

将给定表头的所有值作为列表返回。

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

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

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

parse_line(line: str) → None

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

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

classmethod parse(headers: str) → tornado.httputil.HTTPHeaders

从 HTTP 表头文本返回字典。

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

class tornado.httputil.HTTPServerRequest(method: Optional[str] = None, uri: Optional[str] = None, version: str = 'HTTP/1.0', headers: Optional[tornado.httputil.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)

单个 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 地址。
• protocol
​：使用的协议，“http”或“https”。 如果设置了 HTTPServer.xheaders，如果通过 X-Scheme 表头报告，将传递负载均衡器使用的协议。
• ​host​：请求的主机名，通常取自 Host 表头。
• ​arguments​：GET/POST 参数在 arguments 属性中可用，它将参数名称映射到值列表（以支持单个名称的多个值）。 名称是 str 类型，而参数是字节字符串。 请注意，这与 RequestHandler.get_argument 不同，后者将参数值作为 unicode 字符串返回。
• ​query_arguments​：与参数的格式相同，但仅包含从查询字符串中提取的参数。
• ​body_arguments​：与参数格式相同，但仅包含从请求正文中提取的参数。
• ​files​：文件上传可在 files 属性中使用，它将文件名映射到 HTTPFile 列表。
• ​connectionHTTP​：请求附加到单个 HTTP 连接，可以通过“connection”属性访问。 由于连接通常在 HTTP/1.1 中保持打开状态，因此可以在单个连接上按顺序处理多个请求。
• ​cookies​：http.cookies.Morsel 对象的字典。
• ​full_url() → str​：[source]重构此请求的完整 URL。
• ​request_time() → float​：[source]返回此请求执行所花费的时间。
• ​get_ssl_certificate(binary_form: bool = False) → Union[None, Dict[KT, VT], bytes]​：返回客户端的 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 编码形式的证书。

exception tornado.httputil.HTTPInputError

来自远程源的格式错误的HTTP请求或响应的异常类。

exception tornado.httputil.HTTPOutputError

HTTP 输出中的错误的异常类。

class tornado.httputil.HTTPServerConnectionDelegate

实现这个接口来处理来自 HTTPServer 的请求。

start_request(server_conn: object, request_conn: tornado.httputil.HTTPConnection) → tornado.httputil.HTTPMessageDelegate

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

参数：

​server_conn ​– 是一个不透明的对象，表示长生命（例如 tcp 级别）连接。

​request_conn​ – 是单个请求/响应交换的 HTTPConnection 对象。

此方法应返回 ​HTTPMessageDelegate​。

on_close(server_conn: object) → None

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

参数： ​

server_conn ​– 是先前已传递给 start_request 的服务器连接。

class tornado.httputil.HTTPMessageDelegate

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

headers_received(start_line: Union[RequestStartLine, ResponseStartLine], headers: tornado.httputil.HTTPHeaders) → Optional[Awaitable[None]]

在接收并解析 HTTP 表头时调用。

参数：

​start_line ​– RequestStartLine 或 ResponseStartLine 取决于这是客户端消息还是服务器消息。

​headers​——一个 HTTPHeaders 实例。

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

可能返回一个 ​Future​； 如果确实如此，则在完成之前不会读取正文。

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

当收到一大块数据时调用。

可能会返回 ​Future ​进行流量控制。

finish() → None

在收到最后一块数据后调用。

on_connection_close() → None

如果连接在未完成请求的情况下关闭，则调用。

如果 ​headers_received ​被调用，​finish ​或 ​on_connection_close ​将被调用，但不会同时调用。

class tornado.httputil.HTTPConnection

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

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

编写一个 HTTP 标头块。

参数：

​start_line ​– RequestStartLine 或 ResponseStartLine。

​headers​——一个 HTTPHeaders 实例。

​chunk ​– 第一个（可选）数据块。 这是一种优化，以便可以在与标题相同的调用中写入小的响应。

​start_line的版本字段被忽略。

返回一个用于流控制的 future。

在 6.0 版更改: ​callback​参数已删除。

write(chunk: bytes) → Future[None]

写入一大块正文数据。

返回一个用于流控制的 future。

在 6.0 版更改: ​callback​参数已删除。

finish() → None

表示最后的正文数据已被写入。

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

无论 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

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

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

• ​filename​
• ​body​
• ​content_type​

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

解析表单请求正文。

支持 ​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[tornado.httputil.HTTPFile]]) → None

解析多部分/表单数据主体。

边界和数据参数都是字节串。 ​arguments ​和 ​files ​参数中给出的字典将使用正文的内容进行更新。

在 5.1 版更改: 现在可以识别 RFC 2231/5987 (​filename*=​) 格式的非 ASCII 文件名。

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

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

参数可以是 ​time.time​ 返回的数字时间戳、​time.gmtime​ 返回的时间元组或 ​datetime.datetime​ 对象。

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

class tornado.httputil.RequestStartLine

RequestStartLine（method、path、version）
创建 RequestStartLine 的新实例（method、path、version）
​method​：字段编号 0 的别名
​path​：字段编号 1 的别名
​version​：字段编号 2 的别名

tornado.httputil.parse_request_start_line(line: str) → tornado.httputil.RequestStartLine

返回 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

ResponseStartLine（version、code、reason）
创建 ResponseStartLine（version、code、reason）的新实例
​code​：字段编号 1 的别名
​reason​：字段编号 2 的别名
​version​：字段编号 0 的别名

tornado.httputil.parse_response_start_line(line: str) → tornado.httputil.ResponseStartLine

返回 HTTP 1.x 响应行的（version、code、reason）元组。
响应是一个​ 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

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

返回值是格式为 ​username:password​ 的字节字符串。

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

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

如果不存在，则返回的​port​将为 ​None​。

tornado.httputil.qs_to_qsl(qs: Dict[str, List[AnyStr]]) → Iterable[Tuple[str, AnyStr]]

生成器将 ​parse_qs​ 的结果转换回名称-值对。

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

将 ​CookieHTTP 表头解析为名称/值对的字典。

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

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