Skip to content

Commit

Permalink
Expand client docstrings (#1152)
Browse files Browse the repository at this point in the history 
* 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>
  • Loading branch information
@felix-hilden @tomchristie
felix-hilden and tomchristie authored Aug 11, 2020
1 parent 45de714 commit f540bd0
Show file tree
Hide file tree
Showing 2 changed files with 143 additions and 1 deletion.
2 changes: 1 addition & 1 deletion docs/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
142 changes: 142 additions & 0 deletions httpx/_client.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,14 @@ def build_request(
) -> 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)
Expand Down Expand Up @@ -603,6 +611,22 @@ def request(
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,
Expand All @@ -626,6 +650,19 @@ def send(
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)
Expand Down Expand Up @@ -759,6 +796,11 @@ def get(
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `GET` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"GET",
url,
Expand All @@ -781,6 +823,11 @@ def options(
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send an `OPTIONS` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"OPTIONS",
url,
Expand All @@ -803,6 +850,11 @@ def head(
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,
Expand All @@ -828,6 +880,11 @@ def post(
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `POST` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"POST",
url,
Expand Down Expand Up @@ -856,6 +913,11 @@ def put(
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `PUT` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"PUT",
url,
Expand Down Expand Up @@ -884,6 +946,11 @@ def patch(
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `PATCH` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"PATCH",
url,
Expand All @@ -909,6 +976,11 @@ def delete(
allow_redirects: bool = True,
timeout: typing.Union[TimeoutTypes, UnsetType] = UNSET,
) -> Response:
"""
Send a `DELETE` request.
**Parameters**: See `httpx.request`.
"""
return self.request(
"DELETE",
url,
Expand All @@ -921,6 +993,9 @@ def delete(
)

def close(self) -> None:
"""
Close transport and proxies.
"""
self._transport.close()
for proxy in self._proxies.values():
if proxy is not None:
Expand Down Expand Up @@ -1137,6 +1212,22 @@ async def request(
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,
Expand All @@ -1161,6 +1252,19 @@ async def send(
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)
Expand Down Expand Up @@ -1296,6 +1400,11 @@ async def get(
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,
Expand All @@ -1318,6 +1427,11 @@ async def options(
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,
Expand All @@ -1340,6 +1454,11 @@ async def head(
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,
Expand All @@ -1365,6 +1484,11 @@ async def post(
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,
Expand Down Expand Up @@ -1393,6 +1517,11 @@ async def put(
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,
Expand Down Expand Up @@ -1421,6 +1550,11 @@ async def patch(
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,
Expand All @@ -1446,6 +1580,11 @@ async def delete(
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,
Expand All @@ -1458,6 +1597,9 @@ async def delete(
)

async def aclose(self) -> None:
"""
Close transport and proxies.
"""
await self._transport.aclose()
for proxy in self._proxies.values():
if proxy is not None:
Expand Down

0 comments on commit f540bd0

Please sign in to comment.