Configuration

There is pleasingly little to configure. One function, three parameters, and no environment variables, settings files, or command-line flags hiding behind them. Everything the engine knows, it learned from a single global_init() call at startup.

global_init() parameters

Parameter Type Default Effect
template_folder str or os.PathLike required Root folder for every template path. Must exist and be a directory, otherwise FastAPIChameleonException is raised.
auto_reload bool False When True, Chameleon checks template files for changes on each use and recompiles them. When False, each template is compiled once per process.
cache_init bool True When True, a call made after the engine is already initialized is ignored. When False, the call replaces the loader and folder.

Every row in that table was checked against the source and then by running it. The auto_reload flag is handed straight to Chameleon’s PageTemplateLoader, so its behaviour is Chameleon’s behaviour.

Calling global_init() more than once

This is the one place people get tripped up, because the default is to politely ignore you.

Situation Result
Second call, cache_init=True (default) Silently ignored. The first folder and auto_reload setting stay in effect.
Second call, cache_init=False New loader and folder take effect for every template rendered from now on.
engine.clear() then global_init() Same as a first call.

The consequence: you cannot flip auto_reload by calling global_init() a second time with the defaults. The engine will keep whatever it was told first. Pass cache_init=False, or call fastapi_chameleon.engine.clear() and start over. This design is deliberate. It means a library or a plugin that calls global_init() defensively cannot stomp on the app’s own configuration.

Development versus production

import os
from pathlib import Path

import fastapi_chameleon

dev_mode = os.environ.get('APP_ENV', 'dev') == 'dev'  # your own switch, the package reads no env vars

BASE_DIR = Path(__file__).resolve().parent
fastapi_chameleon.global_init(BASE_DIR / 'templates', auto_reload=dev_mode)

With auto_reload=False, Chameleon compiles each template to Python the first time it is used and reuses that compiled version for the life of the process. Rendering a page becomes a function call, which is why Chameleon has a reputation for speed. That is the setting you want under load. With auto_reload=True, every use checks the file’s modification time first. Cheap, but not free, and pointless on a server where nobody is editing templates.

The decorator

@template(template_file=None, mimetype='text/html') has two options:

Parameter Default Effect
template_file None Template path relative to the folder. None means infer {module}/{function}.html, then .pt.
mimetype 'text/html' Content type of the response for a rendered dict. Ignored for error pages.

There is no status_code parameter on the decorator, and that is on purpose. A rendered dict is always a 200. For another status use response(), and for error pages use generic_error(), each of which makes the status visible at the call site instead of hiding it in a decorator argument.

Where global_init() goes

Call it at import time in the module that creates the app, before the view modules are imported. When views live in their own module, the order looks like this:

# main.py
import fastapi
import fastapi_chameleon

app = fastapi.FastAPI()
fastapi_chameleon.global_init('templates')

from views import home  # noqa: E402  imported after init on purpose

app.include_router(home.router)

The order matters only for views that let the decorator infer the template name. Views with explicit template names resolve them at request time against whatever folder is configured then, so they are indifferent to import order.