# `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]])
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, *, _chars_are_bytes: bool = True) → None

    Adds a new value for the given key.

  get_list(name: str) → List[str]

    Returns all values for the given header as a list.

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

    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, *, _chars_are_bytes: bool = True) → None

    Updates the dictionary with a single header line.

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

    Changed in version 6.5: Now supports lines with or without the trailing CRLF, making it possible to pass lines from AsyncHTTPClient’s header_callback directly to this method.

    Deprecated since version 6.5: In Tornado 7.0, certain deprecated features of HTTP will become errors. Specifically, line folding and the use of LF (with CR) as a line separator will be removed.

  classmethod parse(headers: str, *, _chars_are_bytes: bool = True) → HTTPHeaders

    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: str | None = None, uri: str | None = None, version: str = 'HTTP/1.0', headers: HTTPHeaders | None = None, body: bytes | None = None, host: str | None = None, files: Dict[str, List[HTTPFile]] | None = None, connection: HTTPConnection | None = None, start_line: RequestStartLine | None = None, server_connection: object | None = None)

  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.

    Added in version 3.2.

  body_arguments

    Same format as `arguments`, but contains only arguments extracted from the request body.

    Added 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`.

  Deprecated since version 6.5.2: The `host` argument to the `HTTPServerRequest` constructor is deprecated. Use `headers["Host"]` instead. This argument was mistakenly removed in Tornado 6.5.0 and temporarily restored in 6.5.2.

  property cookies: Dict[str, Morsel]

    A dictionary of `http.cookies.Morsel` objects.

  full_url() → str

    Reconstructs the full URL for this request.

  request_time() → float

    Returns the amount of time it took for this request to execute.

  get_ssl_certificate(binary_form: bool = False) → None | Dict | bytes

    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

  Exception class for malformed HTTP requests or responses from remote sources.

  Added in version 4.0.

exception tornado.httputil.HTTPOutputError

  Exception class for errors in HTTP output.

  Added in version 4.0.

class tornado.httputil.HTTPServerConnectionDelegate

  Implement this interface to handle requests from `HTTPServer`.

  Added in version 4.0.

  start_request(server_conn: object, request_conn: HTTPConnection) → HTTPMessageDelegate

    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

    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

  Implement this interface to handle an HTTP request or response.

  Added in version 4.0.

  headers_received(start_line: RequestStartLine | ResponseStartLine, headers: HTTPHeaders) → Awaitable[None] | None

    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) → Awaitable[None] | None

    Called when a chunk of data has been received.

    May return a `Future` for flow control.

  finish() → None

    Called after the last chunk of data has been received.

  on_connection_close() → None

    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

  Applications use this interface to write their responses.

  Added in version 4.0.

  write_headers(start_line: RequestStartLine | ResponseStartLine, headers: HTTPHeaders, chunk: bytes | None = None) → Future[None]

    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]

    Writes a chunk of body data.

    Returns a future for flow control.

    Changed in version 6.0: The `callback` argument was removed.

  finish() → None

    Indicates that the last body data has been written.

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

  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

  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: HTTPHeaders | None = None) → None

  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

  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: int | float | tuple | struct_time | datetime) → str

  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. Naive `datetime.datetime` objects are assumed to represent UTC; aware objects are converted to UTC before formatting.

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

class tornado.httputil.RequestStartLine(method: str, path: str, version: str)

  RequestStartLine(method, path, version)

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

  method: str

    Alias for field number 0

  path: str

    Alias for field number 1

  version: str

    Alias for field number 2

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

  Returns a (method, path, version) tuple for an HTTP 1.x request line.

  The response is a `typing.NamedTuple`.

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

class tornado.httputil.ResponseStartLine(version: str, code: int, reason: str)

  ResponseStartLine(version, code, reason)

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

  version: str

    Alias for field number 0

  code: int

    Alias for field number 1

  reason: str

    Alias for field number 2

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

  Returns a (version, code, reason) tuple for an HTTP 1.x response line.

  The response is a `typing.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: str | bytes, password: str | bytes) → bytes

  Encodes a username/password pair in the format used by HTTP auth.

  The return value is a byte string in the form `username:password`.

  Added in version 5.1.

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

  Returns `(host, port)` tuple from `netloc`.

  Returned `port` will be `None` if not present.

  Added in version 4.1.

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

  Generator converting a result of `parse_qs` back to name-value pairs.

  Added in version 5.0.

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

  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.

  Added in version 4.4.2.