Install & Compatibility
Where this runs
tested against v4.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.226s · 18.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.216s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PageTemplate
✓ from chameleon import PageTemplate
For creating templates directly from a string.
PageTemplateFile
✓ from chameleon import PageTemplateFile
For loading templates from a file path.
PageTemplateLoader
✓ from chameleon import PageTemplateLoader
For loading multiple templates from a directory, relative to a base path.
This quickstart demonstrates creating a `PageTemplate` from a string, defining a variable using `tal:define`, interpolating variables with `${...}`, and passing a context object for dynamic data. It then renders the template and prints the resulting HTML.
from chameleon import PageTemplate
template_string = """
<div tal:define="name 'World'">
<h1>Hello, ${name}!</h1>
<p>Today is ${context.today.strftime('%Y-%m-%d')}.</p>
</div>
"""
template = PageTemplate(template_string)
# Render the template with a 'context' dictionary
import datetime
output = template(context={'today': datetime.date.today()})
print(output)
Debug
Known issues
breakingChameleon 4.x dropped support for Python versions earlier than 3.9.fixEnsure your project runs on Python 3.9 or newer. Upgrade your Python environment if necessary.
affects: >=4.0.0
breakingBackslash-escaping of dollar-based string interpolation is no longer supported. To render a literal dollar sign, use `$$`.fixReplace `\$` with `$$` in your templates if you need a literal dollar sign.
affects: >=4.0.0 (exact version unclear, but around 3.x to 4.x transition)
gotchaChameleon uses Python as the default expression language, unlike traditional Zope Page Templates which might default to path expressions.fixBe aware that expressions within `tal:` attributes (e.g., `tal:content="expression"`) will be evaluated as Python code. If you previously relied on Zope's path expressions without explicit `python:` prefixes, you might need to adjust your syntax.
affects: All versions
gotchaTemplate variable names starting with two or more leading underscores are disallowed as they are reserved for internal compiler use. Also, certain Python built-ins (e.g., `int`, `float`, `str`, `None`, `True`, `False`) cannot be redefined within templates.fixAvoid using variable names with two or more leading underscores (e.g., `__my_var__`). Do not attempt to redefine Python built-in types or keywords within your template's scope.
affects: All versions
deprecatedThe `literal_false` flag has been removed. Use `boolean_attributes` for similar behavior regarding boolean attributes.fixMigrate your template configuration to use the `boolean_attributes` option instead of `literal_false`. Consult the official documentation for `boolean_attributes` usage.
affects: >=4.0.0 (removed around 4.0.0)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'chameleon'
The 'chameleon' package is not installed in the current Python environment.
fixRun `pip install chameleon` to install the library. Ensure you are in the correct virtual environment if you are using one.
ERROR: Could not find a version that satisfies the requirement chameleon (from versions: none)
This usually indicates an incompatibility between the requested package version and your Python version, or a corrupted pip cache.
fixVerify your Python version meets the `chameleon` requirements (>=3.9 for current versions) using `python --version`. Upgrade `pip` (`pip install --upgrade pip`), clear the pip cache, or try specifying a compatible version of `chameleon` if you cannot upgrade Python.
chameleon.exc.ExpressionError: ('...', ...)
An error occurred during the evaluation of a Python expression within the template. The traceback will usually point to the specific expression and context.
fixExamine the full traceback provided by `chameleon.exc.ExpressionError`. It often includes the template's filename, line, and column where the error originated, along with the problematic expression and variable scope. Debug the Python expression within your template.
IndentationError: expected an indented block
Although Chameleon compiles to Python, complex `tal:` attribute logic, `metal:` macros, or inline Python blocks might lead to malformed generated Python code if the template syntax is incorrect or ambiguous.
fixCarefully review the `tal:`, `metal:`, or inline Python syntax in your template around the reported line. Ensure proper nesting and valid logical constructs as interpreted by the Page Templates language.
Upgrade
Version history
4.6.0latest on PyPI · released Dec 31, 2024
Audit
Dependencies
No dependency data recorded yet.