From a64f32ba453bc19aa679018838bee8ef8cc9a68b Mon Sep 17 00:00:00 2001 From: Rodrigo Silva Date: Wed, 13 Dec 2023 10:05:12 -0300 Subject: [PATCH 1/3] Add note on connection timeout being larger than specified. Fix #5773 On servers with multiple IPs, such as IPv4 and IPv6, `urllib3` tries each address sequentially until one successfully connects, using the specified timeout for _each_ attempt, leading to a total connection timeout that is a _multiple_ of the requested time. --- docs/user/advanced.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index c90a13dc6d..129cf4d0d6 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -1122,4 +1122,12 @@ coffee. r = requests.get('https://github.com', timeout=None) +.. note:: The connect timeout applies to each connection attempt to an IP address. +If multiple addresses exist for a domain name, the underlying ``urllib3`` will +try each address sequentially until one successfully connects. +This may lead to an effective total connection timeout *multiple* times longer +than the specified time, e.g. an unresponsive server having both IPv4 and IPv6 +addresses will have its perceived timeout *doubled*, so take that into account +when setting the connection timeout. + .. _`connect()`: https://linux.die.net/man/2/connect From 951dd15fa619b23aba6b72532f1aac30b69389b7 Mon Sep 17 00:00:00 2001 From: Ian Stapleton Cordasco Date: Sat, 16 Dec 2023 07:26:23 -0600 Subject: [PATCH 2/3] Update docs/user/advanced.rst fix indentation for note so it renders properly --- docs/user/advanced.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 129cf4d0d6..3f5243ee24 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -1123,11 +1123,11 @@ coffee. r = requests.get('https://github.com', timeout=None) .. note:: The connect timeout applies to each connection attempt to an IP address. -If multiple addresses exist for a domain name, the underlying ``urllib3`` will -try each address sequentially until one successfully connects. -This may lead to an effective total connection timeout *multiple* times longer -than the specified time, e.g. an unresponsive server having both IPv4 and IPv6 -addresses will have its perceived timeout *doubled*, so take that into account -when setting the connection timeout. + If multiple addresses exist for a domain name, the underlying ``urllib3`` will + try each address sequentially until one successfully connects. + This may lead to an effective total connection timeout *multiple* times longer + than the specified time, e.g. an unresponsive server having both IPv4 and IPv6 + addresses will have its perceived timeout *doubled*, so take that into account + when setting the connection timeout. .. _`connect()`: https://linux.die.net/man/2/connect From 92f9e431c99d5e0776a00c10a90dfdf11cd45ba0 Mon Sep 17 00:00:00 2001 From: Ian Stapleton Cordasco Date: Sat, 16 Dec 2023 07:29:50 -0600 Subject: [PATCH 3/3] Update docs/user/advanced.rst Add note about wall clock too --- docs/user/advanced.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 3f5243ee24..5e5e36f302 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -1129,5 +1129,11 @@ coffee. than the specified time, e.g. an unresponsive server having both IPv4 and IPv6 addresses will have its perceived timeout *doubled*, so take that into account when setting the connection timeout. +.. note:: Neither the connect nor read timeouts are `wall clock`_. This means + that if you start a request, and look at the time, and then look at + the time when the request finishes or times out, the real-world time + may be greater than what you specified. + +.. _`wall clock`: https://wiki.php.net/rfc/max_execution_wall_time .. _`connect()`: https://linux.die.net/man/2/connect