Module

utils.paths

Path utilities for Bengal SSG.

Provides consistent path management for temporary files, logs, and profiles.

View source
1 Class 1 Function

Classes

BengalPaths
Manages Bengal's directory structure for generated files. Directory Structure: - .bengal/ …
7

Manages Bengal's directory structure for generated files.

Directory Structure:

  • .bengal/ → source_dir/.bengal/ (all Bengal state)
    • logs/build.log → build logs
    • logs/serve.log → dev server logs
    • metrics/ → performance metrics
    • profiles/ → cProfile output
    • cache.json.zst → build cache
    • indexes/ → query indexes

This provides a clean separation between:

  1. Build outputs (public/) - deployable files
  2. Bengal state (.bengal/) - cache, logs, metrics, profiles

Methods 7

get_profile_dir staticmethod
Get the directory for storing performance profiles.
1 Path 
def get_profile_dir(source_dir: Path) -> Path

Get the directory for storing performance profiles.

Parameters 1
source_dir Path

Source directory (where content/ and bengal.toml live)
Returns

Path —

Path to .bengal/profiles/ directory

get_log_dir staticmethod
Get the directory for storing build logs.
1 Path 
def get_log_dir(source_dir: Path) -> Path

Get the directory for storing build logs.

Parameters 1
source_dir Path

Source directory (where content/ and bengal.toml live)
Returns

Path —

Path to .bengal/logs/ directory

get_build_log_path staticmethod
Get the path for the build log file.
2 Path 
def get_build_log_path(source_dir: Path, custom_path: Path | None = None) -> Path

Get the path for the build log file.

Parameters 2
source_dir Path

Source directory
custom_path Path | None

Optional custom path specified by user
Returns

Path —

Path to build log file (.bengal/logs/build.log)

get_serve_log_path staticmethod
Get the path for the dev server log file.
2 Path 
def get_serve_log_path(source_dir: Path, custom_path: Path | None = None) -> Path

Get the path for the dev server log file.

Parameters 2
source_dir Path

Source directory
custom_path Path | None

Optional custom path specified by user
Returns

Path —

Path to serve log file (.bengal/logs/serve.log)

get_profile_path staticmethod
Get the path for a performance profile file.
3 Path 
def get_profile_path(source_dir: Path, custom_path: Path | None = None, filename: str = 'build_profile.stats') -> Path

Get the path for a performance profile file.

Parameters 3
source_dir Path

Source directory
custom_path Path | None

Optional custom path specified by user
filename str

Default filename for the profile
Returns

Path —

Path to profile file

get_cache_path staticmethod
Get the path for the build cache file.
1 Path 
def get_cache_path(output_dir: Path) -> Path

Get the path for the build cache file.

Parameters 1
output_dir Path

Output directory (public/)
Returns

Path —

Path to .bengal-cache.json

get_template_cache_dir staticmethod
Get the directory for Jinja2 bytecode cache.
1 Path 
def get_template_cache_dir(output_dir: Path) -> Path

Get the directory for Jinja2 bytecode cache.

Parameters 1
output_dir Path

Output directory (public/)
Returns

Path —

Path to .bengal-cache/templates/

Functions

format_path_for_display
Format a path for display in logs and warnings. Makes paths relative to a base directory (e.g., si…
2 str | None 
def format_path_for_display(path: Path | str | None, base_path: Path | None = None) -> str | None

Format a path for display in logs and warnings.

Makes paths relative to a base directory (e.g., site root) to avoid showing user-specific absolute paths in output.

Parameters 2

Name Type Default Description
path Path | str | None —

Path to format (can be Path, str, or None)
base_path Path | None None

Base directory to make paths relative to (e.g., site.root_path). If None, uses fallback formatting.

Returns

str | None —

Formatted path string, or None if path was None