# AsyncKivy
[Youtube](https://www.youtube.com/playlist?list=PLNdhqAjzeEGjTpmvNck4Uykps8s9LmRTJ)
[日本語doc](README_jp.md)
`asynckivy` is an async library that saves you from ugly callback-style code,
like most of async libraries do.
Let's say you want to do:
1. `print('A')`
1. wait for 1sec
1. `print('B')`
1. wait for a button to be pressed
1. `print('C')`
in that order.
Your code would look like this:
```python
from kivy.clock import Clock
def what_you_want_to_do(button):
print('A')
def one_sec_later(__):
print('B')
button.bind(on_press=on_button_press)
Clock.schedule_once(one_sec_later, 1)
def on_button_press(button):
button.unbind(on_press=on_button_press)
print('C')
what_you_want_to_do(...)
```
It's not easy to understand.
If you use `asynckivy`, the above code will become:
```python
import asynckivy as ak
async def what_you_want_to_do(button):
print('A')
await ak.sleep(1)
print('B')
await ak.event(button, 'on_press')
print('C')
ak.start(what_you_want_to_do(...))
```
## Installation
It's recommended to pin the minor version, because if it changed, it means some *important* breaking changes occurred.
```text
poetry add asynckivy@~0.6
pip install "asynckivy>=0.6,<0.7"
```
## Usage
```python
import asynckivy as ak
async def some_task(button):
# waits for 1sec
dt = await ak.sleep(1)
print(f'{dt} seconds have passed')
# waits until a button is pressed
await ak.event(button, 'on_press')
# waits until 'button.x' changes
__, x = await ak.event(button, 'x')
print(f'button.x is now {x}')
# waits until 'button.x' becomes greater than 100
if button.x <= 100:
__, x = await ak.event(button, 'x', filter=lambda __, x: x>100)
print(f'button.x is now {x}')
# waits until EITHER a button is pressed OR 5sec passes.
# i.e. wait at most 5 seconds for a button to be pressed
tasks = await ak.wait_any(
ak.event(button, 'on_press'),
ak.sleep(5),
)
print("The button was pressed" if tasks[0].finished else "Timeout")
# same as the above
async with ak.move_on_after(5) as bg_task:
await ak.event(button, 'on_press')
print("Timeout" if bg_task.finished else "The button was pressed")
# waits until a button is pressed AND 5sec passes.
tasks = await ak.wait_all(
ak.event(button, 'on_press'),
ak.sleep(5),
)
# nest as you want.
# waits for a button to be pressed AND (5sec OR 'other_async_func' to complete)
tasks = await ak.wait_all(
ak.event(button, 'on_press'),
ak.wait_any(
ak.sleep(5),
other_async_func(),
),
)
child_tasks = tasks[1].result
print("5sec passed" if child_tasks[0].finished else "other_async_func has completed")
ak.start(some_task(some_button))
```
## Tested on
- CPython 3.8 + Kivy 2.3.0
- CPython 3.9 + Kivy 2.3.0
- CPython 3.10 + Kivy 2.3.0
- CPython 3.11 + Kivy 2.3.0
- CPython 3.12 + Kivy 2.3.0 (3.12.0 is not supported due to [this issue](https://github.com/python/cpython/issues/111058))
## Why this even exists
Kivy supports two legit async libraries, [asyncio][asyncio] and [Trio][trio], from version 2.0.0 so developing another one seems [reinventing the wheel][reinventing].
Actually, I started this one just for learning how async/await works so it *was* initially "reinventing the wheel".
But after playing with Trio and Kivy for a while, I noticed that Trio is not suitable for the situation where fast reactions are required e.g. touch events.
The same is true of asyncio.
You can confirm it by running `investigation/why_xxx_is_not_suitable_for_handling_touch_events.py`, and mashing a mouse button.
You'll see sometimes `up` is not paired with `down`.
You'll see the coordinates aren't relative to the `RelativeLayout` even though the `target` belongs to it.
The cause of those problems is that `trio.Event.set()` and `asyncio.Event.set()` don't *immediately* resume the tasks waiting for the `Event` to be set. They just schedule the tasks to resume.
Same thing can be said to `nursery.start_soon()` and `asyncio.create_task()`.
Trio and asyncio are async **I/O** libraries after all.
They probably don't have to immediately resumes/starts tasks, which I think necessary for Kivy's touch handling.
(If a touch is not handled immediately, its state may change).
Their core design might not be suitable for GUI in the first place.
That's why I'm still developing this `asynckivy` library to this day.
[asyncio]:https://docs.python.org/3/library/asyncio.html
[trio]:https://trio.readthedocs.io/en/stable/
[reinventing]:https://en.wikipedia.org/wiki/Reinventing_the_wheel
Raw data
{
"_id": null,
"home_page": "https://github.com/asyncgui/asynckivy",
"name": "asynckivy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0.0",
"maintainer_email": "",
"keywords": "async,kivy",
"author": "Natt\u014dsai Mit\u014d",
"author_email": "flow4re2c@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/83/82/937171e6747ff89c9a8c238dc200ca496a8d5d0cd03455eb145dec69cc38/asynckivy-0.6.2.tar.gz",
"platform": null,
"description": "# AsyncKivy\n\n[Youtube](https://www.youtube.com/playlist?list=PLNdhqAjzeEGjTpmvNck4Uykps8s9LmRTJ) \n[\u65e5\u672c\u8a9edoc](README_jp.md) \n\n`asynckivy` is an async library that saves you from ugly callback-style code,\nlike most of async libraries do.\nLet's say you want to do:\n\n1. `print('A')`\n1. wait for 1sec\n1. `print('B')`\n1. wait for a button to be pressed\n1. `print('C')`\n\nin that order.\nYour code would look like this:\n\n```python\nfrom kivy.clock import Clock\n\ndef what_you_want_to_do(button):\n print('A')\n\n def one_sec_later(__):\n print('B')\n button.bind(on_press=on_button_press)\n Clock.schedule_once(one_sec_later, 1)\n\n def on_button_press(button):\n button.unbind(on_press=on_button_press)\n print('C')\n\nwhat_you_want_to_do(...)\n```\n\nIt's not easy to understand.\nIf you use `asynckivy`, the above code will become:\n\n```python\nimport asynckivy as ak\n\nasync def what_you_want_to_do(button):\n print('A')\n await ak.sleep(1)\n print('B')\n await ak.event(button, 'on_press')\n print('C')\n\nak.start(what_you_want_to_do(...))\n```\n\n## Installation\n\nIt's recommended to pin the minor version, because if it changed, it means some *important* breaking changes occurred.\n\n```text\npoetry add asynckivy@~0.6\npip install \"asynckivy>=0.6,<0.7\"\n```\n\n## Usage\n\n```python\nimport asynckivy as ak\n\nasync def some_task(button):\n # waits for 1sec\n dt = await ak.sleep(1)\n print(f'{dt} seconds have passed')\n\n # waits until a button is pressed\n await ak.event(button, 'on_press')\n\n # waits until 'button.x' changes\n __, x = await ak.event(button, 'x')\n print(f'button.x is now {x}')\n\n # waits until 'button.x' becomes greater than 100\n if button.x <= 100:\n __, x = await ak.event(button, 'x', filter=lambda __, x: x>100)\n print(f'button.x is now {x}')\n\n # waits until EITHER a button is pressed OR 5sec passes.\n # i.e. wait at most 5 seconds for a button to be pressed\n tasks = await ak.wait_any(\n ak.event(button, 'on_press'),\n ak.sleep(5),\n )\n print(\"The button was pressed\" if tasks[0].finished else \"Timeout\")\n\n # same as the above\n async with ak.move_on_after(5) as bg_task:\n await ak.event(button, 'on_press')\n print(\"Timeout\" if bg_task.finished else \"The button was pressed\")\n\n # waits until a button is pressed AND 5sec passes.\n tasks = await ak.wait_all(\n ak.event(button, 'on_press'),\n ak.sleep(5),\n )\n\n # nest as you want.\n # waits for a button to be pressed AND (5sec OR 'other_async_func' to complete)\n tasks = await ak.wait_all(\n ak.event(button, 'on_press'),\n ak.wait_any(\n ak.sleep(5),\n other_async_func(),\n ),\n )\n child_tasks = tasks[1].result\n print(\"5sec passed\" if child_tasks[0].finished else \"other_async_func has completed\")\n\nak.start(some_task(some_button))\n```\n\n## Tested on\n\n- CPython 3.8 + Kivy 2.3.0\n- CPython 3.9 + Kivy 2.3.0\n- CPython 3.10 + Kivy 2.3.0\n- CPython 3.11 + Kivy 2.3.0\n- CPython 3.12 + Kivy 2.3.0 (3.12.0 is not supported due to [this issue](https://github.com/python/cpython/issues/111058))\n\n## Why this even exists\n\nKivy supports two legit async libraries, [asyncio][asyncio] and [Trio][trio], from version 2.0.0 so developing another one seems [reinventing the wheel][reinventing].\nActually, I started this one just for learning how async/await works so it *was* initially \"reinventing the wheel\".\n\nBut after playing with Trio and Kivy for a while, I noticed that Trio is not suitable for the situation where fast reactions are required e.g. touch events.\nThe same is true of asyncio.\nYou can confirm it by running `investigation/why_xxx_is_not_suitable_for_handling_touch_events.py`, and mashing a mouse button.\nYou'll see sometimes `up` is not paired with `down`.\nYou'll see the coordinates aren't relative to the `RelativeLayout` even though the `target` belongs to it.\n\nThe cause of those problems is that `trio.Event.set()` and `asyncio.Event.set()` don't *immediately* resume the tasks waiting for the `Event` to be set. They just schedule the tasks to resume.\nSame thing can be said to `nursery.start_soon()` and `asyncio.create_task()`.\n\nTrio and asyncio are async **I/O** libraries after all.\nThey probably don't have to immediately resumes/starts tasks, which I think necessary for Kivy's touch handling.\n(If a touch is not handled immediately, its state may change).\nTheir core design might not be suitable for GUI in the first place.\nThat's why I'm still developing this `asynckivy` library to this day.\n\n[asyncio]:https://docs.python.org/3/library/asyncio.html\n[trio]:https://trio.readthedocs.io/en/stable/\n[reinventing]:https://en.wikipedia.org/wiki/Reinventing_the_wheel\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Async library for Kivy",
"version": "0.6.2",
"project_urls": {
"Homepage": "https://github.com/asyncgui/asynckivy",
"Repository": "https://github.com/asyncgui/asynckivy"
},
"split_keywords": [
"async",
"kivy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d79a2f7f5069f8f6341fd05e9aab40962bbba14e884a65dbeeba509e5a9aeaca",
"md5": "fc7234ba5018dd998e6621831b64c855",
"sha256": "d643e5751c87b7573327842e527ccdafdd763ae4446fdacb29b2d800219cf64b"
},
"downloads": -1,
"filename": "asynckivy-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc7234ba5018dd998e6621831b64c855",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0.0",
"size": 18600,
"upload_time": "2024-01-27T10:02:08",
"upload_time_iso_8601": "2024-01-27T10:02:08.912829Z",
"url": "https://files.pythonhosted.org/packages/d7/9a/2f7f5069f8f6341fd05e9aab40962bbba14e884a65dbeeba509e5a9aeaca/asynckivy-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8382937171e6747ff89c9a8c238dc200ca496a8d5d0cd03455eb145dec69cc38",
"md5": "97be8378536d3a619d7249da64ba1eaf",
"sha256": "61c1ed6c82e3abfc57f19541412c2401a354c79e47079c7308c77377dbc828ec"
},
"downloads": -1,
"filename": "asynckivy-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "97be8378536d3a619d7249da64ba1eaf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0.0",
"size": 15576,
"upload_time": "2024-01-27T10:02:11",
"upload_time_iso_8601": "2024-01-27T10:02:11.012708Z",
"url": "https://files.pythonhosted.org/packages/83/82/937171e6747ff89c9a8c238dc200ca496a8d5d0cd03455eb145dec69cc38/asynckivy-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-27 10:02:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "asyncgui",
"github_project": "asynckivy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "asynckivy"
}
JSON
