Module

server.build_handler

File system event handler for automatic site rebuilds.

Watches for file changes and triggers incremental rebuilds with debouncing.

View source
1 Class

Classes

BuildHandler
File system event handler that triggers site rebuild with debouncing. Dev reload policy (source-ga…
10

File system event handler that triggers site rebuild with debouncing.

Dev reload policy (source-gated):

  • Only source edits (markdown/content, config, templates, theme assets) trigger reloads.
  • CSS-only source edits send reload-css; any other source edits send full reload.
  • We do NOT scan output directories for diffs in dev; this avoids dev-only churn (timestamps, site-wide JSON/TXT) from causing spurious reloads.

Features:

  • Debounced rebuilds (0.3s delay to batch changes)
  • Incremental builds for speed (5-10x faster)
  • Parallel rendering
  • Stale object reference prevention (clears ephemeral state)
  • Build error recovery (errors don't crash server)
  • Automatic cache invalidation for config/template changes
  • Handles all file events: create, modify, delete, move/rename

Ignored files:

  • Output directory (public/)
  • Bengal state directory (.bengal/) - logs, cache, metrics
  • Temp files (.tmp, ~, .swp, .swo)
  • System files (.DS_Store, .git)
  • Python cache (pycache, .pyc)
Inherits from FileSystemEventHandler

Methods 4

on_created
Handle file creation events.
1 None 
def on_created(self, event: FileSystemEvent) -> None

Handle file creation events.

Parameters 1
event FileSystemEvent

File system event
on_modified
Handle file modification events.
1 None 
def on_modified(self, event: FileSystemEvent) -> None

Handle file modification events.

Parameters 1
event FileSystemEvent

File system event
on_deleted
Handle file deletion events.
1 None 
def on_deleted(self, event: FileSystemEvent) -> None

Handle file deletion events.

Parameters 1
event FileSystemEvent

File system event
on_moved
Handle file move/rename events.
1 None 
def on_moved(self, event: FileSystemEvent) -> None

Handle file move/rename events.

Parameters 1
event FileSystemEvent

File system event with src_path and dest_path
Internal Methods 6
__init__
Initialize the build handler.
3 None 
def __init__(self, site: Any, host: str = 'localhost', port: int = 5173) -> None

Initialize the build handler.

Parameters 3
site Any

Site instance
host str

Server host
port int

Server port
_clear_ephemeral_state
Clear ephemeral state safely via Site API.
0 None 
def _clear_ephemeral_state(self) -> None

Clear ephemeral state safely via Site API.

_should_regenerate_autodoc
Check if any changed file is in autodoc source directories.
1 bool 
def _should_regenerate_autodoc(self, changed_paths: set[str]) -> bool

Check if any changed file is in autodoc source directories.

Parameters 1
changed_paths set[str]

Set of changed file paths
Returns

bool —

True if any changed file is a Python file in autodoc source directories, or an OpenAPI spec file

_should_ignore_file
Check if file should be ignored (temp files, swap files, etc).
1 bool 
def _should_ignore_file(self, file_path: str) -> bool

Check if file should be ignored (temp files, swap files, etc).

Parameters 1
file_path str

Path to file
Returns

bool —

True if file should be ignored

_trigger_build
Execute the actual build (called after debounce delay). This method: 1. Clears…
0 None 
def _trigger_build(self) -> None

Execute the actual build (called after debounce delay).

This method:

  1. Clears ephemeral state to prevent stale object references
  2. Runs an incremental + parallel build for speed
  3. Displays build statistics
  4. Notifies connected SSE clients to reload
_handle_file_event
Common handler for file system events with debouncing. Multiple rapid file cha…
2 None 
def _handle_file_event(self, event: FileSystemEvent, event_type: str) -> None

Common handler for file system events with debouncing.

Multiple rapid file changes are batched together and trigger a single rebuild after a short delay (DEBOUNCE_DELAY seconds).

Files in the output directory and matching ignore patterns are skipped to prevent infinite rebuild loops.

Parameters 2
event FileSystemEvent

File system event
event_type str

Type of event (created, modified, deleted, moved)