Implement TimerHandle.when() (#5473)

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 5f915c5c43921ad571d3f731890f5498c02305c6..a19c670d0f306821c6b7d95943a9c2d4a27bd009 100644 (file)
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -171,7 +171,7 @@ a different clock than :func:`time.time`.
    Arrange for the *callback* to be called after the given *delay*
    seconds (either an int or float).
 
-   An instance of :class:`asyncio.Handle` is returned, which can be
+   An instance of :class:`asyncio.TimerHandle` is returned, which can be
    used to cancel the callback.
 
    *callback* will be called exactly once per call to :meth:`call_later`.
@@ -193,7 +193,7 @@ a different clock than :func:`time.time`.
 
    This method's behavior is the same as :meth:`call_later`.
 
-   An instance of :class:`asyncio.Handle` is returned, which can be
+   An instance of :class:`asyncio.TimerHandle` is returned, which can be
    used to cancel the callback.
 
    :ref:`Use functools.partial to pass keywords to the callback
@@ -1076,8 +1076,7 @@ Handle
 .. class:: Handle
 
    A callback wrapper object returned by :func:`AbstractEventLoop.call_soon`,
-   :func:`AbstractEventLoop.call_soon_threadsafe`, :func:`AbstractEventLoop.call_later`,
-   and :func:`AbstractEventLoop.call_at`.
+   :func:`AbstractEventLoop.call_soon_threadsafe`.
 
    .. method:: cancel()
 
@@ -1090,6 +1089,22 @@ Handle
 
       .. versionadded:: 3.7
 
+.. class:: TimerHandle
+
+   A callback wrapper object returned by :func:`AbstractEventLoop.call_later`,
+   and :func:`AbstractEventLoop.call_at`.
+
+   The class is inherited from :class:`Handle`.
+
+   .. method:: when()
+
+      Return a scheduled callback time as :class:`float` seconds.
+
+      The time is an absolute timestamp, using the same time
+      reference as :meth:`AbstractEventLoop.time`.
+
+      .. versionadded:: 3.7
+
 
 SendfileNotAvailableError
 -------------------------

diff --git a/Lib/asyncio/events.py b/Lib/asyncio/events.py
index bdefcf62a05d9e783d9bcd2891e125b06eae448d..fcca5d4cb34716823ae587d7d43950d477ec3770 100644 (file)
--- a/Lib/asyncio/events.py
+++ b/Lib/asyncio/events.py
@@ -156,6 +156,14 @@ class TimerHandle(Handle):
             self._loop._timer_handle_cancelled(self)
         super().cancel()
 
+    def when(self):
+        """Return a scheduled callback time.
+
+        The time is an absolute timestamp, using the same time
+        reference as loop.time().
+        """
+        return self._when
+
 
 class AbstractServer:
     """Abstract server returned by create_server()."""

diff --git a/Lib/test/test_asyncio/test_events.py b/Lib/test/test_asyncio/test_events.py
index f54802cf8af21a2141083a426a686db8e2d7010e..f5995974c683a6a9549576cdbbb9e86ff9f93a0d 100644 (file)
--- a/Lib/test/test_asyncio/test_events.py
+++ b/Lib/test/test_asyncio/test_events.py
@@ -2679,6 +2679,12 @@ class TimerTests(unittest.TestCase):
                                 mock.Mock())
         self.assertEqual(hash(h), hash(when))
 
+    def test_when(self):
+        when = time.monotonic()
+        h = asyncio.TimerHandle(when, lambda: False, (),
+                                mock.Mock())
+        self.assertEqual(when, h.when())
+
     def test_timer(self):
         def callback(*args):
             return args

diff --git a/Misc/NEWS.d/next/Library/2018-02-01-17-54-08.bpo-32741.KUvOPL.rst b/Misc/NEWS.d/next/Library/2018-02-01-17-54-08.bpo-32741.KUvOPL.rst
new file mode 100644 (file)
index 0000000..651e766
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2018-02-01-17-54-08.bpo-32741.KUvOPL.rst
@@ -0,0 +1 @@
+Implement ``asyncio.TimerHandle.when()`` method.