Module

utils.build_context

Build context for sharing state across build phases.

Provides BuildContext dataclass for passing shared state between build phases, replacing scattered local variables. Created at build start and populated incrementally as phases execute.

Key Concepts:

  • Shared context: Single context object passed to all build phases
  • Phase coordination: Enables phase-to-phase communication
  • State management: Centralized build state management
  • Lifecycle: Created at build start, populated during phases
  • Lazy artifacts: Expensive computations cached on first access

Related Modules:

  • bengal.orchestration.build: Build orchestration using BuildContext
  • bengal.utils.build_stats: Build statistics collection
  • bengal.utils.progress: Progress reporting

See Also:

  • bengal/utils/build_context.py: BuildContext for context structure
  • plan/active/rfc-build-pipeline.md: Build pipeline design
  • plan/active/rfc-lazy-build-artifacts.md: Lazy artifact design
View source
1 Class

Classes

BuildContext dataclass
Shared build context passed across build phases. This context is created at the start of build() a…
13

Shared build context passed across build phases.

This context is created at the start of build() and passed to all phase* methods. It replaces local variables that were scattered throughout the 894-line build() method.

Lifecycle:

1. Created in _setup_build_context() at build start
2. Populated incrementally as phases execute
3. Used by all _phase_* methods for shared state

Categories:

  • Core: site, stats, profile (required)
  • Cache: cache, tracker (initialized in Phase 0)
  • Build mode: incremental, verbose, quiet, strict, parallel
  • Work items: pages_to_build, assets_to_process (determined in Phase 2)
  • Incremental state: affected_tags, affected_sections, changed_page_paths
  • Output: cli, progress_manager, reporter

Attributes

Name Type Description
site Site | None
stats BuildStats | None
profile BuildProfile | None
cache BuildCache | None
tracker DependencyTracker | None
incremental bool
verbose bool
quiet bool
strict bool
parallel bool
memory_optimized bool
full_output bool
profile_templates bool
pages list[Page] | None
pages_to_build list[Page] | None
assets list[Asset] | None
assets_to_process list[Asset] | None
affected_tags set[str]
affected_sections set[str] | None
changed_page_paths set[Path]
config_changed bool
cli CLIOutput | None
progress_manager LiveProgressManager | None
reporter ProgressReporter | None
build_start float
_knowledge_graph Any
_knowledge_graph_enabled bool
_page_contents dict[str, str]
_content_cache_lock Lock
_accumulated_page_json list[tuple[Any, dict[str, Any]]]
_accumulated_json_lock Lock

Methods 12

knowledge_graph property
Get knowledge graph (built lazily, cached for build duration). The knowledge g…
KnowledgeGraph | None 
def knowledge_graph(self) -> KnowledgeGraph | None

Get knowledge graph (built lazily, cached for build duration).

The knowledge graph is expensive to build (~200-500ms for 773 pages). By caching it here, we avoid rebuilding it 3 times per build (post-processing, special pages, health check).

Returns

KnowledgeGraph | None —

Built KnowledgeGraph instance, or None if disabled/unavailable

content_cache_size property
Get number of cached content entries.
int 
def content_cache_size(self) -> int

Get number of cached content entries.

Returns

int —

Number of files with cached content

has_cached_content property
Check if content cache has any entries. Validators can use this to decide whet…
bool 
def has_cached_content(self) -> bool

Check if content cache has any entries.

Validators can use this to decide whether to use cache or fallback.

Returns

bool —

True if cache has content

has_accumulated_json property
Check if accumulated JSON data exists. Post-processing can use this to decide …
bool 
def has_accumulated_json(self) -> bool

Check if accumulated JSON data exists.

Post-processing can use this to decide whether to use accumulated data or fall back to computing from pages.

Returns

bool —

True if accumulated JSON data exists

clear_lazy_artifacts
Clear lazy-computed artifacts to free memory. Call this at the end of a build …
0 None 
def clear_lazy_artifacts(self) -> None

Clear lazy-computed artifacts to free memory.

Call this at the end of a build to release memory used by cached artifacts like the knowledge graph and content cache.

cache_content
Cache raw content during discovery phase (thread-safe). Call this during conte…
2 None 
def cache_content(self, source_path: Path, content: str) -> None

Cache raw content during discovery phase (thread-safe).

Call this during content discovery to store file content for later use by validators. This eliminates redundant disk I/O during health checks.

Parameters 2
source_path Path

Path to source file (used as cache key)
content str

Raw file content to cache
get_content
Get cached content without disk I/O.
1 str | None 
def get_content(self, source_path: Path) -> str | None

Get cached content without disk I/O.

Parameters 1
source_path Path

Path to source file
Returns

str | None —

Cached content string, or None if not cached

get_all_cached_contents
Get a copy of all cached contents for batch processing. Returns a copy to avoi…
0 dict[str, str] 
def get_all_cached_contents(self) -> dict[str, str]

Get a copy of all cached contents for batch processing.

Returns a copy to avoid thread safety issues when iterating.

Returns

dict[str, str] —

Dictionary mapping source path strings to content

clear_content_cache
Clear content cache to free memory. Call this after validation phase completes…
0 None 
def clear_content_cache(self) -> None

Clear content cache to free memory.

Call this after validation phase completes to release memory used by cached file contents.

accumulate_page_json
Accumulate JSON data for a page during rendering (thread-safe). Call this duri…
2 None 
def accumulate_page_json(self, json_path: Any, page_data: dict[str, Any]) -> None

Accumulate JSON data for a page during rendering (thread-safe).

Call this during rendering phase to store JSON data for later use in post-processing. This eliminates redundant computation and double iteration of pages.

Parameters 2
json_path Any

Path where JSON file should be written
page_data dict[str, Any]

Pre-computed JSON data dictionary
get_accumulated_json
Get all accumulated JSON data for post-processing. Returns a copy to avoid thr…
0 list[tuple[Any, dic… 
def get_accumulated_json(self) -> list[tuple[Any, dict[str, Any]]]

Get all accumulated JSON data for post-processing.

Returns a copy to avoid thread safety issues when iterating.

Returns

list[tuple[Any, dict[str, Any]]] —

List of (json_path, page_data) tuples

clear_accumulated_json
Clear accumulated JSON data to free memory. Call this after post-processing ph…
0 None 
def clear_accumulated_json(self) -> None

Clear accumulated JSON data to free memory.

Call this after post-processing phase completes to release memory used by accumulated JSON data.

Internal Methods 1
_build_knowledge_graph
Build and cache knowledge graph.
0 KnowledgeGraph | None 
def _build_knowledge_graph(self) -> KnowledgeGraph | None

Build and cache knowledge graph.

Returns

KnowledgeGraph | None —

Built KnowledgeGraph instance, or None if disabled/unavailable