asynckivy

0.10.0 verified Fri May 01 auth: no python

Async library for Kivy, providing async/await support for Kivy event loop, touch events, animations, and transitions. Current version 0.10.0 supports Python >=3.10 and <4.0. Released roughly every few months with occasional breaking changes as APIs are deprecated and removed.

pip install asynckivy

Common errors

error ImportError: cannot import name 'aiotKivyApp' from 'asynckivy' ↓

cause Old API was removed in version 0.7.0.

fix

Use from asynckivy import run_asynckivy or asynckivy.start.

error TypeError: object NoneType can't be used in 'await' expression ↓

cause Often due to passing a None widget to `event()`.

fix

Ensure the widget exists before awaiting event: await asynckivy.event(app.root, 'on_press') when root is not None.

error RuntimeError: Cannot schedule coroutine on a stopped event loop ↓

cause Trying to launch coroutines after the Kivy app has exited or the async loop is closed.

fix

Use managed_start to ensure tasks are cancelled on app stop.

error AttributeError: module 'asynckivy' has no attribute 'watch_touch' ↓

cause `watch_touch` was removed in version 0.8.0.

fix

Use rest_of_touch_events or event with 'on_touch_down'.

Warnings

breaking The `anim_with_xxx` APIs (except `anim_with_ratio`) are deprecated as of 0.9.1 and will be removed in a future version. Use the new `transition` submodule for animations. ↓

fix Replace `anim_with_xxx` calls with equivalent `asynckivy.transition` functions (e.g., `fade_in`, `slide`).

breaking In version 0.7.0, `anim_with_ratio` no longer ends on its own (was removed from auto-ending). You must explicitly cancel or await completion. ↓

fix Use `managed_start` or explicitly await the animation task with cancellation.

deprecated `fade_transition` (from the module) is deprecated as of 0.9.0; use `asynckivy.transition.fade` instead. ↓

fix Import `asynckivy.transition` and use `asynckivy.transition.fade(...)`.

gotcha `managed_start` is required to properly cancel tasks on app exit. Otherwise tasks may continue indefinitely. ↓

fix Use `managed_start` for task spawning (see quickstart).

breaking Python 3.9 support dropped in v0.9.1. asynckivy 0.10.0 requires Python >=3.10. ↓

fix Upgrade Python to 3.10 or later.

gotcha `event()` coroutine expects a widget and a single event name (string). Not the same as Kivy's `bind`; it waits for the event to fire once. ↓

fix Use `await asynckivy.event(widget, 'on_touch_down')` (not `bind`).

Imports

run_asynckivy
wrong
```
from asynckivy import aiotKivyApp
```
correct
```
from asynckivy import run_asynckivy
```
run_asynckivy is the main entry point to start the async Kivy event loop; old patterns are removed.
managed_start
wrong
```
from asynckivy import start
```
correct
```
from asynckivy import managed_start
```
start was removed in 0.7.x; managed_start must be used for managed task lifecycle.
event
```
from asynckivy import event
```
event is a coroutine function that waits for a Kivy event (e.g., button on_press).
rest_of_touch_events
wrong
```
from asynckivy import watch_touch
```
correct
```
from asynckivy import rest_of_touch_events
```
watch_touch was removed in 0.8.0; rest_of_touch_events is the replacement.
sleep
wrong
```
from asynckivy import aio_sleep
```
correct
```
from asynckivy import sleep
```
sleep is the async sleep function; aio_sleep was removed.

Quickstart

This example starts a Kivy app asynchronously and waits for a button press using the event() coroutine.

import asynckivy
from kivy.app import App
from kivy.uix.button import Button

class TestApp(App):
    def build(self):
        return Button(text='Click me')

async def main():
    app = TestApp()
    # Run the app asynchronously
    async with asynckivy.run_asynckivy(app):
        await asynckivy.event(app.root, 'on_press')
        print('Button was pressed!')

asynckivy.start(main())