`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(__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)

A dictionary that maintains Http-Header-Case for all keys.

Supports multiple values per key via a pair of new methods, add() and get_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

add(name: str, value: str) → None[source]¶: Adds a new value for the given key.

get_list(name: str) → List[str][source]¶: Returns all values for the given header as a list.

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) → 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 of KeyError, and 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]¶

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.

path¶: The path portion of uri

query¶: The query portion of 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 the X-Real-Ip or X-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 an X-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 from RequestHandler.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.

property cookies: Dict[str, Morsel]¶: A dictionary of http.cookies.Morsel objects.

full_url() → str[source]¶: Reconstructs the full URL for this request.

request_time() → float[source]¶: Returns the amount of time it took for this request to execute.

get_ssl_certificate(binary_form: bool = False) → Union[None, Dict, 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: HTTPConnection) → 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.

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

This method is called when a connection has been closed.

Parameters: server_conn – is a server connection that has previously been passed to start_request.

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: HTTPHeaders) → Optional[Awaitable[None]][source]¶

Called when the HTTP headers have been received and parsed.

Parameters

start_line – a RequestStartLine or ResponseStartLine depending on whether this is a client or server message.
headers – a HTTPHeaders instance.

Some HTTPConnection methods can only be called during headers_received.

May return a Future; if it does the body will not be read until it is done.

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

Called when a chunk of data has been received.

May return a Future for flow control.

finish() → None[source]¶: Called after the last chunk of data has been received.

on_connection_close() → None[source]¶

Called if the connection is closed without finishing the request.

If headers_received is called, either finish or on_connection_close will be called, but not both.

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: HTTPHeaders, chunk: Optional[bytes] = None) → Future[None][source]¶

Write an HTTP header block.

Parameters

start_line – a RequestStartLine or ResponseStartLine.
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 of start_line is ignored.

Returns a future for flow control.

Changed in version 6.0: The callback argument was removed.

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

Writes a chunk of body data.

Returns a future for flow control.

Changed in version 6.0: The callback argument was removed.

finish() → None[source]¶: Indicates that the last body data has been written.

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[HTTPFile]], headers: Optional[HTTPHeaders] = None) → None[source]¶

Parses a form request body.

Supports application/x-www-form-urlencoded and multipart/form-data. The content_type parameter should be a string and body should be a byte string. The arguments and files 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[HTTPFile]]) → None[source]¶

Parses a multipart/form-data body.

The boundary and data 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, struct_time, 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 by time.gmtime, or a datetime.datetime object.

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

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

RequestStartLine(method, path, version)

Create new instance of RequestStartLine(method, path, version)

property method¶: Alias for field number 0

property path¶: Alias for field number 1

property version¶: Alias for field number 2

tornado.httputil.parse_request_start_line(line: str) → 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(version, code, reason)¶

ResponseStartLine(version, code, reason)

Create new instance of ResponseStartLine(version, code, reason)

property code¶: Alias for field number 1

property reason¶: Alias for field number 2

property version¶: Alias for field number 0

tornado.httputil.parse_response_start_line(line: str) → 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 from netloc.

Returned port will be None if not present.

New in version 4.1.

tornado.httputil.qs_to_qsl(qs: Dict[str, List]) → Iterable[Tuple[str, AnyStr]][source]¶: Generator converting a result of parse_qs back to name-value pairs.

New in version 5.0.

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

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.

tornado.httputil — Manipulate HTTP headers and URLs¶

`tornado.httputil` — Manipulate HTTP headers and URLs¶