encode/httpx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Expand client docstrings (#1152)

Browse Source 
* Add AsyncClient.aclose to API documentation

* Expand client docstrings
* Add docstrings for all verbs and close methods
* Include parameter merge information and see also

* Update _client.py

Co-authored-by: Tom Christie <tom@tomchristie.com>
This commit is contained in:
Felix Hildén 2020-08-11 12:08:53 +03:00 committed by GitHub
parent 45de714592
commit f540bd0bcf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 143 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/api.md
View File

@ -42,7 +42,7 @@
::: httpx.AsyncClient
:docstring:
:members: headers cookies params request get head options post put patch delete build_request send
:members: headers cookies params request get head options post put patch delete build_request send aclose
## `Response`

142
httpx/_client.py
View File

@ -208,6 +208,14 @@ class BaseClient:
) -> Request:
"""
Build and return a request instance.
* The `params`, `headers` and `cookies` arguments
are merged with any values set on the client.
* The `url` argument is merged with any `base_url` set on the client.
See also: [Request instances][0]
[0]: /advanced/#request-instances
"""
url = self._merge_url(url)
headers = self._merge_headers(headers)
@ -603,6 +611,22 @@ class Client(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Build and send a request.
Equivalent to:
```python
request = client.build_request(...)
response = client.send(request, ...)
```
See `Client.build_request()`, `Client.send()` and
[Merging of configuration][0] for how the various parameters
are merged with client-level configuration.
[0]: /advanced/#merging-of-configuration
"""
request = self.build_request(
method=method,
url=url,
@ -626,6 +650,19 @@ class Client(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a request.
The request is sent as-is, unmodified.
Typically you'll want to build one with `Client.build_request()`
so that any client-level configuration is merged into the request,
but passing an explicit `httpx.Request()` is supported as well.
See also: [Request instances][0]
[0]: /advanced/#request-instances
"""
timeout = self.timeout if isinstance(timeout, UnsetType) else Timeout(timeout)
auth = self._build_auth(request, auth)
@ -759,6 +796,11 @@ class Client(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `GET` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"GET",
url,
@ -781,6 +823,11 @@ class Client(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send an `OPTIONS` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"OPTIONS",
url,
@ -803,6 +850,11 @@ class Client(BaseClient):
allow_redirects: bool = False, # NOTE: Differs to usual default.
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `HEAD` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"HEAD",
url,
@ -828,6 +880,11 @@ class Client(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `POST` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"POST",
url,
@ -856,6 +913,11 @@ class Client(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `PUT` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"PUT",
url,
@ -884,6 +946,11 @@ class Client(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `PATCH` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"PATCH",
url,
@ -909,6 +976,11 @@ class Client(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `DELETE` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"DELETE",
url,
@ -921,6 +993,9 @@ class Client(BaseClient):
)
def close(self) -> None:
"""
Close transport and proxies.
"""
self._transport.close()
for proxy in self._proxies.values():
if proxy is not None:
@ -1137,6 +1212,22 @@ class AsyncClient(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Build and send a request.
Equivalent to:
```python
request = client.build_request(...)
response = client.send(request, ...)
```
See `AsyncClient.build_request()`, `AsyncClient.send()`
and [Merging of configuration][0] for how the various parameters
are merged with client-level configuration.
[0]: /advanced/#merging-of-configuration
"""
request = self.build_request(
method=method,
url=url,
@ -1161,6 +1252,19 @@ class AsyncClient(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a request.
The request is sent as-is, unmodified.
Typically you'll want to build one with `AsyncClient.build_request()`
so that any client-level configuration is merged into the request,
but passing an explicit `httpx.Request()` is supported as well.
See also: [Request instances][0]
[0]: /advanced/#request-instances
"""
timeout = self.timeout if isinstance(timeout, UnsetType) else Timeout(timeout)
auth = self._build_auth(request, auth)
@ -1296,6 +1400,11 @@ class AsyncClient(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `GET` request.
**Parameters**: See `httpx.request`.
"""
return await self.request(
"GET",
url,
@ -1318,6 +1427,11 @@ class AsyncClient(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send an `OPTIONS` request.
**Parameters**: See `httpx.request`.
"""
return await self.request(
"OPTIONS",
url,
@ -1340,6 +1454,11 @@ class AsyncClient(BaseClient):
allow_redirects: bool = False, # NOTE: Differs to usual default.
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `HEAD` request.
**Parameters**: See `httpx.request`.
"""
return await self.request(
"HEAD",
url,
@ -1365,6 +1484,11 @@ class AsyncClient(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `POST` request.
**Parameters**: See `httpx.request`.
"""
return await self.request(
"POST",
url,
@ -1393,6 +1517,11 @@ class AsyncClient(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `PUT` request.
**Parameters**: See `httpx.request`.
"""
return await self.request(
"PUT",
url,
@ -1421,6 +1550,11 @@ class AsyncClient(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `PATCH` request.
**Parameters**: See `httpx.request`.
"""
return await self.request(
"PATCH",
url,
@ -1446,6 +1580,11 @@ class AsyncClient(BaseClient):
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `DELETE` request.
**Parameters**: See `httpx.request`.
"""
return await self.request(
"DELETE",
url,
@ -1458,6 +1597,9 @@ class AsyncClient(BaseClient):
)
async def aclose(self) -> None:
"""
Close transport and proxies.
"""
await self._transport.aclose()
for proxy in self._proxies.values():
if proxy is not None: