API Reference

The public API of chameleon-rs. It mirrors Chameleon’s (PageTemplate, PageTemplateFile, PageTemplateLoader, …), plus async rendering, built-in partials, process-wide configuration (including Markdown) and the Flask/Quart, FastAPI, Starlette, Robyn and Litestar integrations.

Templates

Compile and render templates from strings, files and folders.

PageTemplate: Constructor for the page template language, rendered by the Rust VM.
PageTemplateFile: File-based page template loaded from filename when first used.
PageTextTemplate: Text-based template class: only ${...} interpolation, no markup, nothing escaped.
PageTextTemplateFile: File-based text template whose render() returns bytes (UTF-8 by default).
PageTemplateLoader: Loads and caches page templates from one or more directories by filename (loader['page.pt']).

PageTemplate Methods

Methods for the PageTemplate class

PageTemplate.__getitem__()
PageTemplate.engine: Chameleon’s expression engine factory for this template’s expression types.
PageTemplate.expression_parser: Chameleon’s parser for this template’s expression_types and default_expression.
PageTemplate.builtins: The template builtins: names every expression can use (overridden by render keywords).
PageTemplate.parse()
PageTemplate.include: The whole template as a macro (metal:use-macro="template").
PageTemplate.render(): Render template to string.
PageTemplate.render_async(): Render template to string, awaiting awaitable values (D9).
PageTemplate.digest()

Configuration

Process-wide settings for templates loaded by name, partials and Markdown.

configure(): Configures chameleon-rs for the whole process (partials, framework integrations, and Markdown).
core_version(): Version of the Rust core, for bug reports and for checking which build is loaded.

Async

Opt-in concurrency for render_async. See also PageTemplate.render_async.

concurrent(): Marks an async helper so that an asynchronous render awaits its calls concurrently

Partials

Render one template inside another. Also chameleon_partials’ API.

render_partial
partials.register_extensions(): chameleon_partials’ setup call: configures the folder render_partial uses (only
partials.extend_model(): Adds render_partial to a view model (chameleon_partials’ helper; not needed with the
partials.clear(): Forgets the folder partials use, for tests.
partials.PartialRenderer: Renders a partial template by path and returns an HTML object.
partials.HTML: Rendered markup, as render_partial returns it from Python: __html__ gives the
partials.PartialsException: Raised when partials are configured or used incorrectly: registering a folder that does

Flask and Quart

chameleon-flask’s API, built in. Imports Flask only when imported itself.

flask.configure(): Configures where templates live and how they load: for the whole process (the same as
flask.global_init(): chameleon-flask’s setup call: configures the views’ templates only (partials keep their
flask.template(): Decorates a Flask or Quart view (sync or async) to render a template with what it
flask.render(): Renders a template (path relative to the template folder) to a str.
flask.response(): Renders a template to a flask.Response. (Unlike @template, mimetype is not a
flask.not_found(): Ends the current @template view with a 404 page: template_file
flask.error(): Ends the current @template view with an error page: template_file rendered with
flask.clear(): Forgets the views’ process-wide configuration, so a later configure() /
flask.check_views(): Raises chameleon_rs.web.DecoratorOrderError if a route of app (blueprints

FastAPI

fastapi-chameleon’s API, built in. Imports FastAPI only when imported itself.

fastapi.configure(): Configures where templates live and how they load, for the whole process (the same as
fastapi.global_init(): fastapi-chameleon’s setup call: configures the views’ templates only (partials keep
fastapi.template(): Decorates a FastAPI view (sync or async) to render a template with what it returns:
fastapi.render(): Renders a template (path relative to the template folder) to a str.
fastapi.render_async(): render as a coroutine: the template’s render_async, which awaits awaitable
fastapi.response(): Renders a template to a fastapi.Response. (As in fastapi-chameleon, every keyword
fastapi.response_async(): response as a coroutine, rendering with render_async.
fastapi.not_found(): Ends the current @template view with a 404 page: template_file
fastapi.error(): Ends the current @template view with an error page: template_file rendered with
fastapi.generic_error(): fastapi-chameleon’s name and signature for error().
fastapi.clear(): Forgets the views’ process-wide configuration, so a later configure() /
fastapi.check_views(): Raises chameleon_rs.web.DecoratorOrderError if a route of app (sub-routers and

Starlette

Jinja2Templates’ API for chameleon-rs, and the decorator API. Imports Starlette only when imported itself.

starlette.Templates: Starlette’s Jinja2Templates for chameleon-rs templates.
starlette.configure(): Configures where templates live and how they load, for the whole process (the same as
starlette.global_init(): fastapi-chameleon’s setup call, for Starlette: configures the views’ templates only
starlette.template(): Decorates a Starlette endpoint (a function, or a method of an HTTPEndpoint class;
starlette.render(): Renders a template (path relative to the template folder) to a str.
starlette.render_async(): render as a coroutine: the template’s render_async, which awaits awaitable
starlette.response(): Renders a template to an HTMLResponse (every keyword but content_type and
starlette.response_async(): response as a coroutine, rendering with render_async.
starlette.not_found(): Ends the current @template endpoint with a 404 page: template_file rendered with
starlette.error(): Ends the current @template endpoint with an error page: template_file rendered
starlette.generic_error(): fastapi-chameleon’s name and signature for error().
starlette.clear(): Forgets the views’ process-wide configuration, so a later configure() /
starlette.check_views(): Raises chameleon_rs.web.DecoratorOrderError if a route of app (a Starlette app

Robyn

chameleon-robyn’s API, built in. Imports Robyn only when imported itself.

robyn.configure(): Configures where templates live and how they load, for the whole process (the same as
robyn.global_init(): chameleon-robyn’s setup call: configures the handlers’ templates only (partials keep
robyn.template(): Decorates a Robyn route handler (sync or async) to render a template with what it
robyn.render(): Renders a template (path relative to the template folder) to a str (no response):
robyn.render_async(): render as a coroutine: the template’s render_async, which awaits awaitable
robyn.response(): Renders a template into a robyn.Response with ``Content-Type: {content_type};
robyn.response_async(): response as a coroutine, rendering with render_async.
robyn.not_found(): Ends the current @template handler with a 404 page: template_file
robyn.error(): Ends the current @template handler with an error page: template_file rendered as
robyn.generic_error(): fastapi-chameleon’s name and signature for error().
robyn.clear(): Forgets the handlers’ process-wide configuration, so a later configure() /
robyn.check_views(): Raises chameleon_rs.web.DecoratorOrderError if a route of app (a Robyn app, with
robyn.ChameleonTemplate: Chameleon templates through Robyn’s TemplateInterface, as its JinjaTemplate:

Litestar

Litestar’s template engine interface for chameleon-rs, and the decorator API. Imports Litestar only when imported itself.

litestar.ChameleonEngine: Litestar’s TemplateEngineProtocol for chameleon-rs templates:
litestar.ChameleonTemplate: A page template as Litestar’s TemplateProtocol: render(**context) renders it with
litestar.Template: Litestar’s Template response, served as text/html when Litestar cannot guess the
litestar.configure(): Configures where templates live and how they load, for the whole process (the same as
litestar.global_init(): The other integrations’ setup call, for Litestar: configures the handlers’ templates only
litestar.template(): Decorates a Litestar route handler function (sync or async; a Controller method too)
litestar.render(): Renders a template (path relative to the template folder) to a str.
litestar.render_async(): render as a coroutine: the template’s render_async, which awaits awaitable
litestar.response(): Renders a template into a litestar.Response (every keyword but content_type and
litestar.response_async(): response as a coroutine, rendering with render_async.
litestar.not_found(): Ends the current @template handler with a 404 page: template_file rendered with
litestar.error(): Ends the current @template handler with an error page: template_file rendered
litestar.generic_error(): fastapi-chameleon’s name and signature for error().
litestar.clear(): Forgets the handlers’ process-wide configuration, so a later configure() /
litestar.check_views(): Raises chameleon_rs.web.DecoratorOrderError if a route of app (a Litestar app or

Errors and web helpers

Exceptions, and the pieces shared by the framework integrations.

TemplateError: Base class for compile-time template errors (ParseError, CompilationError, ExpressionError).
web.TemplateError: A template integration was configured or used incorrectly: no template folder
web.ErrorPage: Raised inside a decorated view to answer with an error page: the decorator renders
web.NotFound: Raised by not_found(): the decorator renders template_file (errors/404.pt
web.TemplateNotFound: No template of that name, or a name reaching outside the template folder: raised by
web.DecoratorOrderError: A view was registered with its framework before @template wrapped it (@template
web.model_of(): The template model a view returned: a dict as is; any other Mapping as a

Compatibility

Make import chameleon resolve to chameleon-rs, or check both engines side by side.

compat.install(): Makes import chameleon (and its submodules) resolve to chameleon-rs and, with
shadow.install(): Starts shadow mode: from now on, a sample_rate share of the outermost renders of
shadow.uninstall(): Stops shadow mode, restoring stock Chameleon’s render methods.
shadow.ShadowDifference: One render whose outcome differs between the engines.