How It Works
The whole library is three short modules, and you can read engine.py in the time it takes to make coffee. But the behaviour that matters is about timing: what happens once when your app imports, what happens on every request, and how an error page gets from a function three layers deep back up to the browser. Know those three and every rule in the rest of this guide becomes obvious.
Act one: the engine
global_init() stores two module-level values in fastapi_chameleon.engine: a Chameleon PageTemplateLoader and the template folder path. That is the entire state of the library. Every render in the process goes through that one loader, which is why global_init() is called once, why a second call is ignored by default, and why tests clear it between runs with engine.clear().
Think of it as the shop’s single key cabinet. Everyone who needs a template goes to the same cabinet, and you set up the cabinet before opening the doors.
Act two: decoration time
@template(...) runs when the view module is imported, not when a request arrives. At that moment it makes three decisions and never revisits them:
- Which template. An explicit name is kept as-is. A missing name is derived from the view’s module and function name, and the
.htmlor.ptchoice is made by checking the filesystem once. - Sync or async.
inspect.iscoroutinefunctionpicks a synchronous or asynchronous wrapper. The async wrapper awaits the view, the sync one calls it, and both then render. - The signature. The wrapper is wrapped with
functools.wraps, and template() is typed with ParamSpec-based overloads, so FastAPI’s dependency injection and your type checker both see the original parameters, not*args, **kwargs.
Because the template folder is read at decoration time for name inference, global_init() has to run before the view module is imported. If it has not, the folder defaults to templates relative to the current working directory. This is the single most important timing rule in the package, and it only bites the inferred-name forms.
Act three: request time
A request comes in. FastAPI resolves the dependencies and calls the wrapper, which calls the view and looks at what came back:
- A
fastapi.Responseis returned as-is. The template is never touched. - A
dictis handed to the loader as the template model, and the HTML comes back in afastapi.Responsewith the decorator’smimetypeand status200. - Anything else raises FastAPIChameleonException.
Rendering before global_init() has run raises FastAPIChameleonException too. A template file that does not exist raises ValueError from Chameleon’s loader.
The emergency exits
not_found() and generic_error() do not return. They raise FastAPIChameleonNotFoundException or FastAPIChameleonGenericException, both subclasses of FastAPIChameleonException. The wrapper from act two has a try around the view call that catches exactly those two types, and nothing else. When it catches one, it renders the exception’s template with the exception’s status, always as text/html. Any other exception passes straight through to FastAPI.
That is why the functions work from anywhere below a decorated view: exceptions travel up the call stack for free, so a repository can refuse a request and the decorator at the top turns the refusal into a page. It is also why they do nothing useful outside one. No wrapper, no try, no page.
Template caching
Chameleon compiles each template to a Python module on first use and keeps it in memory. With auto_reload=False, that compiled version serves every request for the rest of the process. With auto_reload=True, the loader checks the file’s modification time before each use and recompiles when it changed. The first request after a deploy pays the compile cost; every request after that is a function call.
Source
The code is short and readable, and reading it is the fastest way to confirm anything on this page: engine.py and exceptions.py.