Module

cache.dependency_tracker

Dependency tracker for build process dependency management.

Tracks template, partial, and data file dependencies during rendering to enable incremental builds. Records dependencies in BuildCache for change detection and selective rebuilding.

Key Concepts:

  • Dependency tracking: Template and data file dependencies per page
  • Thread-safe tracking: Thread-local storage for parallel rendering
  • Cache integration: Dependencies stored in BuildCache
  • Incremental builds: Dependency changes trigger selective rebuilds

Related Modules:

  • bengal.cache.build_cache: Build cache persistence
  • bengal.orchestration.incremental: Incremental build logic
  • bengal.rendering.pipeline: Rendering pipeline using dependency tracking

See Also:

  • bengal/cache/dependency_tracker.py: DependencyTracker for tracking logic
  • plan/active/rfc-incremental-builds.md: Incremental build design
View source
2 Classes

Classes

CacheInvalidator
Cache invalidation logic for incremental builds. Tracks invalidated paths based on content, templa…
5

Cache invalidation logic for incremental builds.

Tracks invalidated paths based on content, template, and config changes. Provides methods for selective invalidation and full cache invalidation.

Creation:

Direct instantiation: CacheInvalidator(config_hash, content_paths, template_paths)
  • Created by DependencyTracker for cache invalidation
  • Requires config hash and path lists

Attributes

Name Type Description
config_hash —

Hash of configuration for config change detection
content_paths —

List of content file paths
template_paths —

List of template file paths
invalidated —

Set of invalidated paths
Relationships —
  • Used by: DependencyTracker for cache invalidation - Uses: Path sets for invalidation tracking

Methods 4

is_stale property
Invariant: Check if cache needs rebuild.
bool 
def is_stale(self) -> bool

Invariant: Check if cache needs rebuild.

Returns

bool

invalidate_content
Invalidate on content changes.
1 set[Path] 
def invalidate_content(self, changed_paths: set[Path]) -> set[Path]

Invalidate on content changes.

Parameters 1
changed_paths set[Path]
Returns

set[Path]

invalidate_templates
Invalidate dependent pages on template changes.
1 set[Path] 
def invalidate_templates(self, changed_paths: set[Path]) -> set[Path]

Invalidate dependent pages on template changes.

Parameters 1
changed_paths set[Path]
Returns

set[Path]

invalidate_config
Full invalidation on config change.
0 set[Path] 
def invalidate_config(self) -> set[Path]

Full invalidation on config change.

Returns

set[Path]

Internal Methods 1
__init__
3 None 
def __init__(self, config_hash: str, content_paths: list[Path], template_paths: list[Path])
Parameters 3
config_hash str
content_paths list[Path]
template_paths list[Path]
DependencyTracker
Tracks dependencies between pages and their templates, partials, and config files. Records templat…
12

Tracks dependencies between pages and their templates, partials, and config files.

Records template and data file dependencies during rendering to enable incremental builds. Uses thread-local storage for thread-safe parallel rendering and maintains dependency graphs for change detection.

Creation:

Direct instantiation: DependencyTracker(cache, site=None)
  • Created by IncrementalOrchestrator for dependency tracking
  • Requires BuildCache instance for dependency storage

Attributes

Name Type Description
cache —

BuildCache instance for dependency storage
site —

Optional Site instance for config path access
logger —

Logger instance for dependency tracking events
tracked_files —

Mapping of file paths to page paths
dependencies —

Forward dependency graph (page → dependencies)
reverse_dependencies —

Reverse dependency graph (dependency → pages)
current_page —

Thread-local current page being processed
invalidator —

CacheInvalidator for cache invalidation
Relationships —
  • Uses: BuildCache for dependency persistence - Used by: RenderingPipeline for dependency tracking during rendering - Used by: IncrementalOrchestrator for change detection Thread Safety: Thread-safe. Uses thread-local storage for current page tracking and thread-safe locks for dependency graph updates.

Methods 10

start_page
Mark the start of processing a page (thread-safe).
1 None 
def start_page(self, page_path: Path) -> None

Mark the start of processing a page (thread-safe).

Parameters 1
page_path Path

Path to the page being processed
track_template
Record that the current page depends on a template (thread-safe).
1 None 
def track_template(self, template_path: Path) -> None

Record that the current page depends on a template (thread-safe).

Parameters 1
template_path Path

Path to the template file
track_partial
Record that the current page depends on a partial/include (thread-safe).
1 None 
def track_partial(self, partial_path: Path) -> None

Record that the current page depends on a partial/include (thread-safe).

Parameters 1
partial_path Path

Path to the partial file
track_config
Record that the current page depends on the config file (thread-safe). All page…
1 None 
def track_config(self, config_path: Path) -> None

Record that the current page depends on the config file (thread-safe). All pages depend on config, so this marks it as a global dependency.

Parameters 1
config_path Path

Path to the config file
track_asset
Record an asset file (for cache invalidation).
1 None 
def track_asset(self, asset_path: Path) -> None

Record an asset file (for cache invalidation).

Parameters 1
asset_path Path

Path to the asset file
track_taxonomy
Record taxonomy (tags/categories) dependencies. When a page's tags change, tag…
2 None 
def track_taxonomy(self, page_path: Path, tags: set[str]) -> None

Record taxonomy (tags/categories) dependencies.

When a page's tags change, tag pages need to be regenerated.

Parameters 2
page_path Path

Path to the page
tags set[str]

Set of tags/categories for this page
end_page
Mark the end of processing a page (thread-safe).
0 None 
def end_page(self) -> None

Mark the end of processing a page (thread-safe).

get_changed_files
Get all files that have changed since the last build.
1 set[Path] 
def get_changed_files(self, root_path: Path) -> set[Path]

Get all files that have changed since the last build.

Parameters 1
root_path Path

Root path of the site
Returns

set[Path] —

Set of paths that have changed

find_new_files
Find files that are new (not in cache).
1 set[Path] 
def find_new_files(self, current_files: set[Path]) -> set[Path]

Find files that are new (not in cache).

Parameters 1
current_files set[Path]

Set of current file paths
Returns

set[Path] —

Set of new file paths

find_deleted_files
Find files that were deleted (in cache but not on disk).
1 set[Path] 
def find_deleted_files(self, current_files: set[Path]) -> set[Path]

Find files that were deleted (in cache but not on disk).

Parameters 1
current_files set[Path]

Set of current file paths
Returns

set[Path] —

Set of deleted file paths

Internal Methods 2
__init__
Initialize the dependency tracker.
2 None 
def __init__(self, cache: BuildCache, site: Site | None = None) -> None

Initialize the dependency tracker.

Parameters 2
cache BuildCache

BuildCache instance to store dependencies in
site Site | None

Optional Site instance to get config path from
_hash_config
Hash config for invalidation.
0 str 
def _hash_config(self) -> str

Hash config for invalidation.

Returns

str