Module

utils.path_resolver

Centralized path resolution utility.

Provides consistent path resolution across Bengal subsystems by eliminating CWD-dependent behavior. All paths are resolved relative to a fixed base (typically site.root_path).

Key Principles:

  • Base path must always be absolute
  • No Path.cwd() calls - all resolution is explicit
  • Paths resolved once at ingestion, not repeatedly

Usage:

resolver = PathResolver(site.root_path)
abs_path = resolver.resolve("../bengal")  # Always absolute

# Or from site instance
resolver = PathResolver.from_site(site)

Architecture:

This utility is part of the centralized path resolution architecture.
See plan/active/rfc-path-resolution-architecture.md for design rationale.

Related Modules:

  • bengal.core.site: Site.root_path is always absolute
  • bengal.config.loader: Config paths resolved on load
  • bengal.rendering.plugins.directives: Directives use resolver
View source
1 Class 1 Function

Classes

PathResolver
Centralized path resolution utility. All paths resolved relative to a fixed base (site root). Elim…
8

Centralized path resolution utility.

All paths resolved relative to a fixed base (site root). Eliminates CWD-dependent behavior across the codebase.

Attributes

Name Type Description
base —

Absolute base path for resolution

Methods 6

resolve
Resolve path to absolute, relative to base. If path is already absolute, retur…
1 Path 
def resolve(self, path: str | Path) -> Path

Resolve path to absolute, relative to base.

If path is already absolute, returns it unchanged. If path is relative, resolves it relative to self.base.

Parameters 1
path str | Path

Path to resolve (absolute or relative)
Returns

Path —

Absolute path

resolve_many
Resolve multiple paths.
1 list[Path] 
def resolve_many(self, paths: list[str | Path]) -> list[Path]

Resolve multiple paths.

Parameters 1
paths list[str | Path]

List of paths to resolve
Returns

list[Path] —

List of absolute paths

resolve_if_exists
Resolve path and return only if it exists.
1 Path | None 
def resolve_if_exists(self, path: str | Path) -> Path | None

Resolve path and return only if it exists.

Parameters 1
path str | Path

Path to resolve
Returns

Path | None —

Absolute path if exists, None otherwise

is_within_base
Check if a path is within the base directory. Useful for security checks to pr…
1 bool 
def is_within_base(self, path: str | Path) -> bool

Check if a path is within the base directory.

Useful for security checks to prevent path traversal attacks.

Parameters 1
path str | Path

Path to check (will be resolved first)
Returns

bool —

True if resolved path is under base directory

relative_to_base
Get path relative to base.
1 Path 
def relative_to_base(self, path: str | Path) -> Path

Get path relative to base.

Parameters 1
path str | Path

Path to make relative (resolved first)
Returns

Path —

Path relative to base

from_site classmethod
Create resolver from site instance.
1 PathResolver 
def from_site(cls, site: Site) -> PathResolver

Create resolver from site instance.

Parameters 1
site Site

Site instance (uses site.root_path as base)
Returns

PathResolver —

PathResolver with site root as base

Internal Methods 2
__init__
Initialize resolver with absolute base path.
1 None 
def __init__(self, base: Path) -> None

Initialize resolver with absolute base path.

Parameters 1
base Path

Base path for resolution (will be resolved to absolute)
__repr__
0 str 
def __repr__(self) -> str
Returns

str

Functions

resolve_path
Convenience function to resolve a single path. For one-off resolutions without creating a resolver…
2 Path 
def resolve_path(path: str | Path, base: Path) -> Path

Convenience function to resolve a single path.

For one-off resolutions without creating a resolver instance.

Parameters 2

Name Type Default Description
path str | Path —

Path to resolve
base Path —

Base path for resolution

Returns

Path —

Absolute path