Response and Decoders#
Response#
- class urllib3.response.BaseHTTPResponse(*, headers=None, status, version, reason, decode_content, request_url, retries=None)#
Bases:
IOBase
- Parameters:
- CONTENT_DECODERS = ['gzip', 'deflate', 'br', 'zstd']#
- DECODER_ERROR_CLASSES: tuple[type[Exception], ...] = (<class 'OSError'>, <class 'zlib.error'>, <class 'brotli.error'>, <class 'zstd.ZstdError'>)#
- 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.
- Return type:
None
- property connection: HTTPConnection | None#
- drain_conn()#
- Return type:
None
- 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.- Return type:
str | None | Literal[False]
- getheader(name, default=None)#
- getheaders()#
- Return type:
HTTPHeaderDict
- info()#
- Return type:
HTTPHeaderDict
- json()#
Parses the body of the HTTP response as JSON.
To use a custom JSON decoder pass the result of
HTTPResponse.data
to the decoder.This method can raise either UnicodeDecodeError or json.JSONDecodeError.
Read more here.
- Return type:
- read(amt=None, decode_content=None, cache_content=False)#
- read_chunked(amt=None, decode_content=None)#
- release_conn()#
- Return type:
None
- stream(amt=65536, decode_content=None)#
- class urllib3.response.HTTPResponse(body='', headers=None, status=0, version=0, reason=None, preload_content=True, decode_content=True, original_response=None, pool=None, connection=None, msg=None, retries=None, enforce_content_length=True, request_method=None, request_url=None, auto_close=True)#
Bases:
BaseHTTPResponse
HTTP Response container.
Backwards-compatible with
http.client.HTTPResponse
but the responsebody
is loaded and decoded on-demand when thedata
property is accessed. This class is also compatible with the Python standard library’sio
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 (bool) – If True, the response’s body will be preloaded during construction.
decode_content (bool) – If True, will attempt to decode the body based on the ‘content-encoding’ header.
original_response (_HttplibHTTPResponse | None) – 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 (Retry | None) – The retries contains the last
Retry
that was used during the request.enforce_content_length (bool) – Enforce content length checking. Body returned by server must match value of Content-Length header, if present. Otherwise, raise error.
body (_TYPE_BODY) –
headers (Mapping[str, str] | Mapping[bytes, bytes] | None) –
status (int) –
version (int) –
reason (str | None) –
pool (HTTPConnectionPool | None) –
connection (HTTPConnection | None) –
msg (_HttplibHTTPMessage | None) –
request_method (str | None) –
request_url (str | None) –
auto_close (bool) –
- auto_close#
- status#
- headers#
- CONTENT_DECODERS = ['gzip', 'deflate', 'br', 'zstd']#
- DECODER_ERROR_CLASSES: tuple[type[Exception], ...] = (<class 'OSError'>, <class 'zlib.error'>, <class 'brotli.error'>, <class 'zstd.ZstdError'>)#
- 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.
- Return type:
None
- property connection: HTTPConnection | None#
- 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.
- Return type:
None
- fileno()#
Returns underlying file descriptor if one exists.
OSError is raised if the IO object does not use a file descriptor.
- Return type:
- flush()#
Flush write buffers, if applicable.
This is not implemented for read-only and non-blocking streams.
- Return type:
None
- 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.- Return type:
str | None | Literal[False]
- getheader(name, default=None)#
- getheaders()#
- Return type:
HTTPHeaderDict
- info()#
- Return type:
HTTPHeaderDict
- isatty()#
Return whether this is an ‘interactive’ stream.
Return False if it can’t be determined.
- json()#
Parses the body of the HTTP response as JSON.
To use a custom JSON decoder pass the result of
HTTPResponse.data
to the decoder.This method can raise either UnicodeDecodeError or json.JSONDecodeError.
Read more here.
- Return type:
- read(amt=None, decode_content=None, cache_content=False)#
Similar to
http.client.HTTPResponse.read()
, but with two additional parameters:decode_content
andcache_content
.- Parameters:
amt (int | None) – 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 (bool | None) – If True, will attempt to decode the body based on the ‘content-encoding’ header.
cache_content (bool) – 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 ifamt
is set.)
- Return type:
- read_chunked(amt=None, decode_content=None)#
Similar to
HTTPResponse.read()
, but with an additional parameter:decode_content
.- Parameters:
- Return type:
- readable()#
Return whether object was opened for reading.
If False, read() will raise OSError.
- Return type:
- readline(size=-1, /)#
Read and return a line from the stream.
If size is specified, at most size bytes will be read.
The line terminator is always b’n’ for binary files; for text files, the newlines argument to open can be used to select the line terminator(s) recognized.
- readlines(hint=-1, /)#
Return a list of lines from the stream.
hint can be specified to control the number of lines read: no more lines will be read if the total size (in bytes/characters) of all lines so far exceeds hint.
- release_conn()#
- Return type:
None
- seek()#
Change stream position.
Change the stream position to the given byte offset. The offset is interpreted relative to the position indicated by whence. Values for whence are:
0 – start of stream (the default); offset should be zero or positive
1 – current stream position; offset may be negative
2 – end of stream; offset is usually negative
Return the new absolute position.
- seekable()#
Return whether object supports random access.
If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().
- 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 (int | None) – 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 (bool | None) – If True, will attempt to decode the body based on the ‘content-encoding’ header.
- Return type:
- 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().- Return type:
- 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).- Return type:
- truncate()#
Truncate file to size bytes.
File pointer is left unchanged. Size defaults to the current IO position as reported by tell(). Returns the new size.
- property url: str | None#
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.
- writable()#
Return whether object was opened for writing.
If False, write() will raise OSError.
- writelines(lines, /)#
Write a list of lines to stream.
Line separators are not added, so it is usual for each of the lines provided to have a line separator at the end.
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.ZstdDecoder#
- 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.
- Parameters:
modes (str) –