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

Sun Dec 19 06:23:05 EST 2021

https://github.com/python/cpython/commit/da4b214304df38cf1831071804a2b83938f95923
commit: da4b214304df38cf1831071804a2b83938f95923
branch: main
author: Kumar Aditya <59607654+kumaraditya303 at users.noreply.github.com>
committer: asvetlov <andrew.svetlov at gmail.com>
date: 2021年12月19日T13:22:40+02:00
summary:
bpo-42413: Replace `concurrent.futures.TimeoutError` and `asyncio.TimeoutError` with builtin `TimeoutError` (GH-30197)
Co-authored-by: Andrew Svetlov <andrew.svetlov at gmail.com>
files:
A Misc/NEWS.d/next/Library/2020-11-26-10-23-46.bpo-42413.HFikOl.rst
M Doc/library/asyncio-api-index.rst
M Doc/library/asyncio-exceptions.rst
M Doc/library/asyncio-task.rst
M Doc/library/concurrent.futures.rst
M Lib/asyncio/exceptions.py
M Lib/concurrent/futures/_base.py

diff --git a/Doc/library/asyncio-api-index.rst b/Doc/library/asyncio-api-index.rst
index f558724d4a3ff..8bc7943a71739 100644
--- a/Doc/library/asyncio-api-index.rst
+++ b/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`.
 
diff --git a/Doc/library/asyncio-exceptions.rst b/Doc/library/asyncio-exceptions.rst
index 7166d5c4bd88f..9250f01b8a089 100644
--- a/Doc/library/asyncio-exceptions.rst
+++ b/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
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index bfc983e304bcc..cbc42ac26e48c 100644
--- a/Doc/library/asyncio-task.rst
+++ b/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:
diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index b4213b451157e..c9f6aa1f2637c 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/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
 
diff --git a/Lib/asyncio/exceptions.py b/Lib/asyncio/exceptions.py
index f07e448657738..c764c9ffcfc19 100644
--- a/Lib/asyncio/exceptions.py
+++ b/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):
diff --git a/Lib/concurrent/futures/_base.py b/Lib/concurrent/futures/_base.py
index 6095026cb278b..b0337399e5f25 100644
--- a/Lib/concurrent/futures/_base.py
+++ b/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."""
diff --git a/Misc/NEWS.d/next/Library/2020-11-26-10-23-46.bpo-42413.HFikOl.rst b/Misc/NEWS.d/next/Library/2020-11-26-10-23-46.bpo-42413.HFikOl.rst
new file mode 100644
index 0000000000000..85b7fe25074b3
--- /dev/null
+++ b/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.
