How kivy-school/kivy-reloader works
Project Type and Purpose
• This is a developer tool built around the Kivy framework. Its main purpose is to “hot reload” Kivy apps in real-time on multiple devices (Android phones, emulators, desktops) so developers can see changes instantly without having to recompile every time.
• It integrates with build systems like Buildozer and supports configurations via a TOML file (kivy-reloader.toml) and even works within a Poetry-managed environment.
File Structure
• At the top level, you find configuration files (.gitignore, buildozer.spec, pyproject.toml) and key directories: “beautifulapp” (an example advanced Kivy app structure) and “kivy_reloader” (the core library modules).
• The “kivy_reloader” directory contains critical modules:
• app.py – which likely wraps and extends Kivy’s App functionality to enable hot reloading.
• bootstrap.py, compile_app.py, config.py, send_app_to_phone.py, and utils.py – these modules suggest responsibilities such as starting the application, compiling the app to an APK, reading configuration, linking to Android, and utility functions for file watching.
• Additionally, directories like “bin” contain pre-built APKs for quick testing. There is also a “beautifulapp” folder that demonstrates an advanced project structure with separate modules for screens (using Kivy’s language file .kv and Python screen definitions).
Key System Components
a. Core Library (Kivy Reloader):
• Components:
• App wrapper (kivy_reloader/app.py)
• Bootstrap and startup code (bootstrap.py)
• Compilation and deployment logic (compile_app.py, send_app_to_phone.py)
• Configuration handling (config.py)
• Utility functions (utils.py)
• These modules work together to monitor file changes (using a dependency like watchdog via Kaki) and trigger reloading on connected devices.
b. Client Application(s):
• The “beautifulapp” directory exemplifies an advanced Kivy application structure that uses the reloader. It includes:
• The Main App definition (in __init__.py, which creates a MainApp subclass extending the Kivy Reloader App)
• Screens (with separate KV and Python files that define UI layout and logic)
• The “main.py” at the root level (and similarly the one inside beautifulapp) serves as the entry point where the app is initialized and run.
c. Configuration & Build Layer:
• The “kivy-reloader.toml” file for configuring watched files/folders, the IP addresses for phones, and hot reload settings.
• Buildozer spec files (at both the root and within the kivy_reloader directory) for building the Android APK.
• The CLI commands and scripts that facilitate running commands such as “kivy-reloader run” which handle app compilation, deployment, and starting a scrcpy mirror.
Relationships and Data Flow
• The entry point (main.py) initializes the MainApp which is defined in either the “beautifulapp” folder or the core library.
• Once running, the app monitors file system changes as specified in “kivy-reloader.toml”. When a change is detected (using the underlying “watchdog” mechanism integrated via Kaki), the Kivy Reloader’s utility functions trigger a live reload.
• For Android and other device targets, the buildozer configuration is used to compile and deploy the updated APKs.
• External tools (ADB, scrcpy) are used to interact with connected devices, showing mirrored logs and interfaces.
Architectural Patterns and Design Principles
• Modular design: The project cleanly separates the developer tool’s core functionality (in the “kivy_reloader” directory) from the example client app (“beautifulapp”).
• Configuration-driven behavior: The use of a TOML configuration file lets you control which directories/files trigger a reload.
• Event-driven design: The hot reload mechanism is reactive – file changes trigger events that cause the app’s state to update in real time.
• Encapsulation of platform-specific tasks: The build and deployment logic is abstracted behind the utility modules and buildozer spec files.
Elements
• Each major component should be clearly labeled (e.g., “Configuration Module”, “File Watcher & Reload Engine”, “Compilation & Deployment Module”, “Client Kivy App”).
• Initialization flow from main.py to MainApp.
• Data flow from file watcher → configuration check → reload trigger.
• Build and deployment flow from compilation module to device (APK deployment via ADB and mirroring via scrcpy).
• Annotations that mention the use of external libraries and frameworks (e.g., Kivy, Kaki, watchdog, Buildozer).
a. The Client-side: Represent the “beautifulapp” with its screens and UI logic.
b. The Core Tool: Represent the “kivy_reloader” directory modules.