Skip to main content

chameleon-robyn

Note: This project is very much in the alpha and early stages of development. Feel free to use it, but no promises on API stability for a few versions.

Every web framework eventually asks the same question: how do you turn data into HTML? Robyn answers with Jinja2 out of the box. This package offers a second answer, the one people who built on Pyramid or Zope tend to miss the moment they leave: Chameleon page templates. Same .pt files, same TAL/TALES/METAL expressions, now running on Robyn's Rust-powered runtime.

A Chameleon template is an ordinary HTML file. Open one in a browser before it has ever been rendered and you still see a page, because the logic lives inside attributes the browser ignores. tal:repeat loops, tal:condition hides, and ${...} fills in values with real Python expressions. chameleon-robyn wires those templates into Robyn with a single decorator: your handler returns a dict, and a rendered Response comes out the other side.

Documentation

Full documentation lives at mkennedy.codes/docs/chameleon-robyn. This README covers the same ground in short form; the user guide follows one podcast website from its first page to its last error message and goes deeper on each section:

Coding agents can read llms-full.txt or install the agent skill.

Installation

uv pip install chameleon-robyn

This pulls in chameleon and robyn as dependencies. Python 3.10 or newer is required.

Quick start

Three files, three minutes. Here is the shortest path from an empty folder to a rendered page.

1. Set up your project structure:

my_app/
├── app.py
└── templates/
    └── home/
        └── index.pt

2. Create a template (templates/home/index.pt). It is plain HTML with two new ideas: ${name} drops in a value, and tal:repeat on an element makes that element repeat.

<!DOCTYPE html>
<html>
<body>
    <h1>Hello, ${name}!</h1>
    <ul>
        <li tal:repeat="item items">${item}</li>
    </ul>
</body>
</html>

3. Wire it up (app.py). Three lines matter: the import, the global_init() call that says where templates live, and the decorator above the handler.

from pathlib import Path
from robyn import Robyn
import chameleon_robyn

app = Robyn(__file__)

# Point Chameleon at your templates folder (do this once at startup)
template_folder = (Path(__file__).resolve().parent / 'templates').as_posix()
chameleon_robyn.global_init(template_folder, auto_reload=True)

@app.get('/')
@chameleon_robyn.template('home/index.pt')
async def index(request):
    return {'name': 'World', 'items': ['Robyn', 'Chameleon', 'Python']}

app.start(host='127.0.0.1', port=8000)

That's it. Your handler returns a dict, the @template decorator renders it through the Chameleon template and wraps the result in a Robyn Response. The handler never touched a string of HTML, and it never will. The getting started guide walks through this in more detail.

The @template decorator

A route handler has two jobs: decide what to show, and show it. @template takes the second job away entirely. It intercepts your handler's return value and renders it through a Chameleon template, so the handler reads like a description of the page rather than a construction of it.

Explicit template path

@app.get('/episodes')
@chameleon_robyn.template('episodes/list.pt')
def episode_list(request):
    return {'episodes': get_all_episodes()}

Auto-naming (convention over configuration)

Leave the path out and the template is named after the code that renders it. A function called index in a module called home_views looks for home_views/index.html first and, if that file doesn't exist, uses home_views/index.pt. Your template folder ends up mirroring your view modules, which is a pleasant thing to discover six months later.

# Looks for templates/home_views/index.pt
@app.get('/')
@chameleon_robyn.template()
def index(request):
    return {'message': 'Hello!'}

You can even skip the parentheses:

@app.get('/')
@chameleon_robyn.template
def index(request):
    return {'message': 'Hello!'}

Two details: a script run directly (python app.py) has the module name __main__, so the script's file name is used instead and index() in app.py maps to app/index.pt (an existing __main__/index.pt is still found for apps built on the old behavior). And the name is resolved at the first request, not when the decorator runs, so global_init() can be called after the routes are decorated.

Async handlers - just works

The decorator notices async def and awaits the handler. Nothing to configure.

@app.get('/dashboard')
@chameleon_robyn.template('dashboard.pt')
async def dashboard(request):
    stats = await fetch_stats_from_db()
    return {'stats': stats}

Custom status codes and content types

Templates are not only for HTML pages. An XML feed is a template too, and so is the "created" page after a form post.

# Return a 201 after creating a resource
@app.post('/items')
@chameleon_robyn.template('items/created.pt', status_code=201)
async def create_item(request):
    item = await save_item(request.json())
    return {'item': item}

# Serve an XML feed
@app.get('/feed.xml')
@chameleon_robyn.template('feed.xml', content_type='application/xml')
def xml_feed(request):
    return {'episodes': get_recent_episodes()}

Response pass-through (redirects, errors, etc.)

Sometimes the right answer is not a page at all. If your handler returns a Robyn Response object directly, the decorator steps aside and passes it through untouched. This is how you handle redirects, custom error responses, or anything that shouldn't be rendered through a template:

from robyn import Response, Headers

@app.get('/old-page')
@chameleon_robyn.template('home/index.pt')
def old_page(request):
    # This Response is returned as-is - no template rendering
    return Response(
        status_code=302,
        description='',
        headers=Headers({'Location': '/new-page'}),
    )

Modifying the response after rendering (__response_callback__)

Here is the classic puzzle. A visitor logs in. You want to render the welcome page, which means returning a dict, and you also want to set a session cookie, which means touching the Response. You cannot do both from a dict. Or can you?

Put a callable in your model under the reserved __response_callback__ key and the decorator invokes it with the freshly built Response after rendering:

from robyn import Response

@app.post('/account/login')
@chameleon_robyn.template('account/welcome.pt')
async def login(request):
    user = await authenticate(request)
    if not user:
        return chameleon_robyn.response('account/login_failed.pt', status_code=401)

    token = create_session_token(user)

    def set_session_cookie(resp: Response):
        resp.headers.append('Set-Cookie', f'session={token}; HttpOnly; Path=/')

    return {
        'user': user,
        '__response_callback__': set_session_cookie,
    }

A few details:

  • The key is popped before rendering, so it never reaches your template (and your dict isn't mutated - returning a shared model is fine).
  • Mutate the Response in place; the callback's return value is ignored.
  • The value must be callable - anything else raises ChameleonRobynException.

Everything the decorator does, including the exact return-value contract, is in the decorator guide.

Friendly 404 pages

Sooner or later someone will visit /episodes/9999. What they should get is a page in your site's own clothes that points the way home, not a stack trace. Call not_found() from any decorated handler:

@app.get('/episodes/:episode_id')
@chameleon_robyn.template('episodes/detail.pt')
async def episode_detail(request, episode_id: int):
    episode = await get_episode(episode_id)
    if not episode:
        chameleon_robyn.not_found()  # Renders errors/404.pt with status 404

    return {'episode': episode}

Notice there is no return in front of not_found(). It never returns; the decorator catches what it raises and sends the 404 page instead. By default it renders errors/404.pt, but you can specify any template:

chameleon_robyn.not_found(four04template_file='errors/custom_404.pt')

The 404 template receives a message variable describing the 404, which you can render with ${message} if you want. To supply your own message, raise ChameleonRobynNotFoundException('your text') directly; the decorator handles it the same way. not_found() only works inside @template-decorated handlers; see friendly 404 pages for the alternatives.

Lower-level API

The decorator is the front door. A web app renders HTML in more places than route handlers, though: the body of a welcome email, an error page built in middleware, a fragment assembled in a helper. For those there is a side door.

render() - get an HTML string

html = chameleon_robyn.render('emails/welcome.pt', username='Michael')
# Returns a string, no Response wrapping

response() - get a Robyn Response

resp = chameleon_robyn.response('errors/500.pt', status_code=500, error=str(e))
# Returns a fully-formed Robyn Response object

One reserved name: a template variable called encoding cannot be passed, because Chameleon's own render() takes it as a parameter. The library raises ChameleonRobynException if you try. More in rendering outside handlers.

ChameleonTemplate class (Robyn's TemplateInterface)

If you prefer Robyn's built-in template pattern, ChameleonTemplate implements the same render_template() interface as Robyn's JinjaTemplate (via a structural protocol, so importing chameleon_robyn never pulls in Jinja2):

from chameleon_robyn import ChameleonTemplate

chameleon = ChameleonTemplate('templates/', auto_reload=True)

@app.get('/page')
def page(request):
    return chameleon.render_template('page.pt', title='Hello')

This is a standalone class with its own template loader - it doesn't require global_init(). render_template() always returns a 200 text/html response.

global_init() reference

All configuration is one call at startup. No environment variables, no config files.

chameleon_robyn.global_init(
    template_folder,              # Path to your templates directory (required)
    auto_reload=False,            # Watch for template changes - use True in development
    cache_init=True,              # Skip re-initialization if already called
    restricted_namespace=True,    # Set to False if using Alpine.js, htmx @attributes, etc.
)

Alpine.js / htmx compatibility

Here is a surprise waiting for anyone who adds a sprinkle of Alpine.js to a Chameleon page. Chameleon's default namespace rules reject attributes like @click or :class because they look like XML namespace prefixes it has never heard of. If you're using Alpine.js, htmx, or similar libraries, set restricted_namespace=False:

chameleon_robyn.global_init(template_folder, restricted_namespace=False)

This tells Chameleon to allow any attribute syntax in your templates. Every global_init() setting is described in configuration.

Works with chameleon-partials

The episode card appears on the list page and again in search results. Copying it once is fine; copying it a third time is how layouts drift. chameleon-partials provides render_partial() for rendering sub-templates (think: reusable components). It works alongside chameleon-robyn with no extra configuration - just initialize both at startup:

import chameleon_partials
import chameleon_robyn

chameleon_robyn.global_init(template_folder, auto_reload=dev_mode)
chameleon_partials.register_extensions(template_folder, auto_reload=dev_mode)

Then pass render_partial through your template context:

import chameleon_partials

@app.get('/')
@chameleon_robyn.template('home/index.pt')
def index(request):
    return {
        'render_partial': chameleon_partials.render_partial,
        'episodes': get_episodes(),
    }

And use it in your templates with tal:replace="structure ...":

<div tal:repeat="ep episodes">
    <div tal:replace="structure render_partial('shared/episode_card.pt', ep=ep)" />
</div>

Note: use tal:replace="structure ..." (not ${structure ...}) when rendering partials. The structure keyword tells Chameleon to insert the HTML without escaping, and tal:replace swaps out the placeholder element entirely.

Example apps

The repo includes two example apps you can run to see everything in action. Both are the website for a small podcast: episodes, guests, search, a feed, and the occasional lost visitor.

Setup

Clone the repo and install with the extras you need:

git clone https://github.com/mikeckennedy/chameleon-robyn.git
cd chameleon-robyn
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate

# Install the package with example dependencies
pip install -e ".[examples]"

example/ - Core features

A Robyn app demonstrating the @template decorator, sync and async handlers, METAL macro layout inheritance, response pass-through redirects, a __response_callback__ cookie example, friendly 404 pages, search with query parameters, and an XML feed with a custom content type.

python example/app.py
# Open http://127.0.0.1:5555

example-partials/ - With chameleon-partials

The same app, but refactored to use chameleon-partials for reusable template components. The episode card markup lives in a single shared/episode_card.pt partial that's shared across the episodes list and search results pages.

python example-partials/app.py
# Open http://127.0.0.1:5555

Open the two episode list templates side by side and watch a block of card markup collapse into a single tal:replace call.

Template language cheat sheet

Chameleon uses TAL (Template Attribute Language). Most template languages ask you to learn a second syntax; Chameleon asks you to learn a handful of attributes. Here are the ones you will reach for every day:

<!-- Variable substitution -->
<h1>${title}</h1>
<p>${user.name}</p>

<!-- HTML-safe output (skip auto-escaping) -->
<div tal:replace="structure rich_html_content" />

<!-- Conditionals -->
<div tal:condition="show_banner">Special offer!</div>
<div tal:condition="not items">Nothing here yet.</div>

<!-- Loops -->
<li tal:repeat="item items">${item.name} - $${item.price}</li>

<!-- Repeat with index -->
<tr tal:repeat="row data" class="${'odd' if repeat.row.odd else 'even'}">
    <td>${repeat.row.number}. ${row.title}</td>
</tr>

<!-- Attributes -->
<a href="/items/${item.id}" class="${'active' if is_current else ''}">
    ${item.name}
</a>

<!-- Layout inheritance with METAL macros -->
<!-- layout.pt -->
<html>
<body>
    <main metal:define-slot="content">Default content</main>
</body>
</html>

<!-- page.pt -->
<metal:block use-macro="load: shared/layout.pt">
<div metal:fill-slot="content">
    <h1>My page content here</h1>
</div>
</metal:block>

Full docs: chameleon.readthedocs.io. The writing templates guide covers layouts, escaping, and partials in more depth.

Testing and troubleshooting

The best thing about a decorated handler is that it is still a function. Tests call it directly and assert on the returned Robyn Response, with no server to start; see testing your handlers. When something goes wrong, errors and how to fix them is a field guide to every exception the library and Chameleon raise, and what to change.

License

MIT

Metadata

Release files for chameleon_robyn 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for chameleon_robyn 0.1.3
File Size Uploaded Provenance Actions
chameleon_robyn-0.1.3.tar.gz 15.1 kB Without provenance Details for chameleon_robyn-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for chameleon_robyn 0.1.3
File Interpreter ABI Platform Actions
chameleon_robyn-0.1.3-py3-none-any.whl Python 3 none any Details for chameleon_robyn-0.1.3-py3-none-any.whl

Total release size: 30.2 kB

Release files / chameleon_robyn-0.1.3.tar.gz

Download URL chameleon_robyn-0.1.3.tar.gz
Size 15.1 kB
Tags Source
SHA-256 checksum
How to use checksums
01793e4dfd9175c0213b2f2eb14f5a85f118f1a357a6bc97624444a7b0d79d61
BLAKE2b-256 checksum
How to use checksums
9276b97e379145bb1392a5496b540946431246b8b6023591f4f99a0905a0942a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / chameleon_robyn-0.1.3-py3-none-any.whl

Download URL chameleon_robyn-0.1.3-py3-none-any.whl
Size 15.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1d6ab0164d06ebb499c61deefbcdb2a90a101ba96c8a69f9709dd8bc7082a341
BLAKE2b-256 checksum
How to use checksums
1f1f200dca1d4ccd76d1761c1c897b840770c7b9467cd6f56ee064feae1d7345
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for chameleon_robyn 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page