chameleon_robyn 0.1.0__tar.gz

chameleon_robyn-0.1.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+venv
+.venv
+.claude/settings.local.json

chameleon_robyn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Kennedy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chameleon_robyn-0.1.0/PKG-INFO

@@ -0,0 +1,370 @@
+Metadata-Version: 2.4
+Name: chameleon_robyn
+Version: 0.1.0
+Summary: Adds integration of the Chameleon template language to Robyn.
+Project-URL: Homepage, https://github.com/mikeckennedy/chameleon-robyn
+Author-email: Michael Kennedy <michael@talkpython.fm>
+License: MIT
+License-File: LICENSE
+Keywords: Chameleon,Robyn,integration,template
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.10
+Requires-Dist: chameleon
+Requires-Dist: robyn>=0.60
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: chameleon-partials; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# 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.
+
+Use [Chameleon](https://chameleon.readthedocs.io/) page templates in your [Robyn](https://robyn.tech/) web applications. If you've used Chameleon with Pyramid, Flask, or FastAPI, you'll feel right at home - same `.pt` templates, same TAL/TALES/METAL expressions, now running on Robyn's blazing-fast Rust runtime.
+
+## Installation
+
+```bash
+uv pip install chameleon-robyn
+```
+
+This pulls in `chameleon` and `robyn` as dependencies.
+
+## Quick start
+
+**1. Set up your project structure:**
+
+```
+my_app/
+├── app.py
+└── templates/
+    └── home/
+        └── index.pt
+```
+
+**2. Create a template** (`templates/home/index.pt`):
+
+```xml
+<!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`):
+
+```python
+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 `@template` decorator
+
+The decorator is the main way you'll use this package. It intercepts your handler's return value and renders it through a Chameleon template.
+
+### Explicit template path
+
+```python
+@app.get('/episodes')
+@chameleon_robyn.template('episodes/list.pt')
+def episode_list(request):
+    return {'episodes': get_all_episodes()}
+```
+
+### Auto-naming (convention over configuration)
+
+If you omit the template path, it's derived from the module and function name. A function called `index` in a module called `home_views` looks for `home_views/index.pt` (falling back to `home_views/index.html`):
+
+```python
+# Looks for templates/home_views/index.pt
+@app.get('/')
+@chameleon_robyn.template()
+def index(request):
+    return {'message': 'Hello!'}
+```
+
+You can even skip the parentheses:
+
+```python
+@app.get('/')
+@chameleon_robyn.template
+def index(request):
+    return {'message': 'Hello!'}
+```
+
+### Async handlers - just works
+
+```python
+@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
+
+```python
+# 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.)
+
+If your handler returns a Robyn `Response` object directly, the decorator passes it through untouched. This is how you handle redirects, custom error responses, or anything that shouldn't be rendered through a template:
+
+```python
+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'}),
+    )
+```
+
+## Friendly 404 pages
+
+Call `not_found()` from any decorated handler to render a 404 page:
+
+```python
+@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}
+```
+
+By default it renders `errors/404.pt`, but you can specify any template:
+
+```python
+chameleon_robyn.not_found(four04template_file='errors/custom_404.pt')
+```
+
+## Lower-level API
+
+Sometimes you need to render a template outside of a decorator - in middleware, error handlers, or helper functions.
+
+### `render()` - get an HTML string
+
+```python
+html = chameleon_robyn.render('emails/welcome.pt', username='Michael')
+# Returns a string, no Response wrapping
+```
+
+### `response()` - get a Robyn Response
+
+```python
+resp = chameleon_robyn.response('errors/500.pt', status_code=500, error=str(e))
+# Returns a fully-formed Robyn Response object
+```
+
+## `ChameleonTemplate` class (Robyn's TemplateInterface)
+
+If you prefer Robyn's built-in template pattern, `ChameleonTemplate` implements `TemplateInterface` - the same abstract base class that Robyn's `JinjaTemplate` uses:
+
+```python
+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()`.
+
+## `global_init()` reference
+
+```python
+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
+
+Chameleon's default namespace rules reject attributes like `@click` or `:class` because they look like XML namespace prefixes. If you're using Alpine.js, htmx, or similar libraries, set `restricted_namespace=False`:
+
+```python
+chameleon_robyn.global_init(template_folder, restricted_namespace=False)
+```
+
+This tells Chameleon to allow any attribute syntax in your templates.
+
+## Works with chameleon-partials
+
+[chameleon-partials](https://github.com/mikeckennedy/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:
+
+```python
+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:
+
+```python
+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 ..."`:
+
+```xml
+<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.
+
+### Setup
+
+Clone the repo and install with the extras you need:
+
+```bash
+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, friendly 404 pages, search with query parameters, and an XML feed with a custom content type.
+
+```bash
+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](https://github.com/mikeckennedy/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.
+
+```bash
+python example-partials/app.py
+# Open http://127.0.0.1:5555
+```
+
+Compare the two to see how partials reduce template duplication - the episode list and search results templates go from inline card markup to a single `tal:replace` call each.
+
+## Template language cheat sheet
+
+Chameleon uses TAL (Template Attribute Language) - a few patterns to get you going:
+
+```xml
+<!-- 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](https://chameleon.readthedocs.io/)
+
+## License
+
+MIT

chameleon_robyn-0.1.0/README.md

@@ -0,0 +1,342 @@
+# 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.
+
+Use [Chameleon](https://chameleon.readthedocs.io/) page templates in your [Robyn](https://robyn.tech/) web applications. If you've used Chameleon with Pyramid, Flask, or FastAPI, you'll feel right at home - same `.pt` templates, same TAL/TALES/METAL expressions, now running on Robyn's blazing-fast Rust runtime.
+
+## Installation
+
+```bash
+uv pip install chameleon-robyn
+```
+
+This pulls in `chameleon` and `robyn` as dependencies.
+
+## Quick start
+
+**1. Set up your project structure:**
+
+```
+my_app/
+├── app.py
+└── templates/
+    └── home/
+        └── index.pt
+```
+
+**2. Create a template** (`templates/home/index.pt`):
+
+```xml
+<!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`):
+
+```python
+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 `@template` decorator
+
+The decorator is the main way you'll use this package. It intercepts your handler's return value and renders it through a Chameleon template.
+
+### Explicit template path
+
+```python
+@app.get('/episodes')
+@chameleon_robyn.template('episodes/list.pt')
+def episode_list(request):
+    return {'episodes': get_all_episodes()}
+```
+
+### Auto-naming (convention over configuration)
+
+If you omit the template path, it's derived from the module and function name. A function called `index` in a module called `home_views` looks for `home_views/index.pt` (falling back to `home_views/index.html`):
+
+```python
+# Looks for templates/home_views/index.pt
+@app.get('/')
+@chameleon_robyn.template()
+def index(request):
+    return {'message': 'Hello!'}
+```
+
+You can even skip the parentheses:
+
+```python
+@app.get('/')
+@chameleon_robyn.template
+def index(request):
+    return {'message': 'Hello!'}
+```
+
+### Async handlers - just works
+
+```python
+@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
+
+```python
+# 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.)
+
+If your handler returns a Robyn `Response` object directly, the decorator passes it through untouched. This is how you handle redirects, custom error responses, or anything that shouldn't be rendered through a template:
+
+```python
+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'}),
+    )
+```
+
+## Friendly 404 pages
+
+Call `not_found()` from any decorated handler to render a 404 page:
+
+```python
+@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}
+```
+
+By default it renders `errors/404.pt`, but you can specify any template:
+
+```python
+chameleon_robyn.not_found(four04template_file='errors/custom_404.pt')
+```
+
+## Lower-level API
+
+Sometimes you need to render a template outside of a decorator - in middleware, error handlers, or helper functions.
+
+### `render()` - get an HTML string
+
+```python
+html = chameleon_robyn.render('emails/welcome.pt', username='Michael')
+# Returns a string, no Response wrapping
+```
+
+### `response()` - get a Robyn Response
+
+```python
+resp = chameleon_robyn.response('errors/500.pt', status_code=500, error=str(e))
+# Returns a fully-formed Robyn Response object
+```
+
+## `ChameleonTemplate` class (Robyn's TemplateInterface)
+
+If you prefer Robyn's built-in template pattern, `ChameleonTemplate` implements `TemplateInterface` - the same abstract base class that Robyn's `JinjaTemplate` uses:
+
+```python
+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()`.
+
+## `global_init()` reference
+
+```python
+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
+
+Chameleon's default namespace rules reject attributes like `@click` or `:class` because they look like XML namespace prefixes. If you're using Alpine.js, htmx, or similar libraries, set `restricted_namespace=False`:
+
+```python
+chameleon_robyn.global_init(template_folder, restricted_namespace=False)
+```
+
+This tells Chameleon to allow any attribute syntax in your templates.
+
+## Works with chameleon-partials
+
+[chameleon-partials](https://github.com/mikeckennedy/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:
+
+```python
+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:
+
+```python
+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 ..."`:
+
+```xml
+<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.
+
+### Setup
+
+Clone the repo and install with the extras you need:
+
+```bash
+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, friendly 404 pages, search with query parameters, and an XML feed with a custom content type.
+
+```bash
+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](https://github.com/mikeckennedy/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.
+
+```bash
+python example-partials/app.py
+# Open http://127.0.0.1:5555
+```
+
+Compare the two to see how partials reduce template duplication - the episode list and search results templates go from inline card markup to a single `tal:replace` call each.
+
+## Template language cheat sheet
+
+Chameleon uses TAL (Template Attribute Language) - a few patterns to get you going:
+
+```xml
+<!-- 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](https://chameleon.readthedocs.io/)
+
+## License
+
+MIT

chameleon_robyn-0.1.0/chameleon_robyn/__init__.py

@@ -0,0 +1,36 @@
+"""chameleon-robyn - Adds integration of the Chameleon template language to Robyn."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _get_version
+
+from .engine import (
+    ChameleonTemplate,
+    clear,
+    global_init,  # noqa: I001
+    not_found,
+    render,
+    response,
+    template,
+)
+from .exceptions import (
+    ChameleonRobynException,
+    ChameleonRobynNotFoundException,
+)
+
+try:
+    __version__ = _get_version('chameleon_robyn')
+except PackageNotFoundError:
+    __version__ = '0.0.0'
+
+__author__ = 'Michael Kennedy <michael@talkpython.fm>'
+__all__ = [
+    'template',
+    'global_init',
+    'clear',
+    'not_found',
+    'render',
+    'response',
+    'ChameleonTemplate',
+    'ChameleonRobynException',
+    'ChameleonRobynNotFoundException',
+]

chameleon_robyn-0.1.0/chameleon_robyn/engine.py

@@ -0,0 +1,196 @@
+import inspect
+import os
+from functools import wraps
+from typing import Any, Callable, Optional, Protocol, Union, runtime_checkable
+
+from chameleon import PageTemplate, PageTemplateLoader
+from robyn import Headers, Response, status_codes
+
+from chameleon_robyn.exceptions import (
+    ChameleonRobynException,
+    ChameleonRobynNotFoundException,
+)
+
+__templates: Optional[PageTemplateLoader] = None
+template_path: Optional[str] = None
+
+
+def global_init(template_folder: str, auto_reload=False, cache_init=True, restricted_namespace=True):
+    """
+    Initialize the Chameleon template engine.
+
+    Args:
+        template_folder: Path to the template directory
+        auto_reload: Whether to auto-reload templates on change
+        cache_init: Whether to cache initialization (skip if already initialized)
+        restricted_namespace: If True, only TAL/METAL/i18n namespaces are allowed.
+                            If False, allows attribute-based JS frameworks like Alpine.js
+                            to use shorthand syntax (@click, :class, etc.)
+    """
+    global __templates, template_path
+
+    if __templates and cache_init:
+        return
+
+    if not template_folder:
+        msg = 'The template_folder must be specified.'
+        raise ChameleonRobynException(msg)
+
+    if not os.path.isdir(template_folder):
+        msg = f"The specified template folder must be a folder, it's not: {template_folder}"
+        raise ChameleonRobynException(msg)
+
+    template_path = template_folder
+    __templates = PageTemplateLoader(
+        template_folder,
+        auto_reload=auto_reload,
+        restricted_namespace=restricted_namespace,
+    )
+
+
+def clear():
+    global __templates, template_path
+    __templates = None
+    template_path = None
+
+
+def render(template_file: str, **template_data: dict) -> str:
+    if not __templates:
+        raise ChameleonRobynException('You must call global_init() before rendering templates.')
+
+    page: PageTemplate = __templates[template_file]
+    return page.render(encoding='utf-8', **template_data)
+
+
+def response(template_file: str, content_type='text/html', status_code=200, **template_data) -> Response:
+    html = render(template_file, **template_data)
+    return Response(
+        status_code=status_code,
+        description=html,
+        headers=Headers({'Content-Type': f'{content_type}; charset=utf-8'}),
+    )
+
+
+def template(
+    template_file: Optional[Union[Callable, str]] = None,
+    content_type: str = 'text/html',
+    status_code: int = 200,
+):
+    """
+    Decorate a Robyn view method to render an HTML response.
+
+    :param template_file: Optional, the Chameleon template file (path relative to template folder, *.pt).
+    :param content_type: The mimetype response (defaults to text/html).
+    :param status_code: Default status code for responses.
+    :return: Decorator for Robyn route handlers
+    """
+
+    wrapped_function = None
+    if callable(template_file):
+        wrapped_function = template_file
+        template_file = None
+
+    def response_inner(f):
+        nonlocal template_file
+        global template_path
+
+        if not template_path:
+            template_path = 'templates'
+
+        if not template_file:
+            module = f.__module__
+            if '.' in module:
+                module = module.split('.')[-1]
+            view = f.__name__
+            template_file = f'{module}/{view}.html'
+
+            if not os.path.exists(os.path.join(template_path, template_file)):
+                template_file = f'{module}/{view}.pt'
+
+        @wraps(f)
+        def sync_view_method(*args, **kwargs) -> Response:
+            try:
+                response_val = f(*args, **kwargs)
+                return __render_response(template_file, response_val, content_type, status_code)
+            except ChameleonRobynNotFoundException as nfe:
+                return __render_response(nfe.template_file, {}, 'text/html', 404)
+
+        @wraps(f)
+        async def async_view_method(*args, **kwargs) -> Response:
+            try:
+                response_val = await f(*args, **kwargs)
+                return __render_response(template_file, response_val, content_type, status_code)
+            except ChameleonRobynNotFoundException as nfe:
+                return __render_response(nfe.template_file, {}, 'text/html', 404)
+
+        if inspect.iscoroutinefunction(f):
+            return async_view_method
+        else:
+            return sync_view_method
+
+    return response_inner(wrapped_function) if wrapped_function else response_inner
+
+
+def __is_response(resp) -> bool:
+    return isinstance(resp, Response)
+
+
+def __render_response(template_file: str, response_val: Any, content_type: str, status_code: int = 200) -> Response:
+    if __is_response(response_val):
+        return response_val
+
+    if template_file and not isinstance(response_val, dict):
+        msg = f'Invalid return type {type(response_val)}, we expected a dict or Response as the return value.'
+        raise ChameleonRobynException(msg)
+
+    model = response_val
+
+    html = render(template_file, **model)
+    return Response(
+        status_code=status_code,
+        description=html,
+        headers=Headers({'Content-Type': f'{content_type}; charset=utf-8'}),
+    )
+
+
+def not_found(four04template_file: str = 'errors/404.pt'):
+    msg = 'The URL resulted in a 404 response.'
+
+    if four04template_file and four04template_file.strip():
+        raise ChameleonRobynNotFoundException(msg, four04template_file)
+    else:
+        raise ChameleonRobynNotFoundException(msg)
+
+
+@runtime_checkable
+class TemplateInterface(Protocol):
+    """Protocol matching Robyn's TemplateInterface without importing Jinja2."""
+
+    def render_template(self, *args, **kwargs) -> Response: ...
+
+
+class ChameleonTemplate(TemplateInterface):
+    """Chameleon template engine implementing Robyn's TemplateInterface."""
+
+    def __init__(
+        self,
+        directory: str,
+        auto_reload=False,
+        encoding='utf-8',
+        restricted_namespace=True,
+    ):
+        self.loader = PageTemplateLoader(
+            directory,
+            auto_reload=auto_reload,
+            restricted_namespace=restricted_namespace,
+        )
+        self.encoding = encoding
+
+    def render_template(self, template_name: str, **kwargs) -> Response:
+        page: PageTemplate = self.loader[template_name]
+        rendered = page.render(encoding=self.encoding, **kwargs)
+        return Response(
+            status_code=status_codes.HTTP_200_OK,
+            description=rendered,
+            headers=Headers({'Content-Type': 'text/html; charset=utf-8'}),
+        )

chameleon_robyn-0.1.0/chameleon_robyn/exceptions.py

@@ -0,0 +1,13 @@
+from typing import Optional
+
+
+class ChameleonRobynException(Exception):
+    pass
+
+
+class ChameleonRobynNotFoundException(ChameleonRobynException):
+    def __init__(self, message: Optional[str] = None, four04template_file: str = 'errors/404.pt'):
+        super().__init__(message)
+
+        self.template_file: str = four04template_file
+        self.message: Optional[str] = message

chameleon_robyn-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "chameleon_robyn"
+version = "0.1.0"
+description = "Adds integration of the Chameleon template language to Robyn."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Michael Kennedy", email = "michael@talkpython.fm" }
+]
+keywords = ["Robyn", "Chameleon", "template", "integration"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15"
+]
+dependencies = [
+    "robyn>=0.60",
+    "Chameleon"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+]
+examples = [
+    "chameleon-partials",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/mikeckennedy/chameleon-robyn"
+
+
+[build-system]
+requires = ["hatchling>=1.21.0", "hatch-vcs>=0.3.0"]
+build-backend = "hatchling.build"
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.sdist]
+packages = ["chameleon_robyn"]
+exclude = [
+    "/.github",
+    "/dist",
+    "/tests",
+    "/example",
+    "/example-partials",
+    "/venv",
+    "/.venv",
+    "ruff.toml",
+    "requirements-dev.txt",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["chameleon_robyn"]
+exclude = [
+    "/.github",
+    "/dist",
+    "/tests",
+    "/example",
+    "/example-partials",
+    "/venv",
+    "/.venv",
+    "ruff.toml",
+    "requirements-dev.txt",
+]