Module

rendering.template_engine.core

Template engine using Jinja2 for page rendering.

Provides template rendering, template function registration, and optional template profiling for performance analysis. Integrates with theme system for template discovery and asset manifest for cache-busting.

Key Concepts:

  • Template inheritance: Child themes inherit parent templates
  • Bytecode caching: Compiled templates cached for faster subsequent renders
  • Template profiling: Optional timing data collection via --profile-templates
  • Strict mode: StrictUndefined enabled for better error detection

Related Modules:

  • bengal.rendering.template_profiler: Profiling implementation
  • bengal.rendering.template_functions: Template function registry
  • bengal.utils.theme_registry: Theme resolution and discovery
View source
1 Class

Classes

TemplateEngine
Template engine for rendering pages with Jinja2 templates. Provides Jinja2 template rendering with…
10

Template engine for rendering pages with Jinja2 templates.

Provides Jinja2 template rendering with theme inheritance, template function registration, asset manifest access, and optional template profiling. Manages template discovery through theme chains and provides cache-busting via asset manifest.

Creation:

Direct instantiation: TemplateEngine(site, profile_templates=False)
  • Created by RenderingPipeline for template rendering
  • Requires Site instance with theme configuration
  • Optional profiling enabled via profile_templates flag
Inherits from MenuHelpersMixin,ManifestHelpersMixin,AssetURLMixin

Attributes

Name Type Description
site —

Site instance with theme and configuration
template_dirs —

List of template directories (populated during init)
env —

Jinja2 Environment instance
_profile_templates —

Whether template profiling is enabled
_profiler —

Optional TemplateProfiler for performance analysis
_dependency_tracker —

Optional DependencyTracker (set by RenderingPipeline)
_asset_manifest_cache —

Cached asset manifest entries
Relationships —
  • Uses: Theme resolution for template directory discovery - Uses: Template functions for template function registration - Uses: AssetManifest for cache-busting asset URLs - Used by: RenderingPipeline for template rendering - Used by: Renderer for page rendering

Methods 4

render
Render a template with the given context.
2 str 
def render(self, template_name: str, context: dict[str, Any]) -> str

Render a template with the given context.

Parameters 2
template_name str

Name of the template file
context dict[str, Any]

Template context variables
Returns

str —

Rendered HTML

get_template_profile
Get template profiling report.
0 dict[str, Any] | None 
def get_template_profile(self) -> dict[str, Any] | None

Get template profiling report.

Returns

dict[str, Any] | None —

Dictionary with template and function timing statistics, or None if profiling is not enabled.

render_string
Render a template string with the given context.
2 str 
def render_string(self, template_string: str, context: dict[str, Any]) -> str

Render a template string with the given context.

Parameters 2
template_string str

Template content as string
context dict[str, Any]

Template context variables
Returns

str —

Rendered HTML

validate_templates
Validate syntax of all templates in the search path. Proactively checks all di…
1 list[Any] 
def validate_templates(self, include_patterns: list[str] | None = None) -> list[Any]

Validate syntax of all templates in the search path.

Proactively checks all discoverable templates for syntax errors by attempting to compile them through Jinja2. This catches errors before rendering, providing early feedback during builds.

Parameters 1
include_patterns list[str] | None

Optional list of glob patterns to limit validation (e.g., ["page.html", "partials/*.html"]). If None, validates all .html and .xml templates.
Returns

list[Any] —

List of TemplateRenderError for any templates with syntax errors. Empty list if all templates are valid.

Internal Methods 6
__init__
Initialize the template engine.
2 None 
def __init__(self, site: Any, profile_templates: bool = False) -> None

Initialize the template engine.

Parameters 2
site Any

Site instance
profile_templates bool

Enable template profiling for performance analysis
_url_for
Generate URL for a page with base URL support.
1 str 
def _url_for(self, page: Any) -> str

Generate URL for a page with base URL support.

Parameters 1
page Any

Page object
Returns

str —

URL path with base URL prefix if configured

_with_baseurl
Apply base URL prefix to a path.
1 str 
def _with_baseurl(self, path: str) -> str

Apply base URL prefix to a path.

Parameters 1
path str

Relative path starting with '/'
Returns

str —

Path with base URL prefix

_find_template_path
Find the full path to a template file.
1 Path | None 
def _find_template_path(self, template_name: str) -> Path | None

Find the full path to a template file.

Parameters 1
template_name str

Name of the template
Returns

Path | None —

Full path to template file, or None if not found

_resolve_theme_chain
Resolve theme inheritance chain starting from the active theme. Compatibility …
1 list[str] 
def _resolve_theme_chain(self, active_theme: str | None) -> list[str]

Resolve theme inheritance chain starting from the active theme.

Compatibility method for tests. Delegates to resolve_theme_chain function.

Parameters 1
active_theme str | None

Active theme name
Returns

list[str] —

List of theme names in inheritance order

_read_theme_extends
Read theme.toml for 'extends' value. Compatibility method for tests. Delegates…
1 str | None 
def _read_theme_extends(self, theme_name: str) -> str | None

Read theme.toml for 'extends' value.

Compatibility method for tests. Delegates to read_theme_extends function.

Parameters 1
theme_name str

Theme name to look up
Returns

str | None —

Parent theme name if extends is set, None otherwise