Chameleon

Common errors

• ModuleNotFoundError: No module named 'chameleon'

  cause The 'chameleon' package is not installed in the current Python environment.
  fix Run `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)

  cause This usually indicates an incompatibility between the requested package version and your Python version, or a corrupted pip cache.
  fix Verify 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: ('...', ...)

  cause An error occurred during the evaluation of a Python expression within the template. The traceback will usually point to the specific expression and context.
  fix Examine 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

  cause 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.
  fix Carefully 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.

Warnings

• breaking Chameleon 4.x dropped support for Python versions earlier than 3.9.
  Fix: Ensure your project runs on Python 3.9 or newer. Upgrade your Python environment if necessary.
• breaking Backslash-escaping of dollar-based string interpolation is no longer supported. To render a literal dollar sign, use `$$`.
  Fix: Replace `\$` with `$$` in your templates if you need a literal dollar sign.
• gotcha Chameleon uses Python as the default expression language, unlike traditional Zope Page Templates which might default to path expressions.
  Fix: Be 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.
• gotcha Template 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.
  Fix: Avoid 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.
• deprecated The `literal_false` flag has been removed. Use `boolean_attributes` for similar behavior regarding boolean attributes.
  Fix: Migrate your template configuration to use the `boolean_attributes` option instead of `literal_false`. Consult the official documentation for `boolean_attributes` usage.

Install

• pip install chameleon Latest stable version

Imports

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

Quickstart

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)