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.