Response and Decoders

Response

class urllib3.response.BaseHTTPResponse(*, headers=None, status, version, version_string, reason, decode_content, request_url, retries=None)

基底類別：IOBase

參數:
CONTENT_DECODERS = ['gzip', 'x-gzip', 'deflate', 'br', 'zstd']
DECODER_ERROR_CLASSES: tuple[type[Exception], ...] = (<class 'OSError'>, <class 'zlib.error'>, <class 'brotli.error'>, <class 'backports.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.

回傳型別:

None

property connection: BaseHTTPConnection | None
property data: bytes
drain_conn()
回傳型別:

None

get_redirect_location()

Should we redirect and where to?

回傳:

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.

回傳型別:

str | None | Literal[False]

getheader(name, default=None)
參數:

  • name (str)

  • default (str | None)

回傳型別:

str | None

getheaders()
回傳型別:

HTTPHeaderDict

geturl()
回傳型別:

str | None

info()
回傳型別:

HTTPHeaderDict

json()

Deserializes the body of the HTTP response as a Python object.

The body of the HTTP response must be encoded using UTF-8, as per RFC 8529 Section 8.1.

To use a custom JSON decoder pass the result of HTTPResponse.data to your custom decoder instead.

If the body of the HTTP response is not decodable to UTF-8, a UnicodeDecodeError will be raised. If the body of the HTTP response is not a valid JSON document, a json.JSONDecodeError will be raised.

Read more here.

回傳:

The body of the HTTP response as a Python object.

回傳型別:

Any

read(amt=None, decode_content=None, cache_content=False)
參數:

  • amt (int | None)

  • decode_content (bool | None)

  • cache_content (bool)

回傳型別:

bytes

read1(amt=None, decode_content=None)
參數:

  • amt (int | None)

  • decode_content (bool | None)

回傳型別:

bytes

read_chunked(amt=None, decode_content=None)
參數:

  • amt (int | None)

  • decode_content (bool | None)

回傳型別:

Iterator[bytes]

readinto(b)
參數:

b (bytearray | memoryview[int])

回傳型別:

int

release_conn()
回傳型別:

None

property retries: Retry | None
shutdown()
回傳型別:

None

stream(amt=65536, decode_content=None)
參數:

  • amt (int | None)

  • decode_content (bool | None)

回傳型別:

Iterator[bytes]

property url: str | None
class urllib3.response.HTTPResponse(body='', headers=None, status=0, version=0, version_string='HTTP/?', 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, sock_shutdown=None)

基底類別：BaseHTTPResponse

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:

參數:

  • preload_content (bool) -- If True, the response's body will be preloaded during construction.

  • decode_content (bool) -- 若為 True，將嘗試根據「content-encoding」標頭對正文進行解碼。

  • 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)

  • version_string (str)

  • reason (str | None)

  • pool (HTTPConnectionPool | None)

  • connection (HTTPConnection | None)

  • msg (_HttplibHTTPMessage | None)

  • request_method (str | None)

  • request_url (str | None)

  • auto_close (bool)

  • sock_shutdown (Callable[[int], None] | None)

auto_close
status
headers
CONTENT_DECODERS = ['gzip', 'x-gzip', 'deflate', 'br', 'zstd']
DECODER_ERROR_CLASSES: tuple[type[Exception], ...] = (<class 'OSError'>, <class 'zlib.error'>, <class 'brotli.error'>, <class 'backports.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.

回傳型別:

None

property closed: bool
property connection: HTTPConnection | None
property data: bytes
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.

回傳型別:

None

fileno()

Return underlying file descriptor if one exists.

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

回傳型別:

int

flush()

Flush write buffers, if applicable.

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

回傳型別:

None

get_redirect_location()

Should we redirect and where to?

回傳:

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.

回傳型別:

str | None | Literal[False]

getheader(name, default=None)
參數:

  • name (str)

  • default (str | None)

回傳型別:

str | None

getheaders()
回傳型別:

HTTPHeaderDict

geturl()
回傳型別:

str | None

info()
回傳型別:

HTTPHeaderDict

isatty()

Return whether this is an 'interactive' stream.

Return False if it can't be determined.

isclosed()
回傳型別:

bool

json()

Deserializes the body of the HTTP response as a Python object.

The body of the HTTP response must be encoded using UTF-8, as per RFC 8529 Section 8.1.

To use a custom JSON decoder pass the result of HTTPResponse.data to your custom decoder instead.

If the body of the HTTP response is not decodable to UTF-8, a UnicodeDecodeError will be raised. If the body of the HTTP response is not a valid JSON document, a json.JSONDecodeError will be raised.

Read more here.

回傳:

The body of the HTTP response as a Python object.

回傳型別:

Any

length_remaining: int | None
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.

參數:

  • 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) -- 若為 True，將嘗試根據「content-encoding」標頭對正文進行解碼。

  • 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 if amt is set.)

回傳型別:

bytes

read1(amt=None, decode_content=None)

Similar to http.client.HTTPResponse.read1 and documented in io.BufferedReader.read1(), but with an additional parameter: decode_content.

參數:

  • amt (int | None) -- How much of the content to read.

  • decode_content (bool | None) -- 若為 True，將嘗試根據「content-encoding」標頭對正文進行解碼。

回傳型別:

bytes

read_chunked(amt=None, decode_content=None)

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

參數:

  • 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) -- 若為 True，將嘗試根據「content-encoding」標頭對正文進行解碼。

回傳型別:

Generator[bytes, None, None]

readable()

Return whether object was opened for reading.

If False, read() will raise OSError.

回傳型別:

bool

readinto(b)
參數:

b (bytearray | memoryview[int])

回傳型別:

int

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()
回傳型別:

None

property retries: Retry | None
seek(offset, whence=0, /)

Change the stream position to the given byte offset.

offset

The stream position, relative to 'whence'.

whence

The relative position to seek from.

The offset is interpreted relative to the position indicated by whence. Values for whence are:

  • os.SEEK_SET or 0 -- start of stream (the default); offset should be zero or positive

  • os.SEEK_CUR or 1 -- current stream position; offset may be negative

  • os.SEEK_END or 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().

shutdown()
回傳型別:

None

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.

參數:

  • 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) -- 若為 True，將嘗試根據「content-encoding」標頭對正文進行解碼。

回傳型別:

Generator[bytes, None, None]

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().

回傳型別:

bool

tell()

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

回傳型別:

int

truncate(size=None, /)

Truncate file to size bytes.

File pointer is left unchanged. Size defaults to the current IO position as reported by tell(). Return 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.

參數:

modes (str)