Merge pull request #6600 from MestreLion/MestreLion-connection-timeout-note

Add note on connection timeout being larger than specified. Fix #5773
diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst
index c90a13d..5e5e36f 100644
--- a/docs/user/advanced.rst
+++ b/docs/user/advanced.rst
@@ -1122,4 +1122,18 @@
     r = requests.get('', 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`:
 .. _`connect()`: