Skills

A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project’s documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.

Any agent — install with npx:

npx skills add https://mkennedy.codes/docs/chameleon-flask/

Codex / OpenCode

Tell the agent:
Fetch the skill file at https://mkennedy.codes/docs/chameleon-flask/skill.md and follow the instructions.

Manual — download the skill file:

curl -O https://mkennedy.codes/docs/chameleon-flask/skill.md

Or browse the SKILL.md file.

SKILL.md

---
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

```bash
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](https://mkennedy.codes/docs/chameleon-flask/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs