Merge pull request #6600 from MestreLion/MestreLion-connection-timeou…

…t-note

Add note on connection timeout being larger than specified. Fix #5773

docs/user/advanced.rst

@@ -1122,4 +1122,18 @@ 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.
+.. 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