foremon 1.3.0

Automatically restart applications when file changes are detected.

foremon

foremon is a tool to help develop python projects by executing build tasks when file changes are detected.

foremon intends to have feature parity to nodemon, a similar tool for the NodeJS ecosystem, but provide those features within a python toolchain. To use foremon run your script or module as foremon [script or module] or run foremon --help for advanced usage.

File monitoring is provided by watchdog which provides its own shell-utility, watchmedo.

foremon is currently in beta.

Installation

Clone foremon with git or install it using pip (recommended):

pip install foremon

Usage

foremon will bootstrap your module or script with the arguments you normally pass to it:

foremon [script or module or library:func] [args]

If your application uses options which conflict with foremon's options use the -- argument separator.

foremon -- mymodules --version

For CLI options --help:

foremon --help

Using foremon is simple. It will guess if you are running a module or python script and adjust command-line arguments and the PYTHONPATH accordingly. To disable this feature, add the -n (--no-guess) option.

# Executes `script.py`
foremon -n -- script.py

# Executes `python3 script.py`
foremon -- script.py

# Executes `python -m module` if module/__main__.py is present
foremon module

# Executes `python -c 'from lib import main; main()'` if only lib/__init__.py is present
foremon lib:main

# Execute `python -m module` and inserts `path/to` into PYTHONPATH
foremon path/to/module

foremon runs python scripts with the python interpreter of the environment it is installed in (sys.executable).

All foremon output is prefixed with [foremon] and written to stderr. Output from your script, errors included, will be echoed out as expected.

If no script is given, foremon will test for a pyproject.toml file and if found, will run scripts specified in the [tool.foremon] section (ref.).

Automatic re-running

When file changes are detected foremon will restart the script. If a script is running when the change is detected foremon will terminate the script before running it again.

foremon will wait a short period after changes are detected before restarting scripts. If a high volume of events are preventing a script from being restarted foremon will display a warning.

To control how long foremon waits use the -d/--dwell option. Dwell is a fractional number of seconds to wait and is set to 0.1 (100 milliseconds) by default.

Manual restart

Scripts may be manually restarted by typing rs and enter in the terminal where foremon is running. If a script is still running when rs is entered then foremon will terminate the script with a signal. By default SIGTERM is sent but the signal may be changed by setting term_signal in the config file.

foremon can also be shutdown gracefully by typing exit followed by enter. Just using ctrl+c has the same effect.

pyproject.toml

foremon supports pyproject.toml configuration files. If the project contains a pyproject.toml file foremon will automatically load defaults from the [tool.foremon] section. An alternative config file may be specified with the -f (--config-file) option.

All configuration settings are optional but foremon wont begin monitoring for changes if there are no scripts to run.

foremon will automatically reload the config file if it changes while foremon is running. Using the --no-reload option will disable this feature.

[tool.foremon]
# Only watch files ending in .py
patterns = ["*.py"]
# Run these scripts in-order on-change
scripts = ["pytest --cov=myproj"]
# Only run if explicitly run with `-a [alias]
skip = true
# Run script like they're in this directory
cwd = "./"
# Exit code to expect for a successful exit
returncode = 0
# Amount of time after an event is received and a script is restarted
dwell = 1.0
# Signal to send if the process should be terminated
term_signal = "SIGTERM"
# Set to false to turn on case-sensitive pattern matching
ignore_case = true
# List of default ignored paths like .git, or .tox
ignore_defaults = []
# Ignore changes to directories
ignore_dirs = true
# A list of patterns to ignore
ignore = ["*/build/*"]
# Paths to watch for changes
paths = ["src/"]
# Watch paths recursively
recursive = true
# List of events - created, deleted, moved, modified
events = ["created", "modified"]
# Environment overrides
[tool.foremon.environment]
TERM = "MONO"

All subsections contain the same options.

foremon supports multiple monitor and script definitions. Sections in the config file matching [tool.foremon.*], where * is the alias for the section, may be defined in addition to the default section.

To run these other sections specify the -a [alias] option. The -a option may be used multiple times or the --all option can be used to turn on all tasks.

[tool.foremon]
patterns = ["*.c", "*.h"]
scripts = ["./configure"]

  # Run me with 'foremon -a make'
  [tool.foremon.make]
  patterns = ["make*"]
  paths = ["src/*"]
  scripts = ["make -C src"]
  events = ["created"]

  [tool.foremon.other]
  scripts = ["echo skipped"]
  skip = true

Any command-line arguments passed to foremon only supersede definitions in default section.

Refer to the configuration samples for more examples of configuring foremon.