From 560218e36e671fe00031f21d9588c0e72e802940 Mon Sep 17 00:00:00 2001 From: "Joe S. Boyle" Date: Wed, 22 Mar 2023 21:34:36 +0000 Subject: [PATCH 1/8] Update the sphinx docs for asyncio.Timeout - Add a note recommending the use of the async context factories timeout() and timeout_at() - Add the missing argument to the class definition - Add a description of what the when param does, and it's possible values. --- Doc/library/asyncio-task.rst | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index d908e45b3c8d8b..db9ac27c953c3b 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -624,10 +624,24 @@ Timeouts The context manager produced by :func:`asyncio.timeout` can be rescheduled to a different deadline and inspected. - .. class:: Timeout() + .. class:: Timeout(when) An :ref:`asynchronous context manager ` - that limits time spent inside of it. + context manager for cancelling overdue coroutines. + + .. note:: + + Please use :meth:`timeout()` or :meth:`timeout_at()` + rather than instantiating this class directly. + + The ``when`` parameter specifies at what time the context should + time out. It's value should be either a float relative to the + current :meth:`loop.time` or ``None``, if the context should never + expire. + + 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. .. versionadded:: 3.11 @@ -636,21 +650,10 @@ Timeouts Return the current deadline, or ``None`` if the current deadline is not set. - The deadline is a float, consistent with the time returned by - :meth:`loop.time`. - .. method:: reschedule(when: float | None) Change the time the timeout will trigger. - If *when* is ``None``, any current deadline will be removed, and the - context manager will wait indefinitely. - - If *when* is a float, it is set as the new deadline. - - if *when* is in the past, the timeout will trigger on the next - iteration of the event loop. - .. method:: expired() -> bool Return whether the context manager has exceeded its deadline From fbb869d43684eec3806ab1bda6e3b32d661914e9 Mon Sep 17 00:00:00 2001 From: "Joe S. Boyle" Date: Wed, 22 Mar 2023 21:46:08 +0000 Subject: [PATCH 2/8] Trim asyncio.Timeout docs --- Doc/library/asyncio-task.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index db9ac27c953c3b..feb3505becac02 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -636,8 +636,7 @@ Timeouts The ``when`` parameter specifies at what time the context should time out. It's value should be either a float relative to the - current :meth:`loop.time` or ``None``, if the context should never - expire. + current :meth:`loop.time` or ``None``. If ``when`` is ``None``, the timeout will never trigger. If ``when < loop.time()``, the timeout will trigger on the next From f2138f876f3a75be350200120b7e35bf5aa8a7c4 Mon Sep 17 00:00:00 2001 From: JosephSBoyle <48555120+JosephSBoyle@users.noreply.github.com> Date: Wed, 22 Mar 2023 21:49:19 +0000 Subject: [PATCH 3/8] Update Doc/library/asyncio-task.rst Co-authored-by: Alex Waygood --- Doc/library/asyncio-task.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index feb3505becac02..b15b9b0efe2aae 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -627,7 +627,7 @@ Timeouts .. class:: Timeout(when) An :ref:`asynchronous context manager ` - context manager for cancelling overdue coroutines. + for cancelling overdue coroutines. .. note:: From 9506cf56c348b1f5229ae02aa6816f251bbbd6d4 Mon Sep 17 00:00:00 2001 From: JosephSBoyle <48555120+JosephSBoyle@users.noreply.github.com> Date: Wed, 22 Mar 2023 22:07:21 +0000 Subject: [PATCH 4/8] Apply @alexwaygood 's suggestions Co-authored-by: Alex Waygood --- Doc/library/asyncio-task.rst | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index b15b9b0efe2aae..8b601aec1cdb70 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -629,11 +629,6 @@ Timeouts An :ref:`asynchronous context manager ` for cancelling overdue coroutines. - .. note:: - - Please use :meth:`timeout()` or :meth:`timeout_at()` - rather than instantiating this class directly. - The ``when`` parameter specifies at what time the context should time out. It's value should be either a float relative to the current :meth:`loop.time` or ``None``. @@ -642,7 +637,7 @@ Timeouts If ``when < loop.time()``, the timeout will trigger on the next iteration of the event loop. - .. versionadded:: 3.11 + .. versionadded:: 3.11 .. method:: when() -> float | None @@ -651,7 +646,7 @@ Timeouts .. method:: reschedule(when: float | None) - Change the time the timeout will trigger. + Reschedule the timeout. .. method:: expired() -> bool From efa8935e71d50104a9327631bcecbff0d476463f Mon Sep 17 00:00:00 2001 From: JosephSBoyle <48555120+JosephSBoyle@users.noreply.github.com> Date: Wed, 22 Mar 2023 22:21:55 +0000 Subject: [PATCH 5/8] Update Doc/library/asyncio-task.rst Co-authored-by: Alex Waygood --- Doc/library/asyncio-task.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 8b601aec1cdb70..b971c281600884 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -629,13 +629,12 @@ Timeouts An :ref:`asynchronous context manager ` for cancelling overdue coroutines. - The ``when`` parameter specifies at what time the context should - time out. It's value should be either a float relative to the - current :meth:`loop.time` or ``None``. + ``when`` should be either a float relative to the current + :meth:`loop.time` or ``None``: - 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. + - 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. .. versionadded:: 3.11 From 1454cbbce1e2360a1860d1af60665f9332317e68 Mon Sep 17 00:00:00 2001 From: JosephSBoyle <48555120+JosephSBoyle@users.noreply.github.com> Date: Thu, 23 Mar 2023 10:08:12 +0000 Subject: [PATCH 6/8] Apply @alexwaygood 's suggestion Co-authored-by: Alex Waygood --- Doc/library/asyncio-task.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index b971c281600884..b0746e91f552d3 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -636,8 +636,6 @@ Timeouts - If ``when < loop.time()``, the timeout will trigger on the next iteration of the event loop. - .. versionadded:: 3.11 - .. method:: when() -> float | None Return the current deadline, or ``None`` if the current From 84b418a25b6d93b802ebae6b43c4d2554969b74e Mon Sep 17 00:00:00 2001 From: JosephSBoyle <48555120+JosephSBoyle@users.noreply.github.com> Date: Thu, 23 Mar 2023 15:50:28 +0000 Subject: [PATCH 7/8] Update Doc/library/asyncio-task.rst --- Doc/library/asyncio-task.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index b0746e91f552d3..ce3c0327f2f3cc 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -629,8 +629,8 @@ Timeouts An :ref:`asynchronous context manager ` for cancelling overdue coroutines. - ``when`` should be either a float relative to the current - :meth:`loop.time` or ``None``: + ``when`` should be an absolute time at which the context should time out, + as measured by the event loop's clock. - If ``when`` is ``None``, the timeout will never trigger. - If ``when < loop.time()``, the timeout will trigger on the next From 702d2ae08ccdaa8ac67bf475e871e04bcf102d5a Mon Sep 17 00:00:00 2001 From: JosephSBoyle <48555120+JosephSBoyle@users.noreply.github.com> Date: Thu, 23 Mar 2023 16:11:51 +0000 Subject: [PATCH 8/8] Update Doc/library/asyncio-task.rst Co-authored-by: Alex Waygood --- Doc/library/asyncio-task.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index ce3c0327f2f3cc..c5a480ba20190a 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -630,7 +630,7 @@ Timeouts for cancelling overdue coroutines. ``when`` should be an absolute time at which the context should time out, - as measured by the event loop's clock. + as measured by the event loop's clock: - If ``when`` is ``None``, the timeout will never trigger. - If ``when < loop.time()``, the timeout will trigger on the next