async/await型のAPIを全て非メンバ関数にする

.github/workflows/python-package.yml

@@ -10,13 +10,11 @@ on:
     branches: [ main ]
 
 jobs:
-  pygame:
+  noname:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.10', '3.11']
-    env:
-      SDL_VIDEODRIVER: dummy
+        python-version: ['3.10', '3.11', '3.12']
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}

README.md

@@ -1,6 +1,9 @@
 # Clock
 
-An event scheduler.
+*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
@@ -13,34 +16,35 @@ 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, and the callback function will be called.
+# The clock advanced by a total of 20 time units.
+# The callback function will be called.
 clock.tick(10)  # => Hello
 ```
 
-It also supports async-style APIs. The code below does the same thing as the previous one but in an async-style.
+Next one is async/await-style code that involves `asyncgui`, and does the same thing as the previous.
 
 ```python
 import asyncgui
-from asyncgui_ext.clock import Clock
+from asyncgui_ext.clock import Clock, sleep
 
 clock = Clock()
 
-async def main():
-    await clock.sleep(20)
+async def async_fn():
+    await sleep(clock, 20)
     print("Hello")
 
-asyncgui.start(main())
+asyncgui.start(async_fn())
 clock.tick(10)
 clock.tick(10)  # => Hello
 ```
 
-The two examples above effectively illustrate how this module works, but they are not practical.
+These two examples effectively illustrate how this module works but they are 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 want to do:
+For example, if you are using `PyGame`, you may want to do:
 
 ```python
 clock = pygame.time.Clock()
-vclock = asyncui_ext.clock.Clock()
+vclock = asyncgui_ext.clock.Clock()
 
 # main loop
 while running:
@@ -50,26 +54,29 @@ while running:
     vclock.tick(dt)
 ```
 
-And if you are using `Kivy`, you want to do:
+And if you are using `Kivy`, you may want to do:
 
 ```python
 from kivy.clock import Clock
-vclock = asyncui_ext.clock.Clock()
 
+vclock = asyncui_ext.clock.Clock()
 Clock.schedule_interval(vclock.tick, 0)
 ```
 
 ## Installation
 
+Pin the minor version.
+
 ```
-poetry add asyncgui-ext-clock@~0.1
-pip install "asyncgui-ext-clock>=0.1,<0.2"
+poetry add asyncgui-ext-clock@~0.2
+pip install "asyncgui-ext-clock>=0.2,<0.3"
 ```
 
 ## Tested on
 
 - CPython 3.10
 - CPython 3.11
+- CPython 3.12
 
 ## Misc
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "asyncgui-ext-clock"
-version = "0.1.1.dev0"
+version = "0.2.0"
 description = ""
 authors = ["Nattōsai Mitō <[email protected]>"]
 license = "MIT"
@@ -15,6 +15,7 @@ classifiers=[
     'Programming Language :: Python',
     'Programming Language :: Python :: 3.10',
     'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
     'Topic :: Software Development :: Libraries',
     'Operating System :: OS Independent',
 ]

sphinx/conf.py

@@ -87,23 +87,8 @@ def modify_signature(app, what: str, name: str, obj, options, signature, return_
     if name in group1:
         print(f"Hide the signature of {name!r}")
         return ('', None)
-    if name.startswith("Transition."):
-        return ('(p)', None)
     return (signature, return_annotation, )
 
 
-def modify_docstring(app, what, name, obj, options, lines,
-                     prefix="asyncgui_ext.clock.", len_prefix=len("asyncgui_ext.clock."),
-                     group1={'ClockEvent', },
-                     ):
-    if not name.startswith(prefix):
-        return
-    name = name[len_prefix:]
-    if name.startswith("Transition."):
-        name = name[len("Transition."):]
-        lines.append(f".. image:: images/transition/{name}.png")
-
-
 def setup(app):
     app.connect('autodoc-process-signature', modify_signature)
-    app.connect('autodoc-process-docstring', modify_docstring)

sphinx/index.rst

@@ -1,9 +1,9 @@
-=============
-API Reference
-=============
+==========================
+Clock (AsyncGui Extension)
+==========================
 
+.. toctree::
+   :hidden:
 
-.. automodule:: asyncgui_ext.clock
-    :members:
-    :undoc-members:
-    :exclude-members:
+   readme_jp
+   reference

sphinx/readme_jp.rst

@@ -0,0 +1,94 @@
+===========
+ReadMe |ja|
+===========
+
+このモジュールは :mod:`asyncgui` を用いるプログラム向けのタイマー機能を提供します。
+機能は大別すると :class:`Clock` とその他になり、それぞれ以下の特徴を持ちます。
+
+* ``Clock`` ... コールバック型のAPIで ``asyncgui`` の用いないプログラムからも利用できる。
+* その他 ... async/await型のAPIで ``asyncgui`` を用いるプログラムからのみ利用できる。
+
+まずはコールバック型の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型のAPIを用いた以下のコードを見てください。
+
+.. code-block::
+
+    import asyncgui
+    from asyncgui_ext.clock import Clock, sleep
+
+    clock = Clock()
+
+    async def async_fn():
+        await sleep(clock, 20)
+        print("Hello")
+
+    asyncgui.start(async_fn())
+    clock.tick(10)
+    clock.tick(10)  # => Hello
+
+この様に ``clock.tick()`` を呼ぶ事で時計内部の時が進み、関数が呼ばれたり停止中のタスクが再開するわけです。
+しかしこれらの例はこのモジュールの仕組みを示しているだけであまり実用的ではありません。
+実際のプログラムでは ``clock.tick()`` をループ内で呼んだり別のタイマーを用いて定期的に呼ぶ事になると思います。
+例えば ``PyGame`` を使っているなら以下のように、
+
+.. code-block::
+
+    clock = pygame.time.Clock()
+    vclock = asyncgui_ext.clock.Clock()
+
+    # メインループ
+    while running:
+        ...
+
+        dt = clock.tick(fps)
+        vclock.tick(dt)
+
+``Kivy`` を使っているなら以下のようになると思います。
+
+.. code-block::
+
+    from kivy.clock import Clock
+
+    vclock = asyncui_ext.clock.Clock()
+    Clock.schedule_interval(vclock.tick, 0)
+
+インストール方法
+-----------------------
+
+マイナーバージョンまでを固定してください。
+
+::
+
+    poetry add asyncgui-ext-clock@~0.2
+    pip install "asyncgui-ext-clock>=0.2,<0.3"
+
+テスト環境
+-----------------------
+
+* CPython 3.10
+* CPython 3.11
+* CPython 3.12
+
+その他
+-----------------------
+
+* [YouTube](https://youtu.be/kPVzO8fF0yg) (Kivy上で使う例)

sphinx/reference.rst

@@ -0,0 +1,9 @@
+=============
+API Reference
+=============
+
+
+.. automodule:: asyncgui_ext.clock
+    :members:
+    :undoc-members:
+    :exclude-members: