Module

core.cascade_engine

Isolated cascade engine for applying metadata cascades.

This module provides the CascadeEngine class which handles all cascade application logic independently from Site and ContentOrchestrator.

The engine pre-computes page-section relationships for O(1) top-level page detection, improving performance from O(n²) to O(n).

View source
1 Class

Classes

CascadeEngine
Isolated cascade application logic with pre-computed O(1) lookups. Handles metadata cascading wher…
5

Isolated cascade application logic with pre-computed O(1) lookups.

Handles metadata cascading where section _index.md files can define cascade metadata that propagates to descendant pages. This allows setting common metadata at the section level rather than repeating it on every page.

Pre-computes page-section relationships to avoid O(n²) lookups when determining if a page is top-level (not in any section).

Attributes

Name Type Description
pages —

All pages in the site
sections —

All sections in the site
_pages_in_sections —

Pre-computed set of pages that belong to sections (O(1) lookup)

Methods 2

is_top_level_page
Check if a page is top-level (not in any section). O(1) lookup using pre-compu…
1 bool 
def is_top_level_page(self, page: Any) -> bool

Check if a page is top-level (not in any section).

O(1) lookup using pre-computed set.

Parameters 1
page Any

Page object to check
Returns

bool —

True if page is not in any section, False otherwise

apply
Apply cascade metadata from sections to pages. Processes root-level cascades f…
0 dict[str, Any] 
def apply(self) -> dict[str, Any]

Apply cascade metadata from sections to pages.

Processes root-level cascades first, then recursively applies cascades through the section hierarchy. Returns statistics about what was cascaded.

Returns

dict[str, Any] —

Dictionary with cascade statistics:

  • pages_processed: Total pages in site
  • pages_with_cascade: Pages that received cascade values
  • root_cascade_pages: Pages affected by root cascade
  • cascade_keys_applied: Count of each cascaded key

Internal Methods 3
__init__
Initialize cascade engine with site pages and sections.
2 None 
def __init__(self, pages: list[Any], sections: list[Any]) -> None

Initialize cascade engine with site pages and sections.

Parameters 2
pages list[Any]

List of all Page objects in the site
sections list[Any]

List of all Section objects in the site
_compute_pages_in_sections
Pre-compute set of all pages that belong to any section. This enables O(1) loo…
1 set[Any] 
def _compute_pages_in_sections(self, sections: list[Any]) -> set[Any]

Pre-compute set of all pages that belong to any section.

This enables O(1) lookup later instead of searching all sections for each page. Called once during initialization.

Parameters 1
sections list[Any]

List of Section objects
Returns

set[Any] —

Set of Page objects that belong to at least one section

_apply_section_cascade
Recursively apply cascade metadata to a section and its descendants. Cascade m…
3 None 
def _apply_section_cascade(self, section: Any, parent_cascade: dict[str, Any] | None = None, stats: dict[str, Any] | None = None) -> None

Recursively apply cascade metadata to a section and its descendants.

Cascade metadata accumulates through the hierarchy - child sections inherit from parent and can override/extend it.

Parameters 3
section Any

Section to apply cascade to
parent_cascade dict[str, Any] | None

Cascade metadata inherited from parent sections
stats dict[str, Any] | None

Statistics dictionary to update (for tracking what was cascaded)