Hide navigation sidebar
Hide table of contents sidebar
Support urllib3 on GitHub Sponsors
Back to top
Toggle table of contents sidebar

# Response and Decoders

## Response

class urllib3.response.HTTPResponse(body='', headers=None, status=0, version=0, reason=None, strict=0, preload_content=True, decode_content=True, original_response=None, pool=None, connection=None, msg=None, retries=None, enforce_content_length=False, request_method=None, request_url=None, auto_close=True)

  Bases: `IOBase`

  HTTP Response container.

  Backwards-compatible with `http.client.HTTPResponse` but the response `body` is loaded and decoded on-demand when the `data` property is accessed. This class is also compatible with the Python standard library’s `io` module, and can hence be treated as a readable object in the context of that framework.

  Extra parameters for behaviour not present in `http.client.HTTPResponse`:

  Parameters:

    - preload_content – If True, the response’s body will be preloaded during construction.

    - decode_content – If True, will attempt to decode the body based on the ‘content-encoding’ header.

    - original_response – When this HTTPResponse wrapper is generated from an `http.client.HTTPResponse` object, it’s convenient to include the original for debug purposes. It’s otherwise unused.

    - retries – The retries contains the last `Retry` that was used during the request.

    - enforce_content_length – Enforce content length checking. Body returned by server must match value of Content-Length header, if present. Otherwise, raise error.

  CONTENT_DECODERS = ['gzip', 'deflate', 'br']
  DECODER_ERROR_CLASSES = (<class 'OSError'>, <class 'zlib.error'>, <class 'brotli.error'>)
  REDIRECT_STATUSES = [301, 302, 303, 307, 308]
  close()

    Flush and close the IO object.

    This method has no effect if the file is already closed.

  property closed
  property connection
  property data
  drain_conn()

    Read and discard any remaining HTTP response data in the response connection.

    Unread data in the HTTPResponse connection blocks the connection from being released back to the pool.

  fileno()

    Returns underlying file descriptor if one exists.

    OSError is raised if the IO object does not use a file descriptor.

  flush()

    Flush write buffers, if applicable.

    This is not implemented for read-only and non-blocking streams.

  classmethod from_httplib(r, **response_kw)

    Given an `http.client.HTTPResponse` instance `r`, return a corresponding `urllib3.response.HTTPResponse` object.

    Remaining parameters are passed to the HTTPResponse constructor, along with `original_response=r`.

  get_redirect_location()

    Should we redirect and where to?

    Returns:

      Truthy redirect location string if we got a redirect status code and valid location. `None` if redirect status and no location. `False` if not a redirect status code.

  getheader(name, default=None)
  getheaders()
  geturl()

    Returns the URL that was the source of this response. If the request that generated this response redirected, this method will return the final redirect location.

  info()
  isclosed()
  read(amt=None, decode_content=None, cache_content=False)

    Similar to `http.client.HTTPResponse.read()`, but with two additional parameters: `decode_content` and `cache_content`.

    Parameters:

      - amt – How much of the content to read. If specified, caching is skipped because it doesn’t make sense to cache partial content as the full response.

      - decode_content – If True, will attempt to decode the body based on the ‘content-encoding’ header.

      - cache_content – If True, will save the returned data such that the same result is returned despite of the state of the underlying file object. This is useful if you want the `.data` property to continue working after having `.read()` the file object. (Overridden if `amt` is set.)

  read_chunked(amt=None, decode_content=None)

    Similar to `HTTPResponse.read()`, but with an additional parameter: `decode_content`.

    Parameters:

      - amt – How much of the content to read. If specified, caching is skipped because it doesn’t make sense to cache partial content as the full response.

      - decode_content – If True, will attempt to decode the body based on the ‘content-encoding’ header.

  readable()

    Return whether object was opened for reading.

    If False, read() will raise OSError.

  readinto(b)
  release_conn()
  stream(amt=65536, decode_content=None)

    A generator wrapper for the read() method. A call will block until `amt` bytes have been read from the connection or until the connection is closed.

    Parameters:

      - amt – How much of the content to read. The generator will return up to much data per iteration, but may return less. This is particularly likely when using compressed data. However, the empty string will never be returned.

      - decode_content – If True, will attempt to decode the body based on the ‘content-encoding’ header.

  supports_chunked_reads()

    Checks if the underlying file-like object looks like a `http.client.HTTPResponse` object. We do this by testing for the fp attribute. If it is present we assume it returns raw chunks as processed by read_chunked().

  tell()

    Obtain the number of bytes pulled over the wire so far. May differ from the amount of content returned by :meth:`urllib3.response.HTTPResponse.read` if bytes are encoded on the wire (e.g, compressed).

## Decoders

Decoder classes are used for transforming compressed HTTP bodies using the `Content-Encoding` into their uncompressed binary representation.

class urllib3.response.BrotliDecoder

class urllib3.response.DeflateDecoder

class urllib3.response.GzipDecoder

class urllib3.response.MultiDecoder(modes)
  From RFC7231:

    If one or more encodings have been applied to a representation, the sender that applied the encodings MUST generate a Content-Encoding header field that lists the content codings in the order in which they were applied.