From 5bb35d29ab0ebec4d420eaf4f8d513e3cd680ad9 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Thu, 26 Nov 2020 10:24:43 +0200 Subject: [PATCH 1/4] Replace concurrent.futures.TimeoutError and asyncio.TimeoutError with builtin TimeoutError --- Doc/library/asyncio-api-index.rst | 5 --- Doc/library/asyncio-exceptions.rst | 9 +++-- Doc/library/asyncio-task.rst | 12 +++--- Doc/library/concurrent.futures.rst | 37 +++++++++++-------- Lib/asyncio/exceptions.py | 3 +- Lib/concurrent/futures/_base.py | 5 +-- .../2020-11-26-10-23-46.bpo-42413.HFikOl.rst | 2 + 7 files changed, 37 insertions(+), 36 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2020-11-26-10-23-46.bpo-42413.HFikOl.rst diff --git a/Doc/library/asyncio-api-index.rst b/Doc/library/asyncio-api-index.rst index 047e5bbc58ccad..0f88a0d09b37fe 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 7166d5c4bd88f9..bc005e5fee5e51 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.10 + + 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 c638f1263fdaa1..696613fb3b4f29 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -455,7 +455,7 @@ Timeouts completes. If a timeout occurs, it cancels the task and raises - :exc:`asyncio.TimeoutError`. + :exc:`TimeoutError`. To avoid the task :meth:`cancellation `, wrap it in :func:`shield`. @@ -482,7 +482,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()) @@ -494,7 +494,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. Waiting Primitives @@ -518,7 +518,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. @@ -597,7 +597,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 @@ -697,7 +697,7 @@ Scheduling From Other Threads try: result = future.result(timeout) - except asyncio.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 61d6c1143cfdd5..e37b9344a9fee2 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -1,5 +1,6 @@ -:mod:`concurrent.futures` --- Launching parallel tasks -====================================================== +======================================================== + :mod:`concurrent.futures` --- Launching parallel tasks +======================================================== .. module:: concurrent.futures :synopsis: Execute computations concurrently using threads or processes. @@ -21,7 +22,7 @@ defined by the abstract :class:`Executor` class. Executor Objects ----------------- +================ .. class:: Executor @@ -47,7 +48,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 @@ -108,7 +109,7 @@ Executor Objects ThreadPoolExecutor ------------------- +================== :class:`ThreadPoolExecutor` is an :class:`Executor` subclass that uses a pool of threads to execute calls asynchronously. @@ -184,7 +185,7 @@ And:: .. _threadpoolexecutor-example: ThreadPoolExecutor Example -~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------- :: import concurrent.futures @@ -216,7 +217,7 @@ ThreadPoolExecutor Example ProcessPoolExecutor -------------------- +=================== The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that uses a pool of processes to execute calls asynchronously. @@ -268,7 +269,7 @@ to a :class:`ProcessPoolExecutor` will result in deadlock. .. _processpoolexecutor-example: ProcessPoolExecutor Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- :: import concurrent.futures @@ -306,7 +307,7 @@ ProcessPoolExecutor Example Future Objects --------------- +============== The :class:`Future` class encapsulates the asynchronous execution of a callable. :class:`Future` instances are created by :meth:`Executor.submit`. @@ -343,7 +344,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. @@ -357,7 +358,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. @@ -430,7 +431,7 @@ The :class:`Future` class encapsulates the asynchronous execution of a callable. already done. Module Functions ----------------- +================ .. function:: wait(fs, timeout=None, return_when=ALL_COMPLETED) @@ -473,7 +474,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. @@ -487,7 +488,7 @@ Module Functions Exception classes ------------------ +================= .. currentmodule:: concurrent.futures @@ -497,7 +498,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.10 + + This class was made an alias of :exc:`TimeoutError`. + .. exception:: BrokenExecutor diff --git a/Lib/asyncio/exceptions.py b/Lib/asyncio/exceptions.py index e03602ef576234..23fa1b9dd16b83 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 00eb54881f2958..b92f52ea3ee19f 100644 --- a/Lib/concurrent/futures/_base.py +++ b/Lib/concurrent/futures/_base.py @@ -50,10 +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.""" pass 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 00000000000000..85b7fe25074b36 --- /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. From 0b1abf5bb2d6ac8ec407c3948d74ca59f67acf26 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Thu, 26 Nov 2020 10:28:46 +0200 Subject: [PATCH 2/4] Revert back unrelated formatting changes --- Doc/library/concurrent.futures.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index e37b9344a9fee2..796c1c0814f1fd 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -1,6 +1,5 @@ -======================================================== - :mod:`concurrent.futures` --- Launching parallel tasks -======================================================== +:mod:`concurrent.futures` --- Launching parallel tasks +====================================================== .. module:: concurrent.futures :synopsis: Execute computations concurrently using threads or processes. @@ -22,7 +21,7 @@ defined by the abstract :class:`Executor` class. Executor Objects -================ +---------------- .. class:: Executor @@ -109,7 +108,7 @@ Executor Objects ThreadPoolExecutor -================== +------------------ :class:`ThreadPoolExecutor` is an :class:`Executor` subclass that uses a pool of threads to execute calls asynchronously. @@ -185,7 +184,7 @@ And:: .. _threadpoolexecutor-example: ThreadPoolExecutor Example --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ :: import concurrent.futures @@ -217,7 +216,7 @@ ThreadPoolExecutor Example ProcessPoolExecutor -=================== +------------------- The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that uses a pool of processes to execute calls asynchronously. @@ -269,7 +268,7 @@ to a :class:`ProcessPoolExecutor` will result in deadlock. .. _processpoolexecutor-example: ProcessPoolExecutor Example ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: import concurrent.futures @@ -307,7 +306,7 @@ ProcessPoolExecutor Example Future Objects -============== +-------------- The :class:`Future` class encapsulates the asynchronous execution of a callable. :class:`Future` instances are created by :meth:`Executor.submit`. @@ -431,7 +430,7 @@ The :class:`Future` class encapsulates the asynchronous execution of a callable. already done. Module Functions -================ +---------------- .. function:: wait(fs, timeout=None, return_when=ALL_COMPLETED) @@ -488,7 +487,7 @@ Module Functions Exception classes -================= +----------------- .. currentmodule:: concurrent.futures From 46b3eb7cbb6e5ea45e2a6ab631eda253c1ed1a1b Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Thu, 26 Nov 2020 10:56:25 +0200 Subject: [PATCH 3/4] Add whatsnew --- Doc/whatsnew/3.10.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst index f96a3bcbca95f3..135b0b55a50c04 100644 --- a/Doc/whatsnew/3.10.rst +++ b/Doc/whatsnew/3.10.rst @@ -167,6 +167,12 @@ New Modules Improved Modules ================ +asyncio +------ + +The exception :exc:`asyncio.TimeoutError` is now an alias of :exc:`TimeoutError`. +(Contributed by Andrew Svetlov in :issue:`42413`.) + base64 ------ @@ -179,6 +185,13 @@ codecs Add a :func:`codecs.unregister` function to unregister a codec search function. (Contributed by Hai Shi in :issue:`41842`.) +concurrent.futures +------------------ + +The exception :exc:`concurrent.futures.TimeoutError` is now +an alias of :exc:`TimeoutError`. +(Contributed by Andrew Svetlov in :issue:`42413`.) + contextlib ---------- From c2f87432c26b84531d5d3d0d982de28c3c9c1548 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Thu, 26 Nov 2020 11:07:25 +0200 Subject: [PATCH 4/4] fix --- Doc/whatsnew/3.10.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst index 135b0b55a50c04..20fca4732278af 100644 --- a/Doc/whatsnew/3.10.rst +++ b/Doc/whatsnew/3.10.rst @@ -168,7 +168,7 @@ Improved Modules ================ asyncio ------- +------- The exception :exc:`asyncio.TimeoutError` is now an alias of :exc:`TimeoutError`. (Contributed by Andrew Svetlov in :issue:`42413`.)