clean up return type of fail_at/_after for sphinx

python-trio · Zac-HD · Sep 23, 2024 · May 22, 2024 · Jun 6, 2024 · Jun 6, 2024
commit 5a32eb0ca3c329a534df3c0d45a113377fdbf0ac
diff --git a/docs/source/reference-core.rst b/docs/source/reference-core.rst
@@ -598,41 +598,6 @@ which is sometimes useful:
 
 .. autofunction:: current_effective_deadline
 
-
-.. _saved_relative_timeouts:
-
-Separating initialization and entry of a :class:`CancelScope`
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-Before v0.26.3 there was no separation of initialization and entry of a :class:`CancelScope`. This meant that trying to initialize :func:`move_on_after` or :func:`fail_after` and entering them at a later point meant that the timeout was relative to initialization, leading to confusing behaviour.
-
-.. code-block:: python
-
-   # THIS WILL NOW GIVE A DEPRECATION ERROR
-   my_cs = trio.move_on_after(5)
-   trio.sleep(1)
-   with my_cs: # this would move on after 4 seconds
-       ...
-
-This is now resolved with the addition of a wrapper class :class:`trio._timeouts._RelativeCancelScope` that is transparent to end users when initializing and entering at the same time. To silence the :class:`DeprecationWarning` and use the new behavior, pass ``timeout_from_enter=True`` to :func:`move_on_after` or :func:`fail_after`.
-
-.. code-block:: python
-
-   my_cs = trio.move_on_after(5, timeout_from_enter = True)
-   trio.sleep(1)
-   with my_cs: # this will now move on after 5 seconds
-       ...
-
-If you want to retain previous behaviour, you should now instead write something like
-
-.. code-block:: python
-
-   my_cs = trio.move_on_at(trio.current_time() + 5)
-   trio.sleep(1)
-   with my_cs: # this will now unambiguously move on after 4 seconds
-       ...
-
-.. autoclass:: trio._timeouts._RelativeCancelScope
-
 .. _tasks:
 
 Tasks let you do multiple things at once

diff --git a/src/trio/_timeouts.py b/src/trio/_timeouts.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import math
+import sys
 from contextlib import contextmanager
 from typing import TYPE_CHECKING
 
@@ -32,7 +33,6 @@ def move_on_after(
     seconds: float,
     *,
     shield: bool = False,
-    timeout_from_enter: bool = False,
 ) -> trio.CancelScope:
     """Use as a context manager to create a cancel scope whose deadline is
     set to now + *seconds*.
@@ -180,3 +180,13 @@ def fail_after(
         yield scope
     if scope.cancelled_caught:
         raise TooSlowError
+
+
+# Users don't need to know that fail_at & fail_after wraps move_on_at and move_on_after
+# and there is no functional difference. So we replace the return value when generating
+# documentation.
+if "sphinx" in sys.modules:
+    import inspect
+
+    for c in (fail_at, fail_after):
+        c.__signature__ = inspect.Signature.from_callable(c).replace(return_annotation=trio.CancelScope)  # type: ignore[union-attr]