Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 3, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions .github/workflows/python-package.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}
Expand Down
35 changes: 21 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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:
Expand All @@ -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

Expand Down
3 changes: 2 additions & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -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',
]
Expand Down
15 changes: 0 additions & 15 deletions sphinx/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
14 changes: 7 additions & 7 deletions sphinx/index.rst
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
=============
API Reference
=============
==========================
Clock (AsyncGui Extension)
==========================

.. toctree::
:hidden:

.. automodule:: asyncgui_ext.clock
:members:
:undoc-members:
:exclude-members:
readme_jp
reference
94 changes: 94 additions & 0 deletions sphinx/readme_jp.rst
Original file line number Diff line number Diff line change
@@ -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上で使う例)
9 changes: 9 additions & 0 deletions sphinx/reference.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
=============
API Reference
=============


.. automodule:: asyncgui_ext.clock
:members:
:undoc-members:
:exclude-members:
Loading
Loading