bpo-42413: Replace `concurrent.futures.TimeoutError` and `asyncio.TimeoutError` with builtin `TimeoutError` (GH-30197)

Co-authored-by: Andrew Svetlov <andrew.svetlov@gmail.com>

Doc/library/asyncio-api-index.rst

@@ -203,11 +203,6 @@ Exceptions
     :class: full-width-table
 
 
-    * - :exc:`asyncio.TimeoutError`
-      - Raised on timeout by functions like :func:`wait_for`.
-        Keep in mind that ``asyncio.TimeoutError`` is **unrelated**
-        to the built-in :exc:`TimeoutError` exception.
-
     * - :exc:`asyncio.CancelledError`
       - Raised when a Task is cancelled. See also :meth:`Task.cancel`.
 

Doc/library/asyncio-exceptions.rst

@@ -13,11 +13,12 @@ Exceptions
 
 .. exception:: TimeoutError
 
-   The operation has exceeded the given deadline.
+   A deprecated alias of :exc:`TimeoutError`,
+   raised when the operation has exceeded the given deadline.
 
-   .. important::
-      This exception is different from the builtin :exc:`TimeoutError`
-      exception.
+   .. versionchanged:: 3.11
+
+      This class was made an alias of :exc:`TimeoutError`.
 
 
 .. exception:: CancelledError

Doc/library/asyncio-task.rst

@@ -490,7 +490,7 @@ Timeouts
    completes.
 
    If a timeout occurs, it cancels the task and raises
-   :exc:`asyncio.TimeoutError`.
+   :exc:`TimeoutError`.
 
    To avoid the task :meth:`cancellation <Task.cancel>`,
    wrap it in :func:`shield`.
@@ -520,7 +520,7 @@ Timeouts
            # Wait for at most 1 second
            try:
                await asyncio.wait_for(eternity(), timeout=1.0)
-           except asyncio.TimeoutError:
+           except TimeoutError:
                print('timeout!')
 
        asyncio.run(main())
@@ -532,7 +532,7 @@ Timeouts
    .. versionchanged:: 3.7
       When *aw* is cancelled due to a timeout, ``wait_for`` waits
       for *aw* to be cancelled.  Previously, it raised
-      :exc:`asyncio.TimeoutError` immediately.
+      :exc:`TimeoutError` immediately.
 
    .. deprecated-removed:: 3.8 3.10
       The ``loop`` parameter.  This function has been implicitly getting the
@@ -561,7 +561,7 @@ Waiting Primitives
    *timeout* (a float or int), if specified, can be used to control
    the maximum number of seconds to wait before returning.
 
-   Note that this function does not raise :exc:`asyncio.TimeoutError`.
+   Note that this function does not raise :exc:`TimeoutError`.
    Futures or Tasks that aren't done when the timeout occurs are simply
    returned in the second set.
 
@@ -649,7 +649,7 @@ Waiting Primitives
    Each coroutine returned can be awaited to get the earliest next
    result from the iterable of the remaining awaitables.
 
-   Raises :exc:`asyncio.TimeoutError` if the timeout occurs before
+   Raises :exc:`TimeoutError` if the timeout occurs before
    all Futures are done.
 
    .. deprecated-removed:: 3.8 3.10
@@ -762,7 +762,7 @@ Scheduling From Other Threads
 
      try:
          result = future.result(timeout)
-     except concurrent.futures.TimeoutError:
+     except TimeoutError:
          print('The coroutine took too long, cancelling the task...')
          future.cancel()
      except Exception as exc:

Doc/library/concurrent.futures.rst

@@ -47,7 +47,7 @@ Executor Objects
        * *func* is executed asynchronously and several calls to
          *func* may be made concurrently.
 
-       The returned iterator raises a :exc:`concurrent.futures.TimeoutError`
+       The returned iterator raises a :exc:`TimeoutError`
        if :meth:`~iterator.__next__` is called and the result isn't available
        after *timeout* seconds from the original call to :meth:`Executor.map`.
        *timeout* can be an int or a float.  If *timeout* is not specified or
@@ -352,7 +352,7 @@ The :class:`Future` class encapsulates the asynchronous execution of a callable.
        Return the value returned by the call. If the call hasn't yet completed
        then this method will wait up to *timeout* seconds.  If the call hasn't
        completed in *timeout* seconds, then a
-       :exc:`concurrent.futures.TimeoutError` will be raised. *timeout* can be
+       :exc:`TimeoutError` will be raised. *timeout* can be
        an int or float.  If *timeout* is not specified or ``None``, there is no
        limit to the wait time.
 
@@ -366,7 +366,7 @@ The :class:`Future` class encapsulates the asynchronous execution of a callable.
        Return the exception raised by the call.  If the call hasn't yet
        completed then this method will wait up to *timeout* seconds.  If the
        call hasn't completed in *timeout* seconds, then a
-       :exc:`concurrent.futures.TimeoutError` will be raised.  *timeout* can be
+       :exc:`TimeoutError` will be raised.  *timeout* can be
        an int or float.  If *timeout* is not specified or ``None``, there is no
        limit to the wait time.
 
@@ -482,7 +482,7 @@ Module Functions
    they complete (finished or cancelled futures). Any futures given by *fs* that
    are duplicated will be returned once. Any futures that completed before
    :func:`as_completed` is called will be yielded first.  The returned iterator
-   raises a :exc:`concurrent.futures.TimeoutError` if :meth:`~iterator.__next__`
+   raises a :exc:`TimeoutError` if :meth:`~iterator.__next__`
    is called and the result isn't available after *timeout* seconds from the
    original call to :func:`as_completed`.  *timeout* can be an int or float. If
    *timeout* is not specified or ``None``, there is no limit to the wait time.
@@ -506,7 +506,13 @@ Exception classes
 
 .. exception:: TimeoutError
 
-   Raised when a future operation exceeds the given timeout.
+   A deprecated alias of :exc:`TimeoutError`,
+   raised when a future operation exceeds the given timeout.
+
+   .. versionchanged:: 3.11
+
+      This class was made an alias of :exc:`TimeoutError`.
+
 
 .. exception:: BrokenExecutor
 

Lib/asyncio/exceptions.py

@@ -10,8 +10,7 @@ class CancelledError(BaseException):
     """The Future or Task was cancelled."""
 
 
-class TimeoutError(Exception):
-    """The operation exceeded the given deadline."""
+TimeoutError = TimeoutError  # make local alias for the standard exception
 
 
 class InvalidStateError(Exception):

Lib/concurrent/futures/_base.py

@@ -50,9 +50,7 @@ class CancelledError(Error):
     """The Future was cancelled."""
     pass
 
-class TimeoutError(Error):
-    """The operation exceeded the given deadline."""
-    pass
+TimeoutError = TimeoutError  # make local alias for the standard exception
 
 class InvalidStateError(Error):
     """The operation is not allowed in this state."""

Misc/NEWS.d/next/Library/2020-11-26-10-23-46.bpo-42413.HFikOl.rst

@@ -0,0 +1,2 @@
+Replace ``concurrent.futures.TimeoutError`` and ``asyncio.TimeoutError``
+with builtin :exc:`TimeoutError`, keep these names as deprecated aliases.