Watch Mode

Real-time file watching for continuous feedback during development

Watch Mode

Watch mode provides real-time feedback during development by automatically re-running checks when files change. This creates a tight feedback loop that helps you catch issues immediately as you code.

Quick Start

Enable watch mode with the -w or --watch flag:

pycmdcheck check --watch

This will:

  1. Run all checks immediately
  2. Watch for file changes in the package directory
  3. Re-run checks automatically when files change
  4. Listen for interactive commands

How It Works

Watch mode monitors your package directory for changes to relevant files:

  • Included by default: *.py, *.toml, *.md
  • Excluded by default: *.pyc, __pycache__/*, .git/*

When a file change is detected, pycmdcheck waits briefly (debouncing) to coalesce rapid changes, then re-runs the configured checks.

Interactive Commands

While in watch mode, you can press keys to trigger actions:

Key Action
r Rerun all checks immediately
q Quit watch mode
f Set a filter to focus on specific checks
h Show help for available commands
Ctrl+C Stop watching

Using Filters

Press f to enter filter mode. You can filter by:

  • Check IDs: ST001,MT001,CQ002
  • Groups: structure,metadata
  • Mixed: ST001,structure,MT001
Commands: r=rerun, q=quit, f=filter, h=help

> f
Enter check IDs or groups to filter (comma-separated, empty to clear):
Examples: ST001,MT001 | structure,metadata | ST001,structure
> structure,ST001

Filter applied:
  Check IDs: ST001
  Groups: structure

Enter an empty filter to clear and run all checks again.

Usage Examples

Basic Watch Mode

# Watch current directory
pycmdcheck check --watch

# Watch a specific package
pycmdcheck check ./my-package --watch

Watch with Options

All check command options work with watch mode:

# Watch with verbose output
pycmdcheck check --watch --verbose

# Watch only structure checks
pycmdcheck check --watch --only-group structure

# Watch with a profile
pycmdcheck check --watch --profile relaxed

# Watch with parallel execution
pycmdcheck check --watch --parallel

Watch with Caching

Watch mode works well with caching for faster re-runs:

# Watch with caching enabled (default)
pycmdcheck check --watch

# Watch with incremental checking
pycmdcheck check --watch --incremental

Output During Watch

When files change, you’ll see output like:

Watching for changes...
Commands: r=rerun, q=quit, f=filter, h=help

Changes detected, re-running checks...

Structure (3 checks)
  [PASS] ST001 HasReadme - README file exists
  [PASS] ST002 HasLicense - LICENSE file exists
  [PASS] ST003 HasPyproject - pyproject.toml exists

Summary: 3 passed, 0 failed

Watching for changes...
Filter: none (running all checks)
Commands: r=rerun, q=quit, f=filter, h=help

Combining with Other Features

Watch + Fix Mode

While you can’t use --fix in watch mode directly, a common workflow is:

  1. Run watch mode to identify issues
  2. Press q to quit
  3. Run pycmdcheck check --fix to fix issues
  4. Return to watch mode

Watch + Baseline

Use a baseline to focus on new issues:

# Generate baseline from current state
pycmdcheck check --generate-baseline baseline.json

# Watch mode with baseline
pycmdcheck check --watch --baseline baseline.json

Watch + Profile

Apply a profile for consistent checking:

# Use relaxed profile during development
pycmdcheck check --watch --profile relaxed

# Use strict profile for final validation
pycmdcheck check --watch --profile strict

Configuration

Watch mode behavior can be customized through the WatchConfig class when using the Python API:

from pycmdcheck.watch import FileWatcher, WatchConfig

config = WatchConfig(
    debounce_seconds=0.5,  # Wait time before triggering (default: 0.5)
    include_patterns=["*.py", "*.toml", "*.md"],  # Files to watch
    exclude_patterns=["*.pyc", "__pycache__/*", ".git/*"],  # Files to ignore
)

Debouncing

The debounce setting prevents rapid re-runs when multiple files change in quick succession (e.g., during a git checkout or IDE save-all). The default is 0.5 seconds.

File Patterns

You can customize which files trigger re-runs:

  • Include patterns: Glob patterns for files to watch
  • Exclude patterns: Glob patterns for files to ignore

Exclude patterns are checked first, so a file matching both include and exclude patterns will be ignored.

Python API

For programmatic use:

from pathlib import Path
from pycmdcheck.watch import FileWatcher, InteractiveWatcher, WatchConfig

# Simple file watcher
def on_change():
    print("Files changed!")

watcher = FileWatcher(
    path=Path("./my-package"),
    on_change=on_change,
)
watcher.start()  # Blocks until watcher.stop() is called

# Interactive watcher with commands
from pycmdcheck.watch import WatchCommand

def on_command(cmd: WatchCommand):
    if cmd == WatchCommand.QUIT:
        watcher.stop()
    elif cmd == WatchCommand.RERUN:
        print("Manual rerun requested")

watcher = InteractiveWatcher(
    path=Path("./my-package"),
    on_change=on_change,
    on_command=on_command,
)
watcher.start()

Tips

  1. Start with verbose mode (--verbose) to see all checks, then use filters to focus on failures

  2. Use filters liberally - when fixing a specific issue, filter to just that check for faster feedback

  3. Combine with incremental mode (--incremental) for large packages to only re-check modified files

  4. Keep a terminal visible while coding to catch issues immediately

  5. Use profiles to match your current development phase (relaxed for early development, strict for final polish)