1 min read
pyssg.core.phases
Phase orchestration: full build and incremental rebuild.
The full build and the incremental rebuild share the same per-document and per-page processing so that, by construction, an incremental rebuild is byte-identical to a full rebuild (the critical invariant). The full build is just "every node dirty-from LOAD"; the incremental path seeds a worklist from FS events and converges to a fixpoint with early-cutoff.
Stdlib only: all third-party work happens inside the plugins tapped onto the
hooks, never here. The watcher feeds neutral FsEvent-shaped objects; core
never imports the watchdog backend.
class FsEventLike(Protocol)
Structural shape of a filesystem event.
Declared here so core stays decoupled from pyssg.watch (and thus from
watchdog). The watch layer's FsEvent satisfies it.
FsEventLike.kind(self) -> str
FsEventLike.path(self) -> str
FsEventLike.dest(self) -> str | None
output_path_for(out_root: Path, url: str) -> Path
Map a page URL to its output file.
A URL whose final segment has a file extension (/sitemap.xml) maps to
that exact file; a pretty URL (/guide/) maps to .../index.html.
async full_build(build: Build) -> BuildStats
Discover, parse, generate, render and emit the whole site.
run_passes(build: Build, work: WorkList, out_root: Path) -> BuildStats
Process the dirty document frontier to a fixpoint, then finalize.
seed_from_events(build: Build, events: Sequence[FsEventLike], content_root: Path, work: WorkList) -> None
Translate (already coalesced) FS events into dirty seeds.
class IncrementalSession
A persistent build driven by FS events.
Keeps one Build (graph + hashes + bookkeeping) across rebuild passes and
reuses the builder's cache, so each rebuild only recomputes the dirty
frontier. apply returns the set of changed output URLs (for live-reload).
IncrementalSession.__init__(self, builder: Builder) -> None
async IncrementalSession.initial_build(self) -> BuildStats
IncrementalSession.apply(self, events: Sequence[FsEventLike]) -> BuildStats
Rebuild for a batch of FS events; returns this rebuild's stats.