Module

`health.utils`

Shared utilities for health check validators.

This module extracts common patterns to reduce code duplication across validators. All utilities are designed to be defensive and handle edge cases gracefully.

Utilities:

iter_pages_with_output: Iterate pages with valid, existing output_path
relative_path: Convert absolute path to project-relative for display
get_section_pages: Safely get pages from section (handles .pages/.children)
get_health_config: Safely retrieve health_check config values
read_output_content: Safely read page output file content

Related:

bengal.health.validators: Validators that use these utilities
bengal.health.base: BaseValidator interface

Functions

iter_pages_with_output 3 Iterator[Any] ▼

Iterate over pages with valid output_path that exists on disk. This is a commo…

def iter_pages_with_output(site: SiteLike, *, limit: int | None = None, exclude_generated: bool = False) -> Iterator[Any]

Iterate over pages with valid output_path that exists on disk.

This is a common pattern in validators that need to inspect rendered output. Handles type narrowing and existence checks in one place.

Parameters

Name	Type	Description
`site`	`SiteLike`	Site instance containing pages
`limit`	`int \| None`	Maximum pages to yield (None for all) Default:`None`
`exclude_generated`	`bool`	Skip pages with _generated metadata Default:`False`

Returns

Iterator[Any]

relative_path 2 str ▼

Convert absolute path to project-relative path for display. Used consistently …

def relative_path(path: Path | str, root: Path) -> str

Convert absolute path to project-relative path for display.

Used consistently across validators for error messages and reports. Falls back to original path string if conversion fails.

Parameters

Name	Type	Description
`path`	`Path \| str`	Absolute path to convert
`root`	`Path`	Project root to make path relative to

Returns

str

get_section_pages 1 list[Any] ▼

Get pages from a section, handling both .pages and .children attributes. Suppo…

def get_section_pages(section: Any) -> list[Any]

Get pages from a section, handling both .pages and .children attributes.

Supports both full Section objects and lightweight test mocks that may usechildren instead of pages.

Parameters

Name	Type	Description
`section`	`Any`	Section-like object

Returns

list[Any]

get_health_config 3 Any ▼

Safely get a value from health_check config section. Handles both dict-based a…

def get_health_config(site: SiteLike, key: str, default: Any = None) -> Any

Safely get a value from health_check config section.

Handles both dict-based and object-based config access patterns, and gracefully handles missing or malformed config.

Parameters

Name	Type	Description
`site`	`SiteLike`	Site instance with config
`key`	`str`	Config key to retrieve from health_check section
`default`	`Any`	Default value if key not found Default:`None`

Returns

Any

read_output_content 2 str | None ▼

Safely read output file content with error handling. Common pattern for valida…

def read_output_content(page: Any, encoding: str = 'utf-8') -> str | None

Safely read output file content with error handling.

Common pattern for validators that inspect rendered HTML output. Returns None on any error (missing file, encoding issues, etc.).

Parameters

Name	Type	Description
`page`	`Any`	Page with output_path attribute
`encoding`	`str`	File encoding (default utf-8) Default:`'utf-8'`

Returns

str | None

sample_pages 4 list[Any] ▼

Get a sample of pages for validation checks. Many validators only need to chec…

def sample_pages(site: SiteLike, count: int = 10, *, exclude_generated: bool = False, require_output: bool = True) -> list[Any]

Get a sample of pages for validation checks.

Many validators only need to check a subset of pages (e.g., first 10) for performance. This utility standardizes that sampling.

Parameters

Name	Type	Description
`site`	`SiteLike`	Site instance containing pages
`count`	`int`	Maximum pages to return Default:`10`
`exclude_generated`	`bool`	Skip pages with _generated metadata Default:`False`
`require_output`	`bool`	Only include pages with existing output_path Default:`True`

Returns

list[Any]