# `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 `tornado4.web.RequestHandler.request`.

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

  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, value)

    Adds a new value for the given key.

  `get_list`(name)

    Returns all values for the given header as a list.

  `get_all`()

    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)

    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)

    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')]

class `tornado.httputil.``HTTPServerRequest`(method=None, uri=None, version='HTTP/1.0', headers=None, body=None, host=None, files=None, connection=None, start_line=None, server_connection=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.

    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 `tornado4.httpserver.HTTPRequest`.

  `supports_http_1_1`()

    Returns True if this request supports HTTP/1.1 semantics.

    Deprecated since version 4.0: Applications are less likely to need this information with the introduction of `HTTPConnection`. If you still need it, access the `version` attribute directly.

  `cookies`

    A dictionary of Cookie.Morsel objects.

  `write`(chunk, callback=None)

    Writes the given chunk to the response stream.

    Deprecated since version 4.0: Use `request.connection` and the `HTTPConnection` methods to write the response.

  `finish`()

    Finishes this HTTP request on the open connection.

    Deprecated since version 4.0: Use `request.connection` and the `HTTPConnection` methods to write the response.

  `full_url`()

    Reconstructs the full URL for this request.

  `request_time`()

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

  `get_ssl_certificate`(binary_form=False)

    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.

  New in version 4.0.

exception `tornado.httputil.``HTTPOutputError`

  Exception class for errors in HTTP output.

  New in version 4.0.

class `tornado.httputil.``HTTPServerConnectionDelegate`

  Implement this interface to handle requests from `HTTPServer`.

  New in version 4.0.

  `start_request`(server_conn, request_conn)

    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)

    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.

  New in version 4.0.

  `headers_received`(start_line, headers)

    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)

    Called when a chunk of data has been received.

    May return a `Future` for flow control.

  `finish`()

    Called after the last chunk of data has been received.

  `on_connection_close`()

    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.

  New in version 4.0.

  `write_headers`(start_line, headers, chunk=None, callback=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.
    - callback – a callback to be run when the write is complete.

    The `version` field of `start_line` is ignored.

    Returns a `Future` if no callback is given.

  `write`(chunk, callback=None)

    Writes a chunk of body data.

    The callback will be run when the write is complete. If no callback is given, returns a Future.

  `finish`()

    Indicates that the last body data has been written.

`tornado.httputil.``url_concat`(url, args)

  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, body, arguments, files, headers=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, data, arguments, files)

  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.

`tornado.httputil.``format_timestamp`(ts)

  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`

  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)

  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)

  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.``split_host_and_port`(netloc)

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

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

  New in version 4.1.

`tornado.httputil.``parse_cookie`(cookie)

  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.