Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document client block-usage and close() #487

Merged
merged 2 commits into from
Oct 19, 2019
Merged

Document client block-usage and close() #487

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f5239f7
Document client context manager vs close() usage
florimondmanca Oct 19, 2019
b9950a0
Convert client snippets to use context-managed syntax
florimondmanca Oct 19, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 67 additions & 37 deletions docs/advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,36 @@ Using a Client instance to make requests will give you HTTP connection pooling,
will provide cookie persistence, and allows you to apply configuration across
all outgoing requests.

A Client instance is equivalent to a Session instance in `requests`.
!!! hint
A Client instance is equivalent to a Session instance in `requests`.
yeraydiazdiaz marked this conversation as resolved.
Show resolved Hide resolved

### Usage

The recommended way to use a `Client` is as a context manager. This will ensure that connections are properly cleaned up when leaving the `with` block:

```python
>>> with httpx.Client() as client:
... r = client.get('https://example.com')
...
>>> r
<Response [200 OK]>
```

Alternatively, you can explicitly close the connection pool without block-usage using `.close()`:

```python
>>> client = httpx.Client()
>>> r = client.get('https://example.org/')
>>> try:
... r = client.get('https://example.com')
... finally:
... client.close()
...
>>> r
<Response [200 OK]>
```

Once you have a `Client`, you can use all the features documented in the [Quickstart](/quickstart) guide.

## Calling into Python Web Apps

You can configure an `httpx` client to call directly into a Python web
Expand All @@ -38,10 +59,10 @@ app = Flask(__name__)
def hello():
return "Hello World!"

client = httpx.Client(app=app)
r = client.get('http://example/')
assert r.status_code == 200
assert r.text == "Hello World!"
with httpx.Client(app=app) as client:
r = client.get('http://example/')
assert r.status_code == 200
assert r.text == "Hello World!"
```

For some more complex cases you might need to customize the WSGI or ASGI
Expand All @@ -56,7 +77,8 @@ For example:
```python
# Instantiate a client that makes WSGI requests with a client IP of "1.2.3.4".
dispatch = httpx.dispatch.WSGIDispatch(app=app, remote_addr="1.2.3.4")
client = httpx.Client(dispatch=dispatch)
with httpx.Client(dispatch=dispatch) as client:
...
```

## Build Request
Expand All @@ -65,10 +87,12 @@ You can use `Client.build_request()` to build a request and
make modifications before sending the request.

```python
>>> client = httpx.Client()
>>> req = client.build_request("OPTIONS", "https://example.com")
>>> req.url.full_path = "*" # Build an 'OPTIONS *' request for CORS
>>> client.send(r)
>>> with httpx.Client() as client:
... req = client.build_request("OPTIONS", "https://example.com")
... req.url.full_path = "*" # Build an 'OPTIONS *' request for CORS
... r = client.send(req)
...
>>> r
<Response [200 OK]>
```

Expand All @@ -79,11 +103,11 @@ One can set the version of the HTTP protocol for the client in case you want to
For example:

```python
h11_client = httpx.Client(http_versions=["HTTP/1.1"])
h11_response = h11_client.get("https://myserver.com")
with httpx.Client(http_versions=["HTTP/1.1"]) as h11_client:
h11_response = h11_client.get("https://myserver.com")

h2_client = httpx.Client(http_versions=["HTTP/2"])
h2_response = h2_client.get("https://myserver.com")
with httpx.Client(http_versions=["HTTP/2"]) as h2_client:
h2_response = h2_client.get("https://myserver.com")
```

## .netrc Support
Expand Down Expand Up @@ -126,24 +150,31 @@ For example to forward all HTTP traffic to `http://127.0.0.1:3080` and all HTTPS
to `http://127.0.0.1:3081` your `proxies` config would look like this:

```python
>>> client = httpx.Client(proxies={
"http": "http://127.0.0.1:3080",
"https": "http://127.0.0.1:3081"
})
>>> proxies = {
... "http": "http://127.0.0.1:3080",
... "https": "http://127.0.0.1:3081"
... }
>>> with httpx.Client(proxies=proxies) as client:
... ...
```

Proxies can be configured for a specific scheme and host, all schemes of a host,
all hosts for a scheme, or for all requests. When determining which proxy configuration
to use for a given request this same order is used.

```python
>>> client = httpx.Client(proxies={
"http://example.com": "...", # Host+Scheme
"all://example.com": "...", # Host
"http": "...", # Scheme
"all": "...", # All
})
>>> client = httpx.Client(proxies="...") # Shortcut for 'all'
>>> proxies = {
... "http://example.com": "...", # Host+Scheme
... "all://example.com": "...", # Host
... "http": "...", # Scheme
... "all": "...", # All
... }
>>> with httpx.Client(proxies=proxies) as client:
... ...
...
>>> proxy = "..." # Shortcut for {'all': '...'}
>>> with httpx.Client(proxies=proxy) as client:
... ...
```

!!! warning
Expand All @@ -162,10 +193,9 @@ proxy = httpx.HTTPProxy(
proxy_url="https://127.0.0.1",
proxy_mode=httpx.HTTPProxyMode.TUNNEL_ONLY
)
client = httpx.Client(proxies=proxy)

# This request will be tunneled instead of forwarded.
client.get("http://example.com")
with httpx.Client(proxies=proxy) as client:
# This request will be tunneled instead of forwarded.
r = client.get("http://example.com")
```


Expand All @@ -190,15 +220,15 @@ You can set timeouts on two levels:
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)
with httpx.Client() as 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')
with httpx.Client(timeout=5) as client:
client.get('http://example.com/api/v1/example')
```

Besides, you can pass timeouts in two forms:
Expand Down Expand Up @@ -229,8 +259,8 @@ 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
with httpx.Client(timeout=None) as client:
client.get(url) # Does not timeout, returns after 10s


timeout = httpx.TimeoutConfig(
Expand All @@ -239,4 +269,4 @@ timeout = httpx.TimeoutConfig(
write_timeout=5
)
httpx.get(url, timeout=timeout) # Does not timeout, returns after 10s
```
```
4 changes: 2 additions & 2 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@
*An HTTP client, with connection pooling, HTTP/2, redirects, cookie persistence, etc.*

```python
>>> client = httpx.Client()
>>> response = client.get('https://example.org')
>>> with httpx.Client() as client:
... response = client.get('https://example.org')
```

* `def __init__([auth], [params], [headers], [cookies], [verify], [cert], [timeout], [pool_limits], [max_redirects], [app], [dispatch])`
Expand Down
3 changes: 2 additions & 1 deletion docs/compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ session = requests.Session(**kwargs)
is equivalent to

```python
client = httpx.Client(**kwargs)
with httpx.Client(**kwargs) as client:
...
```

More detailed documentation and usage of `Client` can be found in [Advanced Usage](advanced.md).
12 changes: 6 additions & 6 deletions docs/environment_variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,10 @@ Example:

```python
# test_script.py

import httpx
client = httpx.Client()
client.get("https://google.com")

with httpx.Client() as client:
r = client.get("https://google.com")
```

```console
Expand Down Expand Up @@ -64,10 +64,10 @@ Example:

```python
# test_script.py

import httpx
client = httpx.Client()
client.get("https://google.com")

with httpx.Client() as client:
r = client.get("https://google.com")
```

```console
Expand Down
18 changes: 9 additions & 9 deletions docs/parallel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,9 @@ control the authentication or dispatch behavior for all requests within the
block.

```python
>>> client = httpx.Client()
>>> with client.parallel() as parallel:
>>> ...
>>> with httpx.Client() as client:
... with client.parallel() as parallel:
... ...
```

## Async parallel requests
Expand All @@ -59,12 +59,12 @@ If you're working within an async framework, then you'll want to use a fully
async API for making requests.

```python
>>> client = httpx.AsyncClient()
>>> async with client.parallel() as parallel:
>>> pending_one = await parallel.get('https://example.com/1')
>>> pending_two = await parallel.get('https://example.com/2')
>>> response_one = await pending_one.get_response()
>>> response_two = await pending_two.get_response()
>>> async with httpx.AsyncClient() as client:
... async with client.parallel() as parallel:
... pending_one = await parallel.get('https://example.com/1')
... pending_two = await parallel.get('https://example.com/2')
... response_one = await pending_one.get_response()
... response_two = await pending_two.get_response()
```

See [the Async Client documentation](async.md) for more details.