Tempita

Common errors

• NameError: name 'Template' is not defined

  cause The `Template` class was used without being explicitly imported from the `tempita` module.
  fix Add `from tempita import Template` at the top of your Python file.

• tempita.TemplateError: Syntax error in template (template_name.html:X:Y)

  cause There is a syntax error within the Tempita template string or file, such as a missing `{{endfor}}` or incorrect expression syntax.
  fix Review the template content around the reported line number (X) and column (Y) in the error message for syntax mistakes.

• TypeError: 'str' does not support the buffer interface (or similar UnicodeDecodeError on Python 2)

  cause Attempting to use Tempita 0.6.0+ on a Python 2 environment, or encountering unicode/bytes mixing issues in older versions.
  fix Ensure your environment is running Python 3 for Tempita 0.6.0+. For older Tempita versions, explicitly encode/decode strings to handle Unicode consistently, usually to UTF-8.

Warnings

• breaking Tempita version 0.6.0 and later removes Python 2 support. Projects upgrading to 0.6.0 must be running on Python 3, or they will encounter compatibility errors.
  Fix: Ensure your project is running on Python 3 before upgrading to tempita==0.6.0. If Python 2 compatibility is required, pin to an older version (e.g., `tempita<0.6.0`).
• gotcha Tempita templates execute arbitrary Python code. This means templates should be treated as trusted code, as untrusted templates could pose a security risk by executing malicious operations.
  Fix: Only use templates from trusted sources. Do not render user-provided templates directly without sanitization or sandboxing, which Tempita does not provide inherently.
• gotcha Tempita is not designed for complex web applications or extensive feature sets found in larger templating languages like Jinja. It's intended for simpler text substitution and code generation tasks.
  Fix: Evaluate if Tempita's minimalist feature set meets your project's needs. For complex web rendering or rich templating features, consider alternatives.

Install

• pip install tempita Install latest version

Imports

• Template
  wrong:

  import tempita; tempita.Template(...)

  correct:

  from tempita import Template

  While 'import tempita' works, accessing 'Template' directly from the module without explicit import is less idiomatic and can lead to confusion if other module-level functions are expected.
• sub

  from tempita import sub

• HTMLTemplate

  from tempita import HTMLTemplate

  Used for templates producing HTML, providing automatic HTML quoting.

Quickstart

This quickstart demonstrates both the `Template` class for creating reusable template objects and the `sub` function for immediate string substitution. It also includes an example using Tempita's control flow (`for`, `if`) and inline Python blocks (`py:`).

from tempita import Template, sub

# Using the Template class
tmpl = Template("Hello {{name}}! The answer is {{2 * 3}}.")
output_class = tmpl.substitute(name='World')
print(f"Class Output: {output_class}")

# Using the sub shortcut for immediate substitution
output_shortcut = sub("Welcome, {{user}}!", user='Alice')
print(f"Shortcut Output: {output_shortcut}")

# Example with control flow (if/for) and Python blocks
complex_template = Template("""
<ul>
{{for item in items}}
  <li>{{item.upper()}}{{if loop.last}} (last){{endif}}</li>
{{endfor}}
</ul>
{{py: x = 10}}
The value of x is {{x}}.
""")
output_complex = complex_template.substitute(items=['apple', 'banana', 'cherry'])
print("\nComplex Output:")
print(output_complex)