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.

hupper.is_active()[source]

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

hupper.get_reloader()[source]

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.

hupper.is_watchdog_supported()[source]

Return True if watchdog is available.

hupper.is_watchman_supported()[source]

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.

run()[source]

Execute the reloader forever, blocking the current thread.

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

run_once()[source]

Execute the worker once.

This method will return after the worker exits.

class hupper.interfaces.IReloaderProxy[source]
trigger_reload()[source]

Signal the monitor to execute a reload.

watch_files(files)[source]

Signal to the monitor to track some custom paths.

class hupper.interfaces.IFileMonitor[source]
add_path(path)[source]

Start monitoring a new path.

join()[source]

Block until the monitor has stopped.

start()[source]

Start the monitor. This method should not block.

stop()[source]

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]
debug(msg)[source]

Record a debug-only message.

error(msg)[source]

Record an error message.

info(msg)[source]

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.