Add timeout support with improved documentation (#983)

Author: achimnol

CHANGES/983.feature

@@ -0,0 +1 @@
+Introduce the client-level ``timeout`` configuration which becomes the base timeout configuration while still allowing legacy individual per-API timeouts and merging it into the base timeout.  Now setting individual float (total) timeout per-API call is HIGHLY DISCOURAGED in favor of composable timeouts via stdlib's `asyncio.timeout()` async context manager.

CONTRIBUTORS.txt

@@ -15,6 +15,7 @@ Gyubong Lee
 Hiroki Kiyohara
 Igor Alexandrov
 Jason Kraus
+Jonathan Carroll Otsuka
 Joongi Kim
 Joshua Chung
 Julien Kmec
@@ -26,6 +27,7 @@ Nikolay Novik
 Paul Tagliamonte
 Robin Tweedie
 Sanghun Lee
+Saulius Adamonis
 Tianon Gravi
 Tommy Beadle
 Travis DePrato

aiodocker/containers.py

@@ -30,7 +30,7 @@
 from .multiplexed import multiplexed_result_list, multiplexed_result_stream
 from .stream import Stream
 from .types import JSONObject, MutableJSONObject, PortInfo
-from .utils import identical, parse_result
+from .utils import _suppress_timeout_deprecation, identical, parse_result
 
 
 if TYPE_CHECKING:
@@ -286,14 +286,20 @@ async def kill(self, **kwargs) -> None:
         ):
             pass
 
-    async def wait(self, *, timeout=None, **kwargs) -> Dict[str, Any]:
-        data = await self.docker._query_json(
-            f"containers/{self._id}/wait",
-            method="POST",
-            params=kwargs,
-            timeout=timeout,
-        )
-        return data
+    async def wait(self, *, timeout: float | None = None, **kwargs) -> Dict[str, Any]:
+        # The wait API is an exception from deprecation of the total timeout.
+        # Use a context variable to suppress the warning in a thread-safe and async-safe manner.
+        token = _suppress_timeout_deprecation.set(True)
+        try:
+            data = await self.docker._query_json(
+                f"containers/{self._id}/wait",
+                method="POST",
+                params=kwargs,
+                timeout=timeout,
+            )
+            return data
+        finally:
+            _suppress_timeout_deprecation.reset(token)
 
     async def delete(self, **kwargs) -> None:
         async with self.docker._query(