Module

core.site.section_registry

Section registry mixin for Site.

Provides O(1) section lookups by path and URL via registries.

Related Modules:

  • bengal.core.site.core: Main Site dataclass using this mixin
  • bengal.core.section: Section model
View source
1 Class

Classes

SectionRegistryMixin
Mixin providing section registry for O(1) lookups. Requires these attributes on the host class: …
5

Mixin providing section registry for O(1) lookups.

Requires these attributes on the host class:

  • root_path: Path
  • sections: list[Section]
  • _section_registry: dict[Path, Section]
  • _section_url_registry: dict[str, Section]

Attributes

Name Type Description
root_path Path
sections list[Section]
_section_registry dict[Path, Section]
_section_url_registry dict[str, Section]

Methods 3

get_section_by_path
Look up a section by its path (O(1) operation). Uses the section registry for …
1 Section | None 
def get_section_by_path(self, path: Path | str) -> Section | None

Look up a section by its path (O(1) operation).

Uses the section registry for fast lookups without scanning the section tree. Paths are normalized before lookup to handle case-insensitive filesystems and symlinks consistently.

Parameters 1
path Path | str

Section path (absolute, relative to content/, or relative to root)
Returns

Section | None —

Section object if found, None otherwise

get_section_by_url
Look up a section by its relative URL (O(1) operation). Used for virtual secti…
1 Section | None 
def get_section_by_url(self, url: str) -> Section | None

Look up a section by its relative URL (O(1) operation).

Used for virtual sections that don't have a disk path. Virtual sections are registered by their relative_url during register_sections().

Parameters 1
url str

Section relative URL (e.g., "/api/", "/api/core/")
Returns

Section | None —

Section object if found, None otherwise

register_sections
Build the section registries for path-based and URL-based lookups. Scans all s…
0 None 
def register_sections(self) -> None

Build the section registries for path-based and URL-based lookups.

Scans all sections recursively and populates:

  • _section_registry: normalized path → Section mappings
  • _section_url_registry: relative_url → Section mappings (for virtual sections)

This enables O(1) section lookups without scanning the section hierarchy.

Must be called after discover_content() and before any code that uses get_section_by_path(), get_section_by_url(), or page._section property.

Build ordering invariant:

1. discover_content()       → Creates Page/Section objects
2. register_sections()      → Builds registries (THIS)
3. setup_page_references()  → Sets page._section via property setter
4. apply_cascades()         → Lookups resolve via registry
5. generate_urls()          → Uses correct section hierarchy

Performance:

O(n) where n = number of sections. Typical: < 10ms for 1000 sections.
Internal Methods 2
_normalize_section_path
Normalize a section path for registry lookups. Normalization ensures consisten…
1 Path 
def _normalize_section_path(self, path: Path) -> Path

Normalize a section path for registry lookups.

Normalization ensures consistent lookups across platforms:

  • Resolves symlinks to canonical paths
  • Makes path relative to content/ directory
  • Lowercases on case-insensitive filesystems (macOS, Windows)
Parameters 1
path Path

Absolute or relative section path
Returns

Path —

Normalized path suitable for registry keys

_register_section_recursive
Recursively register a section and its subsections in the registries. Handles …
1 None 
def _register_section_recursive(self, section: Section) -> None

Recursively register a section and its subsections in the registries.

Handles both regular sections (with path) and virtual sections (path=None).

Regular sections: Registered in _section_registry by normalized path. Virtual sections: Registered in _section_url_registry by relative_url, enabling page._section lookups via get_section_by_url().

Parameters 1
section Section

Section to register (along with all its subsections)