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 <tom@tomchristie.com>

diff --git a/docs/api.md b/docs/api.md
index a34d366d5615e005fe6a334961da2c46eb743537..94bbb81cdd6c3664e7e4192b27653ecb5633ec10 100644 (file)
--- 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 1211790757298b1a4c3f4113445bb850865b1239..55c544a4c6adb45e2806073ac035b7ff81bf34f7 100644 (file)
--- a/httpx/_client.py
+++ b/httpx/_client.py
@@ -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: