Bring Your Own Template Engine

# my_engine/environment.py
from collections.abc import MutableMapping
from typing import Any, Callable

class MyEnvironment:
    """Template environment that satisfies TemplateEnvironment protocol."""

    def __init__(self):
        # These three attributes are REQUIRED for protocol compliance
        self.globals: dict[str, Any] = {}
        self.filters: dict[str, Callable[..., Any]] = {}
        self.tests: dict[str, Callable[..., bool]] = {}

        # Your engine-specific setup
        self._templates: dict[str, str] = {}

    def add_global(self, name: str, value: Any) -> None:
        """Add a global variable."""
        self.globals[name] = value

    def add_filter(self, name: str, func: Callable) -> None:
        """Add a filter function."""
        self.filters[name] = func

    def add_test(self, name: str, func: Callable) -> None:
        """Add a test function."""
        self.tests[name] = func

# my_engine/engine.py
from pathlib import Path
from typing import Any

from bengal.core import Site
from bengal.protocols import EngineCapability
from bengal.rendering.engines.errors import TemplateError, TemplateNotFoundError
from bengal.rendering.template_functions import register_all

from .environment import MyEnvironment

class MyEngine:
    """Custom template engine implementation."""

    def __init__(self, site: Site):
        self.site = site
        self.template_dirs = self._build_template_dirs()

        # Create environment that satisfies TemplateEnvironment protocol
        self._env = MyEnvironment()

        # Register all 200+ Bengal template functions, filters, and tests automatically!
        register_all(self._env, site, engine_type="generic")

    def _build_template_dirs(self) -> list[Path]:
        """Build ordered list of template directories."""
        dirs = []

        # Project templates (highest priority)
        project_templates = self.site.root_path / "templates"
        if project_templates.exists():
            dirs.append(project_templates)

        # Theme templates (simplified - for theme inheritance, see Kida engine)
        # For basic cases, this works. For parent/child theme support, use
        # resolve_theme_chain() as shown in bengal.rendering.engines.kida
        if hasattr(self.site, 'theme_path') and self.site.theme_path:
            theme_templates = self.site.theme_path / "templates"
            if theme_templates.exists():
                dirs.append(theme_templates)

        return dirs

    def render_template(self, name: str, context: dict[str, Any]) -> str:
        """Render a named template with context."""
        template_path = self.get_template_path(name)
        if not template_path:
            raise TemplateNotFoundError(f"Template not found: {name}")

        source = template_path.read_text()
        return self._render(source, context)

    def render_string(self, template: str, context: dict[str, Any]) -> str:
        """Render an inline template string."""
        return self._render(template, context)

    def _render(self, source: str, context: dict[str, Any]) -> str:
        """Core rendering logic - implement for your engine."""
        # Merge globals into context
        full_context = {**self._env.globals, **context}

        # Your rendering implementation here
        # Access filters via self._env.filters
        # Access tests via self._env.tests
        ...

    def template_exists(self, name: str) -> bool:
        """Check if template exists."""
        return self.get_template_path(name) is not None

    def get_template_path(self, name: str) -> Path | None:
        """Find template in search directories."""
        for dir in self.template_dirs:
            path = dir / name
            if path.exists():
                return path
        return None

    def list_templates(self) -> list[str]:
        """List all available templates."""
        templates = set()
        for dir in self.template_dirs:
            for path in dir.rglob("*.html"):
                templates.add(str(path.relative_to(dir)))
        return sorted(templates)

    def validate(self, patterns: list[str] | None = None) -> list[TemplateError]:
        """Validate templates for syntax errors."""
        errors = []
        for name in self.list_templates():
            try:
                path = self.get_template_path(name)
                if path:
                    source = path.read_text()
                    self._validate_syntax(source)
            except Exception as e:
                errors.append(TemplateError(name=name, message=str(e)))
        return errors

    @property
    def capabilities(self) -> EngineCapability:
        """Declare engine capabilities."""
        return EngineCapability.NONE

    def has_capability(self, cap: EngineCapability) -> bool:
        return cap in self.capabilities

# my_engine/__init__.py
from bengal.rendering.engines import register_engine
from .engine import MyEngine

# Register with Bengal
register_engine("myengine", MyEngine)

# config/_default/site.yaml (or [site] in bengal.toml)
site:
  template_engine: myengine