gh-102810: Add docstrings to the public-facing methods of `asyncio.Timeout` (GH-102811)

(cherry picked from commit 699cb20ae6fdef8b0f13d633cf4858465ef3469f)

Co-authored-by: JosephSBoyle <48555120+JosephSBoyle@users.noreply.github.com>
Co-authored-by: Guido van Rossum <gvanrossum@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

diff --git a/Lib/asyncio/timeouts.py b/Lib/asyncio/timeouts.py
index 94d25535fbc0595760877415166bfc8edd6ba1a8..d07b291005e8f92b39fd8ec811d5616826dc2d45 100644 (file)
--- a/Lib/asyncio/timeouts.py
+++ b/Lib/asyncio/timeouts.py
@@ -25,8 +25,18 @@ class _State(enum.Enum):
 
 @final
 class Timeout:
+    """Asynchronous context manager for cancelling overdue coroutines.
+
+    Use `timeout()` or `timeout_at()` rather than instantiating this class directly.
+    """
 
     def __init__(self, when: Optional[float]) -> None:
+        """Schedule a timeout that will trigger at a given loop time.
+
+        - If `when` is `None`, the timeout will never trigger.
+        - If `when < loop.time()`, the timeout will trigger on the next
+          iteration of the event loop.
+        """
         self._state = _State.CREATED
 
         self._timeout_handler: Optional[events.TimerHandle] = None
@@ -34,9 +44,11 @@ class Timeout:
         self._when = when
 
     def when(self) -> Optional[float]:
+        """Return the current deadline."""
         return self._when
 
     def reschedule(self, when: Optional[float]) -> None:
+        """Reschedule the timeout."""
         assert self._state is not _State.CREATED
         if self._state is not _State.ENTERED:
             raise RuntimeError(