hupper

Warnings

• breaking Version 1.11 dropped support for Python 2.7, 3.4, 3.5, and 3.6. Ensure your environment is Python 3.7 or newer.
  Fix: Upgrade your Python environment to 3.7+ before upgrading hupper to 1.11 or later.
• gotcha The `reload_interval` parameter, which controls how often the filesystem is scanned, must be set to a value greater than 0. Setting it to 0 or less could cause needless CPU spinning and is explicitly disallowed since version 1.11. The default is 1 second.
  Fix: Always ensure `reload_interval` is a positive integer or omit it to use the default.
• gotcha Prior to version 1.10, hupper's handling of SIGTERM signals could be problematic, especially in containerized environments like Docker. It would immediately shut down, potentially stranding the worker process.
  Fix: Upgrade to hupper 1.10 or later to benefit from improved SIGTERM handling, which gracefully forwards the signal to the child process.
• gotcha The `hupper.start_reloader()` function behaves differently based on whether it's called from the parent (monitor) process or a child (worker) process. When called initially from the parent, it forks a new worker, starts the monitor, and *never returns* in the parent process. When called from a worker process, it returns an `IReloaderProxy` instance to communicate with the monitor.
  Fix: Design your application's entry point to account for this dual behavior, typically by checking `os.environ.get('HUPPER_RELOADER')` or by structuring your `main` function as shown in the quickstart.
• gotcha You can override hupper's default file monitor (which auto-selects between `watchdog` and `polling`) by setting the `HUPPER_DEFAULT_MONITOR` environment variable to a dotted Python path of an `IFileMonitorFactory` implementation (e.g., `hupper.polling.PollingFileMonitor`).
  Fix: Set the `HUPPER_DEFAULT_MONITOR` environment variable (e.g., `export HUPPER_DEFAULT_MONITOR=hupper.polling.PollingFileMonitor`) before running your hupper-monitored application if you need to force a specific monitoring mechanism.

Install

• pip install hupper Install stable release

Imports

• start_reloader

  from hupper import start_reloader

• is_active

  from hupper import is_active

• get_reloader

  from hupper import get_reloader

Quickstart

To use hupper, define your application's entry point as a callable function. Call `hupper.start_reloader()` from your main script, passing the dotted path to this entry point. `hupper` will then fork a worker process to run your application and monitor for file changes. If changes are detected, the worker process will be restarted. The `HUPPER_RELOADER` environment variable distinguishes between the monitor and worker processes internally. Running the script and then modifying `my_app.py` will demonstrate the reload functionality.

import hupper
import os
import datetime
import time

def worker_func():
    """This function contains the main application logic, re-executed on reload."""
    now = datetime.datetime.now()
    print(f"Worker process active at {now}. Edit 'my_app.py' to trigger reload.")
    # In a real application, this would be your main application loop
    # (e.g., a web server, a background task). For this example, we just
    # sleep briefly to demonstrate the worker's lifecycle.
    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        print("Worker received KeyboardInterrupt, shutting down.")

def main():
    if os.environ.get('HUPPER_RELOADER') != 'true':
        # This code runs in the *monitor* process
        print("Monitor: Starting reloader for 'my_app.worker_func'...")
        # The first call to start_reloader from the main process
        # forks a worker, starts monitoring, and never returns in this process.
        reloader = hupper.start_reloader('my_app.worker_func')
        # Optional: Watch additional files/directories
        # reloader.watch_files(['./config.ini'])
        print("Monitor: Reloader stopped.") # This line is usually not reached
    else:
        # This code runs in the *worker* process, after being forked by the monitor
        print("Worker: This is a reloaded worker process.")
        worker_func()

if __name__ == '__main__':
    main()