hupper API

hupper.start_reloader(worker_path, reload_interval=1, shutdown_interval=<default>, verbose=1, logger=None, monitor_factory=None, worker_args=None, worker_kwargs=None, ignore_files=None)[source]

Start a monitor and then fork a worker process which starts by executing the importable function at worker_path.

If this function is called from a worker process that is already being monitored then it will return a reference to the current hupper.interfaces.IReloaderProxy which can be used to communicate with the monitor.

worker_path must be a dotted string pointing to a globally importable function that will be executed to start the worker. An example could be myapp.cli.main. In most cases it will point at the same function that is invoking start_reloader in the first place.

reload_interval is a value in seconds and will be used to throttle restarts. Default is 1.

shutdown_interval is a value in seconds and will be used to trigger a graceful shutdown of the server. Set to None to disable the graceful shutdown. Default is the same as reload_interval.

verbose controls the output. Set to 0 to turn off any logging of activity and turn up to 2 for extra output. Default is 1.

logger, if supplied, supersedes verbose and should be an object implementing hupper.interfaces.ILogger.

monitor_factory is an instance of hupper.interfaces.IFileMonitorFactory. If left unspecified, this will try to create a hupper.watchdog.WatchdogFileMonitor if watchdog is installed and will fallback to the less efficient hupper.polling.PollingFileMonitor otherwise.

If monitor_factory is None it can be overridden by the HUPPER_DEFAULT_MONITOR environment variable. It should be a dotted python path pointing at an object implementing hupper.interfaces.IFileMonitorFactory.

ignore_files if provided must be an iterable of shell-style patterns to ignore.


Return True if the current process being monitored by a parent process.


Get a reference to the current hupper.interfaces.IReloaderProxy.

Raises a RuntimeError if the current process is not actively being monitored by a parent process.


Return True if watchdog is available.


Return True if watchman is available.

class hupper.reloader.Reloader(worker_path, monitor_factory, logger, reload_interval=1, shutdown_interval=1, worker_args=None, worker_kwargs=None, ignore_files=None)[source]

A wrapper class around a file monitor which will handle changes by restarting a new worker process.


Execute the reloader forever, blocking the current thread.

This will invoke sys.exit(1) if interrupted.


Execute the worker once.

This method will return after the worker exits.

class hupper.interfaces.IReloaderProxy[source]

Signal the monitor to execute a reload.


Signal to the monitor to track some custom paths.

class hupper.interfaces.IFileMonitor[source]

Start monitoring a new path.


Block until the monitor has stopped.


Start the monitor. This method should not block.


Trigger the monitor to stop.

This should be called before invoking join.

class hupper.interfaces.IFileMonitorFactory[source]
__call__(callback, **kw)[source]

Return an IFileMonitor instance.

callback is a callable to be invoked by the IFileMonitor when file changes are detected. It should accept the path of the changed file as its only parameter.

Extra keyword-only arguments:

interval is the value of reload_interval passed to the reloader and may be used to control behavior in the file monitor.

logger is an ILogger instance used to record runtime output.

class hupper.interfaces.ILogger[source]

Record a debug-only message.


Record an error message.


Record an informational message.

class hupper.polling.PollingFileMonitor(callback, interval=1, **kw)[source]

An hupper.interfaces.IFileMonitor that stats the files at periodic intervals.

callback is a callable that accepts a path to a changed file.

interval is a value in seconds between scans of the files on disk. Do not set this too low or it will eat your CPU and kill your drive.

class hupper.watchdog.WatchdogFileMonitor(callback, logger, **kw)[source]

An hupper.interfaces.IFileMonitor that uses watchdog to watch for file changes uses inotify.

callback is a callable that accepts a path to a changed file.

logger is an hupper.interfaces.ILogger instance.

class hupper.watchman.WatchmanFileMonitor(callback, logger, sockpath=None, binpath='watchman', timeout=1.0, **kw)[source]

An hupper.interfaces.IFileMonitor that uses Facebook’s watchman daemon to detect changes.

callback is a callable that accepts a path to a changed file.