(api-break) remove Clock.schedule_once()

Author: gottadiveintopython

README.md

@@ -1,27 +1,6 @@
 # Clock
 
-*An event scheduler designed for asyncgui programs.*
-
-First, take a look at the callback-style code below that has nothing to do with `asyncgui`.
-If you've ever used `Kivy` or `Pyglet`, you may find it familiar.
-
-```python
-from asyncgui_ext.clock import Clock
-
-clock = Clock()
-
-# Schedules a function to be called after a delay of 20 time units.
-clock.schedule_once(lambda dt: print("Hello"), 20)
-
-# Advances the clock by 10 time units.
-clock.tick(10)
-
-# The clock advanced by a total of 20 time units.
-# The callback function will be called.
-clock.tick(10)  # => Hello
-```
-
-Next one is async/await-style code that involves `asyncgui`, and does the same thing as the previous.
+*Event scheduler designed for asyncgui programs.*
 
 ```python
 import asyncgui
@@ -30,37 +9,37 @@ from asyncgui_ext.clock import Clock
 clock = Clock()
 
 async def async_fn():
-    await clock.sleep(20)
+    await clock.sleep(20)  # Waits for 20 time units
     print("Hello")
 
 asyncgui.start(async_fn())
-clock.tick(10)
-clock.tick(10)  # => Hello
+clock.tick(10)  # Advances the clock by 10 time units.
+clock.tick(10)  # Total of 20 time units. The task above will wake up, and prints 'Hello'.
 ```
 
-These two examples effectively illustrate how this module works but they are not practical.
+The example above effectively illustrate how this module works but it's not practical.
 In a real-world program, you probably want to call ``clock.tick()`` in a loop or schedule it to be called repeatedly using another scheduling API.
 For example, if you are using `PyGame`, you may want to do:
 
 ```python
-clock = pygame.time.Clock()
-vclock = asyncgui_ext.clock.Clock()
+pygame_clock = pygame.time.Clock()
+clock = asyncgui_ext.clock.Clock()
 
 # main loop
 while running:
     ...
 
-    dt = clock.tick(fps)
-    vclock.tick(dt)
+    dt = pygame_clock.tick(fps)
+    clock.tick(dt)
 ```
 
 And if you are using `Kivy`, you may want to do:
 
 ```python
 from kivy.clock import Clock
 
-vclock = asyncui_ext.clock.Clock()
-Clock.schedule_interval(vclock.tick, 0)
+clock = asyncui_ext.clock.Clock()
+Clock.schedule_interval(clock.tick, 0)
 ```
 
 ## Installation

sphinx/readme_jp.rst

@@ -3,27 +3,6 @@ ReadMe |ja|
 ===========
 
 このモジュールは :mod:`asyncgui` を用いるプログラム向けのタイマー機能を提供します。
-機能は大別するとコールバック型とasync/await型に分けられ、状況に応じて好きな方を使えます。
-まずはコールバック型のAPIを用いた以下のコードを見てください。
-
-.. code-block::
-
-    from asyncgui_ext.clock import Clock
-
-    clock = Clock()
-
-    # 20経過後に関数が呼ばれるようにする。
-    clock.schedule_once(lambda dt: print("Hello"), 20)
-
-    # 時計を10進める。
-    clock.tick(10)
-
-    # 合計で20進むので関数が呼ばれる。
-    clock.tick(10)  # => Hello
-
-:mod:`sched` と同じで時間の単位が決まってない事に気付いたと思います。
-APIに渡す時間の単位は統一さえされていれば何でも構いません。
-次は同じ事をするasync/await型のコードを見てください。
 
 .. code-block::
 
@@ -33,38 +12,41 @@ APIに渡す時間の単位は統一さえされていれば何でも構いま
     clock = Clock()
 
     async def async_fn():
-        await clock.sleep(20)
+        await clock.sleep(20)  # 時間が20経過するのを待つ。
         print("Hello")
 
     asyncgui.start(async_fn())
-    clock.tick(10)
-    clock.tick(10)  # => Hello
+    clock.tick(10)  # 時間が10進む。
+    clock.tick(10)  # 合計で20進むのでタスクが再開し 'Hello' が表示される。
+
+この様に ``clock.tick()`` を呼ぶ事で時計内部の時が進み停止中のタスクが再開するわけです。
+また :mod:`sched` と同じで時間の単位が決まってない事に気付いたと思います。
+APIに渡す時間の単位は統一さえされていれば何でも構いません。
 
-この様に ``clock.tick()`` を呼ぶ事で時計内部の時が進み、関数が呼ばれたり停止中のタスクが再開するわけです。
-ただこれらの例はこのモジュールの仕組みを示してはいますが実用的な使い方ではありません。
-実際のプログラムでは ``clock.tick()`` をループ内で呼んだり別のタイマーを用いて定期的に呼ぶ事になると思います。
+ただ上記の例はこのモジュールの仕組みを示しているだけであり実用的な使い方ではありません。
+実際のプログラムでは ``clock.tick()`` をメインループ内で呼んだり別のタイマーを用いて定期的に呼ぶ事になると思います。
 例えば ``PyGame`` を使っているなら以下のように、
 
 .. code-block::
 
-    clock = pygame.time.Clock()
-    vclock = asyncgui_ext.clock.Clock()
+    pygame_clock = pygame.time.Clock()
+    clock = asyncgui_ext.clock.Clock()
 
     # メインループ
     while running:
         ...
 
-        dt = clock.tick(fps)
-        vclock.tick(dt)
+        dt = pygame_clock.tick(fps)
+        clock.tick(dt)
 
 ``Kivy`` を使っているなら以下のようになるでしょう。
 
 .. code-block::
 
     from kivy.clock import Clock
 
-    vclock = asyncui_ext.clock.Clock()
-    Clock.schedule_interval(vclock.tick, 0)
+    clock = asyncui_ext.clock.Clock()
+    Clock.schedule_interval(clock.tick, 0)
 
 インストール方法
 -----------------------

src/asyncgui_ext/clock.py

@@ -11,7 +11,7 @@
 from threading import Thread
 from concurrent.futures import ThreadPoolExecutor
 
-from asyncgui import AsyncEvent, Cancelled, Task, move_on_when, _sleep_forever, _current_task
+from asyncgui import Cancelled, Task, move_on_when, _sleep_forever, _current_task
 
 TimeUnit = TypeVar("TimeUnit")
 ClockCallback: TypeAlias = Callable[[TimeUnit], None]
@@ -82,8 +82,6 @@ def tick(self, delta_time):
                 tba_append(e)
                 continue
             e.callback(cur_time - e._last_tick)
-            if e._interval is None:
-                continue
             e._deadline += e._interval
             e._last_tick = cur_time
             tba_append(e)
@@ -92,30 +90,6 @@ def tick(self, delta_time):
         self._events = events_tba
         self._events_to_be_added = events
 
-    def schedule_once(self, func, delay) -> ClockEvent:
-        '''
-        Schedules the ``func`` to be called after the ``delay``.
-
-        To unschedule:
-
-        .. code-block::
-
-            event = clock.schedule_once(func, 10)
-            event.cancel()
-
-        You can use this ``event`` object as a context manager, and it will be automatically unscheduled when the
-        context manager exits.
-
-        .. code-block::
-
-            with clock.schedule_once(func, 10):
-                ...
-        '''
-        cur_time = self._cur_time
-        event = ClockEvent(cur_time + delay, cur_time, func, None)
-        self._events_to_be_added.append(event)
-        return event
-
     def schedule_interval(self, func, interval) -> ClockEvent:
         '''
         Schedules the ``func`` to be called repeatedly at a specified interval.
@@ -125,6 +99,7 @@ def schedule_interval(self, func, interval) -> ClockEvent:
         self._events_to_be_added.append(event)
         return event
 
+    @types.coroutine
     def sleep(self, duration) -> Awaitable:
         '''
         Waits for a specified period of time.
@@ -133,9 +108,12 @@ def sleep(self, duration) -> Awaitable:
 
             await clock.sleep(10)
         '''
-        ev = AsyncEvent()
-        self.schedule_once(ev.fire, duration)
-        return ev.wait()
+        task = (yield _current_task)[0][0]
+        event = self.schedule_interval(task._step, duration)
+        try:
+            yield _sleep_forever
+        finally:
+            event.cancel()
 
     def move_on_after(self, timeout) -> AbstractAsyncContextManager[Task]:
         '''

tests/clock/test_schedule_xxx.py

@@ -1,71 +1,3 @@
-def test_once(clock):
-    dt_list = []
-    func = dt_list.append
-
-    clock.schedule_once(func, 100)
-    assert dt_list == []
-    clock.schedule_once(func, 50)
-    assert dt_list == []
-    clock.tick(20)
-    assert dt_list == []
-    clock.schedule_once(func, 40)
-    assert dt_list == []
-    clock.tick(50)
-    assert sorted(dt_list) == [50, 70, ]
-    clock.tick(50)
-    assert sorted(dt_list) == [50, 70, 120, ]
-
-
-def test_once_zero_delay(clock):
-    dt_list = []
-
-    clock.schedule_once(dt_list.append, 0)
-    assert dt_list == []
-    clock.tick(0)
-    assert dt_list == [0, ]
-    clock.tick(0)
-    assert dt_list == [0, ]
-
-
-def test_once_cancel(clock):
-    dt_list = []
-    func = dt_list.append
-
-    e = clock.schedule_once(func, 100)
-    clock.schedule_once(func, 50)
-    e.cancel()
-    assert dt_list == []
-    clock.tick(60)
-    assert dt_list == [60, ]
-    clock.tick(60)
-    assert dt_list == [60, ]
-
-
-def test_once_cancel_from_a_callback(clock):
-    dt_list = []
-
-    e = clock.schedule_once(dt_list.append, 100)
-    clock.schedule_once(lambda __: e.cancel(), 50)
-    assert dt_list == []
-    clock.tick(60)
-    assert dt_list == []
-    clock.tick(60)
-    assert dt_list == []
-
-
-def test_once_schedule_from_a_callback(clock):
-    dt_list = []
-
-    clock.schedule_once(lambda dt: clock.schedule_once(dt_list.append, 50), 50)
-    assert dt_list == []
-    clock.tick(50)
-    assert dt_list == []
-    clock.tick(50)
-    assert dt_list == [50, ]
-    clock.tick(50)
-    assert dt_list == [50, ]
-
-
 def test_interval(clock):
     dt_list = []