From: Florimond Manca <florimond.manca@gmail.com>
Date: Sat, 19 Oct 2019 13:05:26 +0000 (+0200)
Subject: Document client-level configuration (#488)
X-Git-Tag: 0.7.6~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ad38db82f970176770bb6959c74fbf31b65fa773;p=thirdparty%2Fhttpx.git

Document client-level configuration (#488)

* Document client-level configuration

* Fix typo
---

diff --git a/docs/advanced.md b/docs/advanced.md
index 327edbd1..8a69d7b2 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -36,6 +36,42 @@ Alternatively, you can explicitly close the connection pool without block-usage
 
 Once you have a `Client`, you can use all the features documented in the [Quickstart](/quickstart) guide.
 
+### Configuration
+
+Clients allow you to apply configuration to all outgoing requests by passing parameters to the `Client` constructor.
+
+For example, to apply a set of custom headers on every request:
+
+```python
+>>> url = 'http://httpbin.org/headers'
+>>> headers = {'user-agent': 'my-app/0.0.1'}
+>>> with httpx.Client(headers=headers) as client:
+...     r = client.get(url)
+...
+>>> r.json()['headers']['User-Agent']
+'my-app/0.0.1'
+```
+
+!!! note
+    When you provide a parameter at both the client and request levels, one of two things can happen:
+    
+    - For headers, query parameters and cookies, the values are merged into one.
+    - For all other parameters, the request-level value is used.
+
+Additionally, `Client` constructor accepts some parameters that aren't available at the request level.
+
+One particularly useful parameter is `base_url`, which allows you to define a base URL to prepend to all outgoing requests:
+
+```python
+>>> with httpx.Client(base_url='http://httpbin.org') as client:
+...     r = client.get('/headers')
+... 
+>>> r.request.url
+URL('http://httpbin.org/headers')
+```
+
+For a list of all available client-level parameters, see the [`Client` API reference](/api/#client).
+
 ## Calling into Python Web Apps
 
 You can configure an `httpx` client to call directly into a Python web