Rename Clock.tick -> Clock.advance, and leave the original name as an alias.

Author: gottadiveintopython

README.md

@@ -1,7 +1,5 @@
 # Clock
 
-Provides async time-related functionality.
-
 ```python
 import asyncgui
 from asyncgui_ext.clock import Clock
@@ -13,12 +11,12 @@ async def async_fn():
     print("Hello")
 
 asyncgui.start(async_fn())
-clock.tick(10)  # Advances the clock by 10 time units.
-clock.tick(10)  # Total of 20 time units. The async_fn will wake up, and prints 'Hello'.
+clock.advance(10)  # Advances the clock by 10 time units.
+clock.advance(10)  # Total of 20 time units. The async_fn will wake up, and prints 'Hello'.
 ```
 
 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 main loop.
+In a real-world program, you probably want to call ``clock.advance()`` in a main loop.
 For example, if you are using `PyGame`, you may want to do:
 
 ```python
@@ -29,8 +27,8 @@ clock = asyncgui_ext.clock.Clock()
 while running:
     ...
 
-    dt = pygame_clock.tick(fps)
-    clock.tick(dt)
+    dt = pygame_clock.advance(fps)
+    clock.advance(dt)
 ```
 
 ## Installation

sphinx/readme_jp.rst

@@ -16,15 +16,15 @@ ReadMe |ja|
         print("Hello")
 
     asyncgui.start(async_fn())
-    clock.tick(10)  # 時間を10進める。
-    clock.tick(10)  # 合計で20進むのでタスクが再開し 'Hello' が表示される。
+    clock.advance(10)  # 時間を10進める。
+    clock.advance(10)  # 合計で20進むのでタスクが再開し 'Hello' が表示される。
 
-この様に ``clock.tick()`` を呼ぶ事で時計内部の時が進み停止中のタスクが再開します。
+この様に ``clock.advance()`` を呼ぶ事で時計内部の時が進み停止中のタスクが再開します。
 また :mod:`sched` と同じで時間の単位が決まってない事に気付いたと思います。
 APIに渡す時間の単位は統一さえされていれば何でも構いません。
 
 ただ上記の例はこのモジュールの仕組みを示しているだけであり実用的な使い方ではありません。
-実際のプログラムでは ``clock.tick()`` をメインループ内で呼んだり別のタイマーを用いて定期的に呼ぶ事になると思います。
+実際のプログラムでは ``clock.advance()`` をメインループ内で呼んだり別のタイマーを用いて定期的に呼ぶ事になると思います。
 例えば ``PyGame`` を使っているなら以下のように、
 
 .. code-block::
@@ -36,8 +36,8 @@ APIに渡す時間の単位は統一さえされていれば何でも構いま
     while running:
         ...
 
-        dt = pygame_clock.tick(fps)
-        clock.tick(dt)
+        dt = pygame_clock.advance(fps)
+        clock.advance(dt)
 
 ``Kivy`` を使っているなら以下のようになるでしょう。
 
@@ -46,7 +46,7 @@ APIに渡す時間の単位は統一さえされていれば何でも構いま
     from kivy.clock import Clock
 
     clock = asyncui_ext.clock.Clock()
-    Clock.schedule_interval(clock.tick, 0)
+    Clock.schedule_interval(clock.advance, 0)
 
 インストール方法
 -----------------------

src/asyncgui_ext/clock.py

@@ -55,10 +55,11 @@ def __init__(self, initial_time=0):
     def current_time(self) -> TimeUnit:
         return self._cur_time
 
-    def tick(self, delta_time):
+    def advance(self, delta_time):
         '''
         Advances the clock time and triggers scheduled events accordingly.
-        The ``delta_time`` must be 0 or greater.
+
+        :param delta_time: Must be 0 or greater.
 
         .. warning::
 
@@ -88,6 +89,8 @@ def tick(self, delta_time):
         self._events = events_tba
         self._events_to_be_added = events
 
+    tick = advance
+
     def schedule_interval(self, func, interval) -> ClockEvent:
         '''
         Schedules the ``func`` to be called repeatedly at a specified interval.
@@ -133,7 +136,7 @@ def move_on_after(self, timeout) -> AbstractAsyncContextManager[Task]:
     @types.coroutine
     def n_frames(self, n: int) -> Awaitable:
         '''
-        Waits for a specified number of times the :meth:`tick` to be called.
+        Waits for a specified number of times the :meth:`advance` to be called.
 
         .. code-block::
 

tests/clock/test_anim_attrs.py

@@ -9,13 +9,13 @@ def test_scalar(clock):
     task = asyncgui.start(clock.anim_attrs(obj, num=20, duration=100))
 
     assert int(obj.num) == 0
-    clock.tick(30)
+    clock.advance(30)
     assert int(obj.num) == 6
-    clock.tick(30)
+    clock.advance(30)
     assert int(obj.num) == 12
-    clock.tick(30)
+    clock.advance(30)
     assert int(obj.num) == 18
-    clock.tick(30)
+    clock.advance(30)
     assert int(obj.num) == 20
     assert task.finished
 
@@ -29,12 +29,12 @@ def test_sequence(clock):
     task = asyncgui.start(clock.anim_attrs(obj, pos=[100, 0], duration=100))
 
     assert obj.pos == approx([0, 100])
-    clock.tick(30)
+    clock.advance(30)
     assert obj.pos == approx([30, 70])
-    clock.tick(30)
+    clock.advance(30)
     assert obj.pos == approx([60, 40])
-    clock.tick(30)
+    clock.advance(30)
     assert obj.pos == approx([90, 10])
-    clock.tick(30)
+    clock.advance(30)
     assert obj.pos == approx([100, 0])
     assert task.finished

tests/clock/test_anim_with_xxx.py

@@ -11,15 +11,15 @@ async def async_fn():
 
     task = start(async_fn())
     assert dt_list == []
-    clock.tick(10)
+    clock.advance(10)
     assert dt_list == [10]
-    clock.tick(20)
+    clock.advance(20)
     assert dt_list == [10, 20]
-    clock.tick(5)
+    clock.advance(5)
     assert dt_list == [10, 20, 5]
-    clock.tick(5)
+    clock.advance(5)
     assert dt_list == [10, 20, 5, 5]
-    clock.tick(5)
+    clock.advance(5)
     assert dt_list == [10, 20, 5, 5]
     task.cancel()
 
@@ -34,15 +34,15 @@ async def async_fn():
 
     task = start(async_fn())
     assert et_list == []
-    clock.tick(10)
+    clock.advance(10)
     assert et_list == [10]
-    clock.tick(20)
+    clock.advance(20)
     assert et_list == [10, 30]
-    clock.tick(5)
+    clock.advance(5)
     assert et_list == [10, 30, 35]
-    clock.tick(5)
+    clock.advance(5)
     assert et_list == [10, 30, 35, 40]
-    clock.tick(5)
+    clock.advance(5)
     assert et_list == [10, 30, 35, 40]
     task.cancel()
 
@@ -60,17 +60,17 @@ async def async_fn():
 
     task = start(async_fn())
     assert p_list == []
-    clock.tick(10)
+    clock.advance(10)
     assert p_list == approx([0.1])
-    clock.tick(20)
+    clock.advance(20)
     assert p_list == approx([0.1, 0.3])
-    clock.tick(5)
+    clock.advance(5)
     assert p_list == approx([0.1, 0.3, 0.35, ])
-    clock.tick(5)
+    clock.advance(5)
     assert p_list == approx([0.1, 0.3, 0.35, 0.4, ])
-    clock.tick(5)
+    clock.advance(5)
     assert p_list == approx([0.1, 0.3, 0.35, 0.4, ])
-    clock.tick(105)
+    clock.advance(105)
     assert p_list == approx([0.1, 0.3, 0.35, 0.4, 1.5])
     assert task.finished
 
@@ -85,10 +85,10 @@ async def async_fn():
 
     task = start(async_fn())
     assert p_list == []
-    clock.tick(6)
+    clock.advance(6)
     assert p_list == []
     with pytest.raises(ZeroDivisionError):
-        clock.tick(6)
+        clock.advance(6)
     assert p_list == []
     assert task.cancelled
 
@@ -103,15 +103,15 @@ async def async_fn():
 
     task = start(async_fn())
     assert values == []
-    clock.tick(10)
+    clock.advance(10)
     assert values == [10, 10] ; values.clear()
-    clock.tick(20)
+    clock.advance(20)
     assert values == [20, 30] ; values.clear()
-    clock.tick(5)
+    clock.advance(5)
     assert values == [5, 35] ; values.clear()
-    clock.tick(5)
+    clock.advance(5)
     assert values == [5, 40] ; values.clear()
-    clock.tick(5)
+    clock.advance(5)
     assert values == []
     assert not task.finished
     task.cancel()
@@ -130,25 +130,25 @@ async def async_fn():
 
     task = start(async_fn())
     assert values == []
-    clock.tick(10)
+    clock.advance(10)
     assert values[:2] == [10, 10]
     assert values[2] == approx(0.1)
     values.clear()
-    clock.tick(20)
+    clock.advance(20)
     assert values[:2] == [20, 30]
     assert values[2] == approx(0.3)
     values.clear()
-    clock.tick(5)
+    clock.advance(5)
     assert values[:2] == [5, 35]
     assert values[2] == approx(0.35)
     values.clear()
-    clock.tick(5)
+    clock.advance(5)
     assert values[:2] == [5, 40]
     assert values[2] == approx(0.4)
     values.clear()
-    clock.tick(5)
+    clock.advance(5)
     assert values == []
-    clock.tick(105)
+    clock.advance(105)
     assert values[:2] == [110, 150]
     assert values[2] == approx(1.5)
     assert task.finished
@@ -164,9 +164,9 @@ async def async_fn():
 
     task = start(async_fn())
     assert values == []
-    clock.tick(6)
+    clock.advance(6)
     assert values == []
     with pytest.raises(ZeroDivisionError):
-        clock.tick(6)
+        clock.advance(6)
     assert values == []
     assert task.cancelled

tests/clock/test_etc.py

@@ -14,9 +14,9 @@ async def async_fn():
 
     task = start(async_fn())
     assert task_state == 'A'
-    clock.tick(10)
+    clock.advance(10)
     assert task_state == 'B'
-    clock.tick(10)
+    clock.advance(10)
     assert task_state == 'C'
     assert task.finished
 
@@ -37,9 +37,9 @@ async def async_fn():
 
     task = start(async_fn())
     assert task_state == 'A'
-    clock.tick(10)
+    clock.advance(10)
     assert task_state == 'B'
-    clock.tick(10)
+    clock.advance(10)
     assert task_state == 'B'
     assert task.finished
 
@@ -56,5 +56,5 @@ def test_n_frames(clock, n):
     task = start(clock.n_frames(n))
     for __ in range(n):
         assert not task.finished
-        clock.tick(0)
+        clock.advance(0)
     assert task.finished

tests/clock/test_interpolate_xxx.py

@@ -11,13 +11,13 @@ async def async_fn():
 
     task = start(async_fn())
     assert values == [100, ]
-    clock.tick(30)
+    clock.advance(30)
     assert values == [100, 70]
-    clock.tick(20)
+    clock.advance(20)
     assert values == [100, 70, 50, ]
-    clock.tick(40)
+    clock.advance(40)
     assert values == [100, 70, 50, 10, ]
-    clock.tick(40)
+    clock.advance(40)
     assert values == [100, 70, 50, 10, 0, ]
     assert task.finished
 
@@ -33,7 +33,7 @@ async def async_fn():
 
     task = start(async_fn())
     assert values == [100, ]
-    clock.tick(step)
+    clock.advance(step)
     assert values == [100, 0]
     assert task.finished
 
@@ -49,13 +49,13 @@ async def async_fn():
 
     task = start(async_fn())
     assert values == [0, 100] ; values.clear()
-    clock.tick(30)
+    clock.advance(30)
     assert values == [30, 70] ; values.clear()
-    clock.tick(30)
+    clock.advance(30)
     assert values == [60, 40] ; values.clear()
-    clock.tick(30)
+    clock.advance(30)
     assert values == [90, 10] ; values.clear()
-    clock.tick(30)
+    clock.advance(30)
     assert values == [100, 0] ; values.clear()
     assert task.finished
 
@@ -72,6 +72,6 @@ async def async_fn():
 
     task = start(async_fn())
     assert values == [0, 100] ; values.clear()
-    clock.tick(step)
+    clock.advance(step)
     assert values == [100, 0] ; values.clear()
     assert task.finished