Add timeout fine-tunning advanced docs section (#476)

* Add timeout fine-tunning advanced docs section

* Rephrase part of timeout documentation

diff --git a/docs/advanced.md b/docs/advanced.md
index 368682fec73eb18b712c63a55e20e29451d75b8f..973ffed4862db5a09b7687a03cfd16fedf3aac5d 100644 (file)
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -167,3 +167,76 @@ client = httpx.Client(proxies=proxy)
 # This request will be tunneled instead of forwarded.
 client.get("http://example.com")
 ```
+
+
+## Timeout fine-tuning
+HTTPX offers various request timeout management options. Three types of timeouts are available: **connect** timeouts, 
+**write** timeouts and **read** timeouts.
+
+* The **connect timeout** specifies the maximum amount of time to wait until a connection to the requested host is established.   
+If HTTPX is unable to connect within this time frame, a `ConnectTimeout` exception is raised.
+* The **write timeout** specifies the maximum duration to wait for a chunk of data to be sent (for example, a chunk of the request body).   
+If HTTPX is unable to send data within this time frame, a `WriteTimeout` exception is raised.
+* The **read timeout** specifies the maximum duration to wait for a chunk of data to be received (for example, a chunk of the response body).  
+If HTTPX is unable to receive data within this time frame, a `ReadTimeout` exception is raised.
+
+### Setting timeouts
+You can set timeouts on two levels:
+
+- For a given request:
+
+```python
+# Using top-level API
+httpx.get('http://example.com/api/v1/example', timeout=5)
+
+# Or, with a client:
+client = httpx.Client()
+client.get("http://example.com/api/v1/example", timeout=5)
+```
+
+- On a client instance, which results in the given `timeout` being used as a default for requests made with this client:
+
+```python
+client = httpx.Client(timeout=5)
+client.get('http://example.com/api/v1/example')
+```
+
+Besides, you can pass timeouts in two forms:
+
+- A number, which sets the read, write and connect timeouts to the same value, as in the examples above.  
+- A `TimeoutConfig` instance, which allows to define the read, write and connect timeouts independently:
+
+```python
+timeout = httpx.TimeoutConfig(
+    connect_timeout=5, 
+    read_timeout=10, 
+    write_timeout=15
+)
+
+resp = httpx.get('http://example.com/api/v1/example', timeout=timeout)
+```
+
+### Default timeouts
+By default all types of timeouts are set to 5 second.
+ 
+### Disabling timeouts
+To disable timeouts, you can pass `None` as a timeout parameter.  
+Note that currently this is not supported by the top-level API.
+
+```python
+url = "http://example.com/api/v1/delay/10"
+
+httpx.get(url, timeout=None)  # Times out after 5s
+
+
+client = httpx.Client(timeout=None)
+client.get(url)  # Does not timeout, returns after 10s
+
+
+timeout = httpx.TimeoutConfig(
+    connect_timeout=5, 
+    read_timeout=None, 
+    write_timeout=5
+)
+httpx.get(url, timeout=timeout) # Does not timeout, returns after 10s
+```
\ No newline at end of file

diff --git a/docs/quickstart.md b/docs/quickstart.md
index e7ac5fa8417874f47845341c2924cc4cbd2bae8c..9e72cdcb43c9a8854989d98f78deb5929d48b3d1 100644 (file)
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -380,6 +380,8 @@ value to be more or less strict:
 >>> httpx.get('https://github.com/', timeout=0.001)
 ```
 
+For advanced timeout management, see [Timeout fine-tuning](https://www.encode.io/httpx/advanced/#timeout-fine-tuning).
+
 ## Authentication
 
 HTTPX supports Basic and Digest HTTP authentication.