chameleon-flask

name	chameleon-flask
description	Adds integration of the Chameleon template language to Flask and Quart. Use when writing Python code that uses the chameleon_flask package.
license	MIT
compatibility	Requires Python >=3.10.

chameleon-flask

Adds integration of the Chameleon template language to Flask and Quart.

Installation

pip install chameleon-flask

When to use what

Need	Use
Render a Chameleon template from a Flask/Quart view	@chameleon_flask.template('home/index.pt') on the view function
Return a friendly 404 page from a view	chameleon_flask.not_found()
Build a rendered Response outside a decorated view	chameleon_flask.response(template_file, **model)
Get rendered HTML as a plain string	chameleon_flask.engine.render(template_file, **model)
Use Alpine.js/Vue shorthand attributes in templates	global_init(..., restricted_namespace=False)

API overview

Configuration

Set up the Chameleon template engine once at app startup.

• global_init: Initialize the Chameleon template engine
• engine.clear

Decorating views

Render templates from Flask/Quart view functions (sync or async) and return friendly 404s.

• template: Decorate a Flask or Quart view method to render a Chameleon template
• not_found: Abort the current view and render a friendly 404 page

Direct rendering

Render a template to a Response or raw HTML without the decorator.

• response: Render a Chameleon template directly to a flask.Response
• engine.render

Exceptions

Errors raised by the engine. Importable from chameleon_flask directly or from chameleon_flask.exceptions.

• FlaskChameleonException: Base exception for all chameleon-flask errors
• FlaskChameleonNotFoundException: Raised by not_found() to signal that a view should render a 404 page

Gotchas

1. global_init() is one-shot by default: with cache_init=True, later calls are silently ignored. Pass cache_init=False or call chameleon_flask.engine.clear() to re-initialize.
2. The bare @template form resolves the template file name once, at decoration time — call global_init() before defining views that rely on it.
3. Decorated views must return a dict (the template model) or a Flask/Quart Response; any other return type raises FlaskChameleonException at request time.
4. Chameleon's restricted namespace (the default) rejects Alpine.js/Vue shorthand attributes like @click, :class, and x-data. Pass restricted_namespace=False to global_init() to allow them.
5. The 404 path from not_found() always renders with text/html and status 404; the view's own content_type and status_code do not apply.
6. The decorator keyword is content_type, not mimetype (renamed in an earlier release).

Best practices

• Call global_init(template_folder, auto_reload=dev_mode) exactly once at app startup, before any views are defined.
• Return plain dicts from views; return a Response only for redirects and other pass-through cases.
• Enable auto_reload only during development so templates stay cached in production.
• Use chameleon_flask.response() inside error handlers and other spots where the decorator doesn't fit.

Resources

• Full documentation
• llms.txt — Indexed API reference for LLMs
• llms-full.txt — Comprehensive documentation for LLMs