----------------------------------------------------------------------
This is the API documentation for the chameleon_robyn library.
----------------------------------------------------------------------


## Setup & configuration

Initialize the template engine once at app startup.


global_init(template_folder: str, auto_reload: bool = False, cache_init: bool = True, restricted_namespace: bool = True) -> None

Initialize the Chameleon template engine.

Args:
    template_folder: Path to the template directory
    auto_reload: Whether to auto-reload templates on change
    cache_init: Whether to cache initialization (skip if already initialized)
    restricted_namespace: If True, only TAL/METAL/i18n namespaces are allowed.
                        If False, allows attribute-based JS frameworks like Alpine.js
                        to use shorthand syntax (@click, :class, etc.)

clear() -> None

Reset the template engine to its uninitialized state.

After calling this, global_init() must be called again before rendering.
Mostly useful in tests to isolate template configuration between cases.


## Rendering views

The @template decorator and friendly 404s for Robyn route handlers.


template(template_file: Callable | str | None = None, content_type: str = 'text/html', status_code: int = 200) -> Callable

Decorate a Robyn view method to render an HTML response.

The decorated handler returns a dict (the template model). If the template path is
omitted, it is derived from the module and function name: module/function.html if that
file exists, otherwise module/function.pt. The auto-derived name is resolved at first
request, so global_init() may be called after route decoration. Handlers that return a
Robyn Response are passed through untouched (redirects, custom errors). Works with sync
and async handlers.

Args:
    template_file: Optional, the Chameleon template file (path relative to template folder, *.pt).
    content_type: The Content-Type header value for rendered responses (defaults to text/html).
    status_code: The HTTP status code for rendered responses (defaults to 200).

Returns:
    Decorator for Robyn route handlers.

not_found(four04template_file: str = 'errors/404.pt') -> NoReturn

Render a friendly 404 page from within a @template-decorated handler.

Raises an exception that the @template decorator catches and converts into a
404 response rendered through the given template. The template receives a
`message` variable describing the 404. Only works inside handlers decorated
with @template.

Args:
    four04template_file: The template to render, relative to the template folder
        (defaults to 'errors/404.pt').

Raises:
    ChameleonRobynNotFoundException: Always; carries the 404 template path.


## Lower-level rendering

Render templates outside the decorator (middleware, error handlers, emails).


render(template_file: str, **template_data: Any) -> str

Render a Chameleon template to a string (no Response wrapping).

Useful outside of route handlers: emails, middleware, error handlers, etc.

Args:
    template_file: The template file path, relative to the template folder (e.g. 'emails/welcome.pt').
    **template_data: Values passed to the template as its model.

Returns:
    The rendered template as a string.

Raises:
    ChameleonRobynException: If global_init() has not been called.

response(template_file: str, content_type: str = 'text/html', status_code: int = 200, **template_data: Any) -> Response

Render a Chameleon template and wrap it in a fully-formed Robyn Response.

Args:
    template_file: The template file path, relative to the template folder.
    content_type: The Content-Type header value (defaults to text/html).
    status_code: The HTTP status code for the response (defaults to 200).
    **template_data: Values passed to the template as its model.

Returns:
    A Robyn Response with the rendered template as its body.


## Robyn TemplateInterface

Standalone template engine class matching Robyn's built-in template pattern.


ChameleonTemplate(directory: str, auto_reload: bool = False, encoding: str = 'utf-8', restricted_namespace: bool = True)

Chameleon template engine implementing Robyn's TemplateInterface.

A standalone alternative to the module-level API: it owns its own template
loader and does not require global_init(). Use it like Robyn's built-in
JinjaTemplate.

Args:
    directory: Path to the template directory.
    auto_reload: Whether to auto-reload templates on change (use True in development).
    encoding: Output encoding for rendered templates (defaults to utf-8).
    restricted_namespace: If True, only TAL/METAL/i18n namespaces are allowed.
        Set to False for Alpine.js/htmx-style attributes (@click, :class, etc.).


## Exceptions

Exception types raised by the library.


ChameleonRobynException

Base exception for all chameleon-robyn errors (bad configuration, invalid return types, etc.).

ChameleonRobynNotFoundException(message: str | None = None, four04template_file: str = 'errors/404.pt')

Raised by not_found() to signal a 404 from within a @template-decorated handler.

The @template decorator catches this exception and renders the template it
carries with a 404 status code, passing the message to the template as `message`.

Args:
    message: Optional human-readable description of the 404.
    four04template_file: The 404 template to render, relative to the template folder.