tessl/pypi-watchfiles

Simple, modern and high performance file watching and code reload in python.

Overview

Eval results

Files

CLI Interface

Name: tessl/pypi-watchfiles
Author: tessl

Command-line interface for watching files and running commands or Python functions when changes are detected. The CLI provides a convenient way to use watchfiles without writing Python code.

Capabilities

Main CLI Function

Entry point for the watchfiles command-line interface that watches directories and executes targets on file changes.

def cli(*args_: str) -> None:
    """
    Watch one or more directories and execute either a shell command or a python function on file changes.

    Parameters:
    - *args_: Command line arguments, defaults to sys.argv[1:] if not provided

    Examples:
    - watchfiles foobar.main  # Watch current directory, call Python function
    - watchfiles --filter python 'pytest --lf' src tests  # Watch with filter
    """

Command Line Usage:

# Watch current directory and call a Python function
watchfiles my_module.main

# Watch specific directories with custom filter
watchfiles --filter python 'pytest --lf' src tests

# Run shell command on changes
watchfiles 'echo "Files changed!"' ./src

# Watch with custom ignore paths
watchfiles --ignore-paths "logs,tmp" 'python main.py' ./src

CLI Arguments

The CLI supports the following arguments:

Positional Arguments:

target - Command or dotted function path to run (required)
paths - Filesystem paths to watch (defaults to current directory)

Optional Arguments:

--filter - File filter type: all, python, or custom filter class path
--ignore-paths - Comma-separated list of paths to ignore
--extensions - Additional file extensions to watch (used with python filter)
--target-type - Target type: function, command, or auto (default)
--verbosity - Logging verbosity level
--version - Show version information

Filter Integration

The CLI integrates with the filtering system to control which file changes trigger actions.

Built-in Filters:

all - Watch all files (no filtering)
python - Watch only Python files (.py, .pyx, .pyd)
Custom filter class path - Import and use custom filter class

Filter Examples:

# Use default filter
watchfiles my_module.main ./src

# Watch all files (no filtering)
watchfiles --filter all my_module.main ./src

# Watch only Python files
watchfiles --filter python my_module.main ./src

# Use custom filter class
watchfiles --filter mypackage.filters.CustomFilter my_module.main ./src

# Python filter with additional extensions
watchfiles --filter python --extensions pyi,pyx my_module.main ./src

# Ignore specific paths
watchfiles --filter python --ignore-paths "logs,tmp,cache" my_module.main ./src

Utility Functions

Helper functions used by the CLI for path resolution and argument processing.

def resolve_path(path_str: str) -> Path:
    """
    Resolve a path string to an absolute Path object.

    Parameters:
    - path_str: String representation of the path

    Returns:
    Path: Resolved absolute path

    Raises:
    FileNotFoundError: If the path does not exist
    """

Target Type Detection

The CLI uses automatic target type detection when --target-type auto is specified (default).

Detection Logic:

If target is not a string → function
If target ends with .py or .sh → command
If target matches pattern [a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)+ → function
Otherwise → command

Examples:

# These are detected as functions
watchfiles my_module.main        # function (dotted path)
watchfiles mypackage.app.run     # function (dotted path)

# These are detected as commands
watchfiles 'python main.py'      # command (shell command)
watchfiles './script.sh'         # command (script file)
watchfiles main.py               # command (ends with .py)

# Override detection
watchfiles --target-type function 'my_module.main'  # force function
watchfiles --target-type command 'my_module.main'   # force command

Environment Integration

The CLI respects the same environment variables as the Python API:

WATCHFILES_FORCE_POLLING - Enable/disable force polling
WATCHFILES_POLL_DELAY_MS - Set polling delay in milliseconds
WATCHFILES_DEBUG - Enable debug output
WATCHFILES_IGNORE_PERMISSION_DENIED - Ignore permission denied errors
WATCHFILES_CHANGES - JSON string of changes (set automatically for targets)

Process Integration

The CLI internally uses the process management functionality to handle target execution:

Python functions are run using multiprocessing.Process with spawn context
Shell commands are run using subprocess.Popen
Signal handling (SIGINT/SIGTERM) for graceful shutdown
Process restarting on file changes with configurable timeouts

Exit Codes:

0 - Normal exit
1 - Error or KeyboardInterrupt
Other codes - Process-specific exit codes

Development Workflow Integration

The CLI is designed for common development workflows:

Testing Workflow:

# Run tests when Python files change
watchfiles --filter python 'pytest' tests/

# Run specific test on change
watchfiles --filter python 'pytest tests/test_specific.py -v' src/

Development Server:

# Restart development server on changes
watchfiles 'python manage.py runserver' src/

# Restart with custom settings
watchfiles 'python app.py --debug' src/ static/

Build Pipeline:

# Rebuild on source changes
watchfiles 'make build' src/

# Multiple build steps
watchfiles 'npm run build && python deploy.py' src/ assets/

Types

# Internal CLI types (not part of public API)
from pathlib import Path
from argparse import ArgumentParser

Install with Tessl CLI

npx tessl i tessl/pypi-watchfiles

docs

process-management.md

tile.json