API reference¶

Here is an example of autofunction, autoclass directives.

.. autofunction:: sphinx.versioning.merge_doctrees
    :noindex:

.. autoclass:: urllib3.util.Timeout
    :members:
    :noindex:

sphinx.versioning.merge_doctrees(old: Node, new: Node, condition: Any) → Iterator[Node][source]

Merge the old doctree with the new one while looking at nodes matching the condition.

Each node which replaces another one or has been added to the new doctree will be yielded.

Parameters:: condition – A callable which returns either True or False for a given node.

Timeout configuration.

Timeouts can be defined as a default for a pool:

import urllib3

timeout = urllib3.util.Timeout(connect=2.0, read=7.0)

http = urllib3.PoolManager(timeout=timeout)

resp = http.request("GET", "https://example.com/")

print(resp.status)

Or per-request (which overrides the default for the pool):

response = http.request("GET", "https://example.com/", timeout=Timeout(10))

Timeouts can be disabled by setting all the parameters to None:

no_timeout = Timeout(connect=None, read=None)
response = http.request("GET", "https://example.com/", timeout=no_timeout)

Parameters:

total (int, float, or None) –
This combines the connect and read timeouts into one; the read timeout will be set to the time leftover from the connect attempt. In the event that both a connect timeout and a total are specified, or a read timeout and a total are specified, the shorter timeout will be applied.

Defaults to None.
connect (int, float, or None) – The maximum amount of time (in seconds) to wait for a connection attempt to a server to succeed. Omitting the parameter will default the connect timeout to the system default, probably the global default timeout in socket.py. None will set an infinite timeout for connection attempts.
read (int, float, or None) –
The maximum amount of time (in seconds) to wait between consecutive read operations for a response from the server. Omitting the parameter will default the read timeout to the system default, probably the global default timeout in socket.py. None will set an infinite timeout.

Note

Many factors can affect the total amount of time for urllib3 to return an HTTP response.

For example, Python’s DNS resolver does not obey the timeout specified on the socket. Other factors that can affect total request time include high CPU load, high swap, the program running at a low priority level, or other behaviors.

In addition, the read and total timeouts only measure the time between read operations on the socket connecting the client and the server, not the total amount of time for the request to return a complete response. For most requests, the timeout is raised because the server has not sent the first byte in the specified time. This is not always the case; if a server streams one byte every fifteen seconds, a timeout of 20 seconds will not trigger, even though the request will take several minutes to complete.

Attributes:

connect_timeout: Get the value to use when setting a connection timeout.
read_timeout: Get the value for the read timeout.

Methods

`clone`()	Create a copy of the timeout object
`from_float`(timeout)	Create a new Timeout from a legacy timeout value.
`get_connect_duration`()	Gets the time elapsed since the call to `start_connect()`.
`start_connect`()	Start the timeout clock, used during a connect() attempt

resolve_default_timeout

DEFAULT_TIMEOUT: float | _TYPE_DEFAULT | None = -1: A sentinel object representing the default timeout value

clone() → Timeout[source]

Create a copy of the timeout object

Timeout properties are stored per-pool but each request needs a fresh Timeout object to ensure each one has its own start/stop configured.

Returns:: a copy of the timeout object
Return type:: Timeout

property connect_timeout: float | _TYPE_DEFAULT | None

Get the value to use when setting a connection timeout.

This will be a positive float or integer, the value None (never timeout), or the default system timeout.

Returns:: Connect timeout.
Return type:: int, float, Timeout.DEFAULT_TIMEOUT or None

classmethod from_float(timeout: float | _TYPE_DEFAULT | None) → Timeout[source]

Create a new Timeout from a legacy timeout value.

The timeout value used by httplib.py sets the same timeout on the connect(), and recv() socket requests. This creates a Timeout object that sets the individual timeouts to the timeout value passed to this function.

Parameters:: timeout (integer, float, urllib3.util.Timeout.DEFAULT_TIMEOUT, or None) – The legacy timeout value.
Returns:: Timeout object
Return type:: Timeout

get_connect_duration() → float[source]

Gets the time elapsed since the call to start_connect().

Returns:: Elapsed time in seconds.
Return type:: float
Raises:: urllib3.exceptions.TimeoutStateError – if you attempt to get duration for a timer that hasn’t been started.

property read_timeout: float | None

Get the value for the read timeout.

This assumes some time has elapsed in the connection timeout and computes the read timeout appropriately.

If self.total is set, the read timeout is dependent on the amount of time taken by the connect timeout. If the connection time has not been established, a TimeoutStateError will be raised.

Returns:: Value to use for the read timeout.
Return type:: int, float or None
Raises:: urllib3.exceptions.TimeoutStateError – If start_connect() has not yet been called on this object.

start_connect() → float[source]

Start the timeout clock, used during a connect() attempt

Raises:: urllib3.exceptions.TimeoutStateError – if you attempt to start a timer that has been started already.