From f540bd0bcf74cb092c32093ee866ab0c30809e02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20Hild=C3=A9n?= Date: Tue, 11 Aug 2020 12:08:53 +0300 Subject: [PATCH] Expand client docstrings (#1152) * 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 --- docs/api.md | 2 +- httpx/_client.py | 142 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 143 insertions(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index a34d366d56..94bbb81cdd 100644 --- a/docs/api.md +++ b/docs/api.md @@ -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` diff --git a/httpx/_client.py b/httpx/_client.py index 1211790757..55c544a4c6 100644 --- a/httpx/_client.py +++ b/httpx/_client.py @@ -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) @@ -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, @@ -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) @@ -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, @@ -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, @@ -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, @@ -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, @@ -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, @@ -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, @@ -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, @@ -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: @@ -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, @@ -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) @@ -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, @@ -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, @@ -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, @@ -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, @@ -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, @@ -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, @@ -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, @@ -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: