tornado.httputil
— Manipulate HTTP headers and URLs¶
HTTP utility code shared by clients and servers.
This module also defines the HTTPServerRequest
class which is exposed
via tornado.web.RequestHandler.request
.
-
class
tornado.httputil.
HTTPHeaders
(*args, **kwargs)[source]¶ A dictionary that maintains
Http-Header-Case
for all keys.Supports multiple values per key via a pair of new methods,
add()
andget_list()
. The regular dictionary interface returns a single value per key, with multiple values joined by a comma.>>> 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
-
get_all
() → Iterable[Tuple[str, str]][source]¶ Returns an iterable of all (name, value) pairs.
If a header has multiple values, multiple pairs will be returned with the same name.
-
parse_line
(line: str) → None[source]¶ Updates the dictionary with a single header line.
>>> h = HTTPHeaders() >>> h.parse_line("Content-Type: text/html") >>> h.get('content-type') 'text/html'
-
classmethod
parse
(headers: str) → tornado.httputil.HTTPHeaders[source]¶ Returns a dictionary from HTTP header text.
>>> h = HTTPHeaders.parse("Content-Type: text/html\r\nContent-Length: 42\r\n") >>> sorted(h.items()) [('Content-Length', '42'), ('Content-Type', 'text/html')]
Changed in version 5.1: Raises
HTTPInputError
on malformed headers instead of a mix ofKeyError
, andValueError
.
-
-
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)[source]¶ A single HTTP request.
All attributes are type
str
unless otherwise noted.-
method
¶ HTTP request method, e.g. “GET” or “POST”
-
uri
¶ The requested uri.
-
version
¶ HTTP version specified in request, e.g. “HTTP/1.1”
-
headers
¶ HTTPHeaders
dictionary-like object for request headers. Acts like a case-insensitive dictionary with additional methods for repeated headers.
-
body
¶ Request body, if present, as a byte string.
-
remote_ip
¶ Client’s IP address as a string. If
HTTPServer.xheaders
is set, will pass along the real IP address provided by a load balancer in theX-Real-Ip
orX-Forwarded-For
header.
Changed in version 3.1: The list format of
X-Forwarded-For
is now supported.-
protocol
¶ The protocol used, either “http” or “https”. If
HTTPServer.xheaders
is set, will pass along the protocol used by a load balancer if reported via anX-Scheme
header.
-
host
¶ The requested hostname, usually taken from the
Host
header.
-
arguments
¶ GET/POST arguments are available in the arguments property, which maps arguments names to lists of values (to support multiple values for individual names). Names are of type
str
, while arguments are byte strings. Note that this is different fromRequestHandler.get_argument
, which returns argument values as unicode strings.
-
query_arguments
¶ Same format as
arguments
, but contains only arguments extracted from the query string.New in version 3.2.
-
body_arguments
¶ Same format as
arguments
, but contains only arguments extracted from the request body.New in version 3.2.
-
files
¶ File uploads are available in the files property, which maps file names to lists of
HTTPFile
.
-
connection
¶ An HTTP request is attached to a single HTTP connection, which can be accessed through the “connection” attribute. Since connections are typically kept open in HTTP/1.1, multiple requests can be handled sequentially on a single connection.
Changed in version 4.0: Moved from
tornado.httpserver.HTTPRequest
.A dictionary of
http.cookies.Morsel
objects.
-
get_ssl_certificate
(binary_form: bool = False) → Union[None, Dict[KT, VT], bytes][source]¶ Returns the client’s SSL certificate, if any.
To use client certificates, the HTTPServer’s
ssl.SSLContext.verify_mode
field must be set, e.g.: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)
By default, the return value is a dictionary (or None, if no client certificate is present). If
binary_form
is true, a DER-encoded form of the certificate is returned instead. See SSLSocket.getpeercert() in the standard library for more details. http://docs.python.org/library/ssl.html#sslsocket-objects
-
-
exception
tornado.httputil.
HTTPInputError
[source]¶ Exception class for malformed HTTP requests or responses from remote sources.
New in version 4.0.
-
exception
tornado.httputil.
HTTPOutputError
[source]¶ Exception class for errors in HTTP output.
New in version 4.0.
-
class
tornado.httputil.
HTTPServerConnectionDelegate
[source]¶ Implement this interface to handle requests from
HTTPServer
.New in version 4.0.
-
start_request
(server_conn: object, request_conn: tornado.httputil.HTTPConnection) → tornado.httputil.HTTPMessageDelegate[source]¶ This method is called by the server when a new request has started.
Parameters: - server_conn – is an opaque object representing the long-lived (e.g. tcp-level) connection.
- request_conn – is a
HTTPConnection
object for a single request/response exchange.
This method should return a
HTTPMessageDelegate
.
-
-
class
tornado.httputil.
HTTPMessageDelegate
[source]¶ Implement this interface to handle an HTTP request or response.
New in version 4.0.
-
headers_received
(start_line: Union[RequestStartLine, ResponseStartLine], headers: tornado.httputil.HTTPHeaders) → Optional[Awaitable[None]][source]¶ Called when the HTTP headers have been received and parsed.
Parameters: - start_line – a
RequestStartLine
orResponseStartLine
depending on whether this is a client or server message. - headers – a
HTTPHeaders
instance.
Some
HTTPConnection
methods can only be called duringheaders_received
.May return a
Future
; if it does the body will not be read until it is done.- start_line – a
-
-
class
tornado.httputil.
HTTPConnection
[source]¶ Applications use this interface to write their responses.
New in version 4.0.
-
write_headers
(start_line: Union[RequestStartLine, ResponseStartLine], headers: tornado.httputil.HTTPHeaders, chunk: Optional[bytes] = None) → Future[None][source]¶ Write an HTTP header block.
Parameters: - start_line – a
RequestStartLine
orResponseStartLine
. - headers – a
HTTPHeaders
instance. - chunk – the first (optional) chunk of data. This is an optimization so that small responses can be written in the same call as their headers.
The
version
field ofstart_line
is ignored.Returns a future for flow control.
Changed in version 6.0: The
callback
argument was removed.- start_line – a
-
-
tornado.httputil.
url_concat
(url: str, args: Union[None, Dict[str, str], List[Tuple[str, str]], Tuple[Tuple[str, str], ...]]) → str[source]¶ Concatenate url and arguments regardless of whether url has existing query parameters.
args
may be either a dictionary or a list of key-value pairs (the latter allows for multiple values with the same key.>>> 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]¶ Represents a file uploaded via a form.
For backwards compatibility, its instance attributes are also accessible as dictionary keys.
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[source]¶ Parses a form request body.
Supports
application/x-www-form-urlencoded
andmultipart/form-data
. Thecontent_type
parameter should be a string andbody
should be a byte string. Thearguments
andfiles
parameters are dictionaries that will be updated with the parsed contents.
-
tornado.httputil.
parse_multipart_form_data
(boundary: bytes, data: bytes, arguments: Dict[str, List[bytes]], files: Dict[str, List[tornado.httputil.HTTPFile]]) → None[source]¶ Parses a
multipart/form-data
body.The
boundary
anddata
parameters are both byte strings. The dictionaries given in the arguments and files parameters will be updated with the contents of the body.Changed in version 5.1: Now recognizes non-ASCII filenames in RFC 2231/5987 (
filename*=
) format.
-
tornado.httputil.
format_timestamp
(ts: Union[int, float, tuple, time.struct_time, datetime.datetime]) → str[source]¶ Formats a timestamp in the format used by HTTP.
The argument may be a numeric timestamp as returned by
time.time
, a time tuple as returned bytime.gmtime
, or adatetime.datetime
object.>>> format_timestamp(1359312200) 'Sun, 27 Jan 2013 18:43:20 GMT'
-
class
tornado.httputil.
RequestStartLine
¶ RequestStartLine(method, path, version)
Create new instance of RequestStartLine(method, path, version)
-
method
¶ Alias for field number 0
-
path
¶ Alias for field number 1
-
version
¶ Alias for field number 2
-
-
tornado.httputil.
parse_request_start_line
(line: str) → tornado.httputil.RequestStartLine[source]¶ Returns a (method, path, version) tuple for an HTTP 1.x request line.
The response is a
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)
Create new instance of ResponseStartLine(version, code, reason)
-
code
¶ Alias for field number 1
-
reason
¶ Alias for field number 2
-
version
¶ Alias for field number 0
-
-
tornado.httputil.
parse_response_start_line
(line: str) → tornado.httputil.ResponseStartLine[source]¶ Returns a (version, code, reason) tuple for an HTTP 1.x response line.
The response is a
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]¶ Encodes a username/password pair in the format used by HTTP auth.
The return value is a byte string in the form
username:password
.New in version 5.1.
-
tornado.httputil.
split_host_and_port
(netloc: str) → Tuple[str, Optional[int]][source]¶ Returns
(host, port)
tuple fromnetloc
.Returned
port
will beNone
if not present.New in version 4.1.
-
tornado.httputil.
qs_to_qsl
(qs: Dict[str, List[AnyStr]]) → Iterable[Tuple[str, AnyStr]][source]¶ Generator converting a result of
parse_qs
back to name-value pairs.New in version 5.0.
Parse a
Cookie
HTTP header into a dict of name/value pairs.This function attempts to mimic browser cookie parsing behavior; it specifically does not follow any of the cookie-related RFCs (because browsers don’t either).
The algorithm used is identical to that used by Django version 1.9.10.
New in version 4.4.2.