New in version 1.0.0.

Hot reload tool - is a fork of the project


Since the project is not developing, we decided to include it in the KivvMD library and hope that the further development of the hot reload tool in the KivyMD project will develop faster.

This library enhance Kivy frameworks with opiniated features such as:

  • Auto reloading kv or py (watchdog required, limited to some uses cases);

  • Idle detection support;

  • Foreground lock (Windows OS only);



See create project with hot reload for more information.


  • Add automatic reloading of Python classes;

  • Add save application state on reloading;


  • On Windows, hot reloading of Python files may not work;

API - = True#

Base handler that catches exceptions in runTouchApp(). You can subclass and extend it as follows:

class E(ExceptionHandler):
    def handle_exception(self, inst):
        Logger.exception('Exception caught by ExceptionHandler')
        return ExceptionManager.PASS


Then, all exceptions will be set to PASS, and logged to the console!

handle_exception(self, inst)#

Called by ExceptionManagerBase to handle a exception.

Defaults to returning ExceptionManager.RAISE that re-raises the exception. Return ExceptionManager.PASS to indicate that the exception was handled and should be ignored.

This may be called multiple times with the same exception, if ExceptionManager.RAISE is returned as the exception bubbles through multiple kivy exception handling levels.


HotReload Application class.


Control either we activate debugging in the app or not. Defaults depend if ‘DEBUG’ exists in os.environ.

DEBUG is a BooleanProperty.


If True it will require the foreground lock on windows.

FOREGROUND_LOCK is a BooleanProperty and defaults to False.


List of KV files under management for auto reloader.

KV_FILES is a ListProperty and defaults to [].


List of managed KV directories for autoloader.

KV_DIRS is a ListProperty and defaults to [].


List of path to watch for auto reloading.

AUTORELOADER_PATHS is a ListProperty and defaults to ([(“.”, {“recursive”: True})].


List of extensions to ignore.

AUTORELOADER_IGNORE_PATTERNS is a ListProperty and defaults to [‘*.pyc’, ‘*__pycache__*’].


Factory classes managed by hotreload.

CLASSES is a DictProperty and defaults to {}.


Idle detection (if True, event on_idle/on_wakeup will be fired). Rearming idle can also be done with rearm_idle().

IDLE_DETECTION is a BooleanProperty and defaults to False.


Default idle timeout.

IDLE_TIMEOUT is a NumericProperty and defaults to 60.


Raise error. When the DEBUG is activated, it will raise any error instead of showing it on the screen. If you still want to show the error when not in DEBUG, put this to False.

RAISE_ERROR is a BooleanProperty and defaults to True.


Initializes the application; it will be called only once. If this method returns a widget (tree), it will be used as the root widget and added to the window.


None or a root Widget instance if no self.root exists.


Return a root widget, that will contains your application. It should not be your application widget itself, as it may be destroyed and recreated from scratch when reloading.

By default, it returns a RelativeLayout, but it could be a Viewport.


Return the root file path.

abstract build_app(self, first=False)#

Must return your application widget.

If first is set, it means that will be your first time ever that the application is built. Act according to it.


Called when all the application dependencies must be unloaded. Usually happen before a reload


Load all the application dependencies. This is called before rebuild.

rebuild(self, *args, **kwargs)#
set_error(self, exc, tb=None)#
bind_key(self, key, callback)#

Bind a key (keycode) to a callback (cannot be unbind).


Enable autoreload manually. It is activated automatically if “DEBUG” exists in environ. It requires the watchdog module.


Try forcing app to front permanently to avoid windows pop ups and notifications

Requires fake full screen and borderless.


This function is called automatically if FOREGROUND_LOCK is set

set_widget(self, wid)#

Clear the root container, and set the new approot widget to wid.

apply_state(self, state)#

Whatever the current state is, reapply the current state.

install_idle(self, timeout=60)#

Install the idle detector. Default timeout is 60s. Once installed, it will check every second if the idle timer expired. The timer can be rearm using rearm_idle().

rearm_idle(self, *args)#

Rearm the idle timer.

on_idle(self, *args)#

Event fired when the application enter the idle mode.

on_wakeup(self, *args)#

Event fired when the application leaves idle mode.