FAQ

The questions that come up once the shop is open and real customers are clicking things.

Can I use Jinja instead of Chameleon?

Not with this package, but you do not have to choose blind. fastapi-jinja is the sister project with the same shape: one global_init(), one @template decorator, views that return dicts. Swapping between them is mostly a matter of which attribute syntax you prefer.

Does it work with APIRouter?

Yes. Put @router.get(...) on the outside and @fastapi_chameleon.template(...) directly on the function, exactly as with @app.get(...).

Do async views work?

Yes. The decorator detects a coroutine function at decoration time and awaits it. Nothing else changes, and sync and async views can live side by side in the same router.

Can I return a Pydantic model from a view?

No. Return model.model_dump(). Only a dict or a fastapi.Response is accepted, and anything else raises FastAPIChameleonException with a message naming the type it got instead.

How do I pass the request to the template?

Put it in the dict: return {'request': request, 'title': 'Home'}. The template can then read ${request.url.path} or anything else on it. There is no magic request variable, which also means there is nothing to forget to configure.

Can I have more than one template folder?

Not at the same time. There is one loader per process. Use subfolders of a single root and refer to them in template paths, such as admin/users.pt.

Why does my 404 page come back as JSON, or as a 500?

Because not_found() was called from code that is not below a @template-decorated view. The decorator is the thing that turns the exception into a page, and without it the exception is just an exception. Decorate the route, or raise fastapi.HTTPException(404) from undecorated code. See Friendly Error Pages.

Why are my template edits not showing up?

auto_reload is False by default and templates are compiled once. Pass auto_reload=True to global_init() while developing. Note that a second global_init() call does not change the setting unless you pass cache_init=False. See Configuration.

Should I use the template name inference?

If your project is laid out as {module}/{function}.pt and global_init() runs before your view modules are imported, inference is tidy and saves a string per view. If you would rather read the path than remember the rule, name templates explicitly. Both are fully supported. See Decorating Views.

What Python versions are supported?

Python 3.10 and newer. The test suite runs on 3.10 through 3.15.

Where is the full list of errors?

Troubleshooting lists every exception the package or Chameleon raises, what it means, and how to fix it, in the order you should check things.