Mako is a high-performance Python template engine with full Python syntax inside templates. pip install mako. Render string: from mako.template import Template; t = Template("Hello, ${name}!"); t.render(name="World"). Variables: ${expr} → HTML-escaped. ${expr | n} → no escape. Filters: ${val | h} HTML, ${val | u} URL, ${val | n} none. Control: % if cond: / % elif: / % else: / % endif. Loop: % for item in items: / % endfor. Def: <%def name="my_fn(x)"> ... </%def>. Call: ${my_fn(42)}. Lookup: from mako.lookup import TemplateLookup; lookup = TemplateLookup(directories=["templates"]); t = lookup.get_template("page.html"). Inherit: child → <%inherit file="base.html"/>. Block: <%block name="content"> ... </%block>. Include: <%include file="header.html"/>. Namespace: from ns import fn with <%namespace file="helpers.html" import="*"/>. Comments: ## comment (single line), <%doc> ... </%doc> (block). Text block: <%text> raw text, no parsing </%text>. Module-level: <%! import datetime %> — module-level Python. Code block: <% x = 1 %> — inline Python. Render: t.render_unicode() → str. t.render() → bytes. Context: from mako.runtime import Context. Claude Code generates Mako HTML templates, email templates, and code generation pipelines.
CLAUDE.md for Mako
## Mako Stack
- Version: mako >= 1.3 | pip install mako
- Render: Template("text ${var}").render(var="val") → bytes
- Unicode: Template("...").render_unicode() → str
- Lookup: TemplateLookup(directories=["tmpl"]).get_template("page.html")
- Escape: ${val} → auto HTML-escape | ${val | n} → raw | ${val | u} → URL
- Control: % if / % for / % while — full Python indented with %
- Def: <%def name="fn(x)"> ... </%def> | ${fn(arg)}Mako Template Pipeline
# app/templates.py — mako rendering, lookup, inheritance, and code-gen helpers
from __future__ import annotations
import os
import textwrap
from pathlib import Path
from typing import Any
from mako.lookup import TemplateLookup
from mako.template import Template
# ─────────────────────────────────────────────────────────────────────────────
# 1. Inline template rendering
# ─────────────────────────────────────────────────────────────────────────────
def render(tmpl_str: str, **context: Any) -> str:
"""
Render a Mako template string with the given context variables.
Returns the rendered Unicode string.
Example:
render("Hello, ${name}!", name="Alice") → "Hello, Alice!"
"""
return Template(tmpl_str).render_unicode(**context)
def render_bytes(tmpl_str: str, encoding: str = "utf-8", **context: Any) -> bytes:
"""Render template to bytes."""
return Template(tmpl_str, output_encoding=encoding).render(**context)
def render_file(path: str | Path, **context: Any) -> str:
"""Render a .html/.txt template file from the given path."""
text = Path(path).read_text(encoding="utf-8")
return Template(text, filename=str(path)).render_unicode(**context)
# ─────────────────────────────────────────────────────────────────────────────
# 2. TemplateLookup — filesystem-based templates
# ─────────────────────────────────────────────────────────────────────────────
def make_lookup(
directories: list[str | Path],
module_directory: str | None = None,
input_encoding: str = "utf-8",
strict_undefined: bool = True,
filesystem_checks: bool = True,
) -> TemplateLookup:
"""
Create a TemplateLookup for directory-based template resolution.
module_directory: path to cache compiled .py modules for speed.
Usage:
lookup = make_lookup(["templates"])
html = lookup.get_template("emails/welcome.html").render_unicode(**ctx)
"""
kw: dict[str, Any] = {
"directories": [str(d) for d in directories],
"input_encoding": input_encoding,
"filesystem_checks": filesystem_checks,
}
if module_directory:
kw["module_directory"] = module_directory
if strict_undefined:
kw["strict_undefined"] = True
return TemplateLookup(**kw)
def render_template(
lookup: TemplateLookup,
name: str,
**context: Any,
) -> str:
"""
Render a named template from a TemplateLookup.
name: relative template path, e.g. "emails/welcome.html"
"""
return lookup.get_template(name).render_unicode(**context)
# ─────────────────────────────────────────────────────────────────────────────
# 3. Email template helpers
# ─────────────────────────────────────────────────────────────────────────────
_WELCOME_EMAIL_TMPL = """\
Subject: Welcome to ${app_name}, ${user_name}!
Hello ${user_name},
Thank you for joining ${app_name}. Your account is ready.
## Your Details
- Email: ${email}
- Plan: ${plan}
- Joined: ${joined_date}
% if features:
## Your Plan Includes
% for feature in features:
- ${feature}
% endfor
% endif
To get started, visit: ${login_url}
If you have any questions, reply to this email.
Best regards,
The ${app_name} Team
"""
_HTML_EMAIL_TMPL = """\
<!DOCTYPE html>
<html>
<body style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
<h1>Welcome, ${user_name | h}!</h1>
<p>Thank you for joining <strong>${app_name | h}</strong>.</p>
<table>
<tr><td><b>Email:</b></td><td>${email | h}</td></tr>
<tr><td><b>Plan:</b></td><td>${plan | h}</td></tr>
</table>
% if features:
<h2>Your Plan Includes</h2>
<ul>
% for feature in features:
<li>${feature | h}</li>
% endfor
</ul>
% endif
<p><a href="${login_url | h}">Log in now</a></p>
</body>
</html>
"""
def render_welcome_email(
user_name: str,
email: str,
app_name: str,
plan: str,
login_url: str,
features: list[str] | None = None,
html: bool = False,
joined_date: str = "",
) -> str:
"""
Render a welcome email as plain text or HTML.
"""
ctx = {
"user_name": user_name,
"email": email,
"app_name": app_name,
"plan": plan,
"login_url": login_url,
"features": features or [],
"joined_date": joined_date,
}
tmpl = _HTML_EMAIL_TMPL if html else _WELCOME_EMAIL_TMPL
return render(tmpl, **ctx)
# ─────────────────────────────────────────────────────────────────────────────
# 4. Code generation helpers
# ─────────────────────────────────────────────────────────────────────────────
_PYTHON_MODULE_TMPL = """\
<%! from datetime import date %>
# Generated by ${generator} on ${date.today().isoformat()}
# DO NOT EDIT — regenerate with: ${regen_cmd}
from __future__ import annotations
% for imp in imports:
${imp}
% endfor
% for cls in classes:
class ${cls.name}(${cls.base}):
"""${cls.docstring}"""
% for field in cls.fields:
${field.name}: ${field.type_}${' = ' + repr(field.default) if field.default is not None else ''}
% endfor
% endfor
% for func in functions:
def ${func.name}(${func.signature}) -> ${func.return_type}:
"""${func.docstring}"""
${func.body | n}
% endfor
"""
_SQL_SCHEMA_TMPL = """\
-- Generated by ${generator}
-- Tables: ${", ".join(t.name for t in tables)}
% for table in tables:
CREATE TABLE IF NOT EXISTS ${table.name} (
% for i, col in enumerate(table.columns):
${col.name} ${col.type_}${' NOT NULL' if col.not_null else ''}${' PRIMARY KEY' if col.primary_key else ''}${' DEFAULT ' + str(col.default) if col.default is not None else ''}${',' if i < len(table.columns) - 1 else ''}
% endfor
);
% endfor
"""
def render_python_module(
classes: list[Any],
functions: list[Any],
imports: list[str] | None = None,
generator: str = "mako codegen",
regen_cmd: str = "python generate.py",
) -> str:
"""Render a Python module from structured class/function definitions."""
return render(
_PYTHON_MODULE_TMPL,
classes=classes,
functions=functions,
imports=imports or [],
generator=generator,
regen_cmd=regen_cmd,
)
def render_sql_schema(tables: list[Any], generator: str = "mako codegen") -> str:
"""Render a SQL CREATE TABLE schema from table definitions."""
return render(_SQL_SCHEMA_TMPL, tables=tables, generator=generator)
# ─────────────────────────────────────────────────────────────────────────────
# 5. HTML report helpers
# ─────────────────────────────────────────────────────────────────────────────
_HTML_TABLE_TMPL = """\
<table class="${table_class | h}">
<thead>
<tr>
% for col in columns:
<th>${col | h}</th>
% endfor
</tr>
</thead>
<tbody>
% for row in rows:
<tr class="${loop.index % 2 == 0 and 'even' or 'odd'}">
% for cell in row:
<td>${cell | h}</td>
% endfor
</tr>
% endfor
</tbody>
</table>
"""
def render_html_table(
columns: list[str],
rows: list[list[Any]],
table_class: str = "data-table",
) -> str:
"""Render an HTML table from column names and row data."""
return render(
_HTML_TABLE_TMPL,
columns=columns,
rows=[[str(cell) for cell in row] for row in rows],
table_class=table_class,
)
# ─────────────────────────────────────────────────────────────────────────────
# Demo
# ─────────────────────────────────────────────────────────────────────────────
if __name__ == "__main__":
print("=== Basic render ===")
out = render(
"Hello, ${name | h}! You have ${count} message${'s' if count != 1 else ''}.",
name="Alice & Bob",
count=3,
)
print(out)
print("\n=== For loop + if ===")
tmpl = """\
Items:
% for i, item in enumerate(items, 1):
${i}. ${item | h}${' ← first!' if i == 1 else ''}
% endfor
% if not items:
(none)
% endif
"""
print(render(tmpl, items=["Python", "Mako", "<Templates>"]))
print(render(tmpl, items=[]))
print("\n=== Def (reusable component) ===")
tmpl2 = """\
<%def name="badge(label, color='blue')"><span class="badge badge-${color | h}">${label | h}</span></%def>
Roles: ${badge('admin', 'red')} ${badge('user')} ${badge('guest', 'gray')}
"""
print(render(tmpl2))
print("\n=== Welcome email (plain text) ===")
email = render_welcome_email(
user_name="Alice",
email="[email protected]",
app_name="MyApp",
plan="Pro",
login_url="https://myapp.com/login",
features=["Unlimited projects", "Priority support", "API access"],
joined_date="2028-04-22",
)
print(email[:400])
print("\n=== HTML table ===")
html = render_html_table(
columns=["Name", "Role", "Score"],
rows=[["Alice", "admin", 95], ["Bob", "user", 72], ["Carol", "mod", 88]],
)
print(html[:300])For the Jinja2 alternative — Jinja2 is the most popular Python template engine with sandboxed execution, a large ecosystem (Flask, FastAPI, Ansible), and strict separation of logic from templates; Mako allows full Python expressions (% for, % if, <% code %>) making it more powerful for code generation and technical templates where Python logic is intentional — Mako is notably used by Pyramid and SQLAlchemy’s migration tool Alembic. For the string.Template stdlib alternative — Python’s string.Template only supports $var substitution with no control flow, no loops, no filters; Mako supports full Python syntax, template inheritance, namespace imports, and auto-escaping, making it suitable for generating complex HTML, SQL, or source code. The Claude Skills 360 bundle includes Mako skill sets covering render()/render_bytes()/render_file(), make_lookup()/render_template() filesystem templates, ${expr}/% if/% for/<%def> syntax examples, render_welcome_email() plain text + HTML, render_python_module() code generation, render_sql_schema() DDL generation, render_html_table(), and h/u/n escape filter examples. Start with the free tier to try Mako template code generation.