### SimpleCacheImpl Example

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/caching.rst

An example implementation of a local dictionary cache plugin for Mako.

```APIDOC
## SimpleCacheImpl

### Description
An example implementation of a local dictionary cache plugin for Mako.

### Class Definition
```python
from mako.cache import CacheImpl, register_plugin

class SimpleCacheImpl(CacheImpl):
    def __init__(self, cache):
        super(SimpleCacheImpl, self).__init__(cache)
        self._cache = {}

    def get_or_create(self, key, creation_function, **kw):
        if key in self._cache:
            return self._cache[key]
        else:
            self._cache[key] = value = creation_function()
            return value

    def set(self, key, value, **kwargs):
        self._cache[key] = value

    def get(self, key, **kwargs):
        return self._cache.get(key)

    def invalidate(self, key, **kwargs):
        self._cache.pop(key, None)

# optional - register the class locally
register_plugin("simple", __name__, "SimpleCacheImpl")
```

### Usage Example
Enabling the above plugin in a template would look like:

```python
from mako.template import Template

t = Template("mytemplate",
             file="mytemplate.html",
             cache_impl='simple')
```
```

--------------------------------

### Basic TemplateLookup Setup

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/usage.rst

Shows the initial setup of TemplateLookup, which is used to resolve template resources, including included files. It requires a list of directories to search for templates.

```python
from mako.template import Template
from mako.lookup import TemplateLookup

mylookup = TemplateLookup(directories=['/docs'])
mytemplate = Template("%3C%25include file=\"header.txt\"/%3E hello world!", lookup=mylookup)
```

--------------------------------

### Python SimpleCacheImpl for Mako

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/caching.rst

An example of a custom cache implementation using a local dictionary. It extends Mako's CacheImpl and provides methods for getting, setting, and invalidating cache entries. Register this plugin using register_plugin.

```python
from mako.cache import Cacheimpl, register_plugin

class SimpleCacheImpl(CacheImpl):
    def __init__(self, cache):
        super(SimpleCacheImpl, self).__init__(cache)
        self._cache = {}

    def get_or_create(self, key, creation_function, **kw):
        if key in self._cache:
            return self._cache[key]
        else:
            self._cache[key] = value = creation_function()
            return value

    def set(self, key, value, **kwargs):
        self._cache[key] = value

    def get(self, key, **kwargs):
        return self._cache.get(key)

    def invalidate(self, key, **kwargs):
        self._cache.pop(key, None)

# optional - register the class locally
register_plugin("simple", __name__, "SimpleCacheImpl")
```

--------------------------------

### Gettext Catalog Example

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/usage.rst

This is an example of a gettext catalog entry generated by Babel. It includes translator comments and message IDs.

```pot
#. TRANSLATORS: This is a proper name. See the gettext
#. manual, section Names.
#: myproj/templates/name.html:5
msgid "Francois Pinard"
msgstr ""
```

--------------------------------

### Basic Mako Template Example

Source: https://github.com/sqlalchemy/mako/blob/main/README.rst

Demonstrates basic Mako template syntax including inheritance, variable assignment, loops, and defining custom functions. Use this for creating dynamic HTML structures.

```python
<%inherit file="base.html"/>
<% 
    rows = [[v for v in range(0,10)] for row in range(0,10)]
%>
<table>
    % for row in rows:
        ${makerow(row)}
    % endfor
</table>

<%def name="makerow(row)">
    <tr>
    % for name in row:
        <td>${name}</td>\
    % endfor
    </tr>
</%def>
```

--------------------------------

### Mako Caching with Beaker Backend

Source: https://context7.com/sqlalchemy/mako/llms.txt

Demonstrates template caching using the 'beaker' backend with configurable timeouts and programmatic invalidation. Ensure 'beaker' is installed.

```python
from mako.template import Template
import time

# This content is cached for 60 seconds
Generated at: ${time.strftime('%H:%M:%S')}
""", imports=["import time"], cache_impl="beaker",
    cache_args={"type": "memory"})

# First render generates and caches
output1 = t.render()
# Second render returns cached value (same timestamp)
output2 = t.render()
assert output1 == output2

# Invalidate the body cache programmatically
t.cache.invalidate_body()
```

```python
# ── Cache individual defs ─────────────────────────────────────────────────────
t2 = Template("""
<%def name="sidebar()" cached="True" cache_timeout="300">
  Expensive sidebar content
</%def>

<%def name="header()">
  Always fresh header
</%def>

${header()}
${sidebar()}
""", cache_impl="beaker", cache_args={"type": "memory"})

t2.render()
# Invalidate just the sidebar def
t2.cache.invalidate_def("sidebar")
```

--------------------------------

### Namespace API Usage Example - Static Dependencies (Version Two - Use a specific named def)

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/namespaces.rst

This example shows an alternative method where static dependencies are placed within a named '<%def>' block. The base template then calls this specific def on each namespace to retrieve the necessary includes.

```APIDOC
## base.mako
## base-most template, renders layout etc.
<html>
<head>
## traverse through all namespaces present,
## look for a %def named 'includes'
% for ns in context.namespaces.values():
    % if hasattr(ns, 'includes'):
        ${ns.includes()}
    % endif
% endfor
</head>
<body>
${next.body()}
</body
</html>

## library.mako
## library functions.

<%def name="includes()">
    <link rel="stylesheet" type="text/css" href="mystyle.css"/>
    <script type="text/javascript" src="functions.js"></script>
</%def>

<%def name="mytag()">
    <form>
        ${caller.body()}
    </form>
</%def>


## index.mako
## calling template.
<%inherit file="base.mako"/>
<%namespace name="foo" file="library.mako"/>

<%foo:mytag>
    a form
</%foo:mytag>
```

--------------------------------

### Define and Render Mako Template with Definitions

Source: https://github.com/sqlalchemy/mako/wiki/imported_issue_attachments/102/functional_def_render.txt

Shows how to define reusable template functions (defs) within a Mako template and then render them with specific arguments. Ensure Mako is installed.

```python
from mako.template import Template
```

```python
template = Template("""
    <%def name="hi(name)">
        hi ${name}!
    </%def>

    <%def name="bye(name)">
        bye ${name}!
    </%def>
    """)
```

```python
print template.get_def("hi").render(name="ed")
```

--------------------------------

### English Translation Example

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

This is an example of a .po file entry for an English translation. It shows the original message ID and its corresponding translation.

```ini
#: translate_demo\controllers\hello.py:6 translate_demo\controllers\hello.py:9
msgid "Hello"
msgstr "Hello"
```

--------------------------------

### Mako Template Inheritance Example

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/inheritance.rst

Demonstrates how an inheriting template can override blocks defined in a base template. Use this to extend base layouts with specific content.

```mako
## index.html
<%inherit file="base.html"/>

<%block name="header">
    this is some header content
    ${parent.header()}
</%block>

<%block name="title">
    this is the title
</%block>

this is the body content.
```

--------------------------------

### Jinja2 Macro and Inclusion Example

Source: https://github.com/sqlalchemy/mako/blob/main/examples/bench/jinja2/template.html

Defines a reusable macro for greetings and includes other templates. Useful for creating dynamic HTML content.

```html
{% title %} {%- macro greeting(name) %}

hello {{ name }}

{%- endmacro %} {% include "header.html" %} {{ greeting(user) }} {{ greeting('me') }} {{ greeting('world') }}
```

--------------------------------

### Call Mako Body Method with Arguments

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/namespaces.rst

Provides an example of calling the body() method with specific arguments, including positional and keyword arguments. This is used when the body method's signature has been explicitly defined.

```mako
${self.body(5, y=10, someval=15, delta=7)}
```

--------------------------------

### Spanish Translation Example

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

This is an example of a .po file entry for a Spanish translation. It shows the original message ID and its corresponding translation.

```ini
#: translate_demo\controllers\hello.py:6 translate_demo\controllers\hello.py:9
msgid "Hello"
msgstr "°Hola!"
```

--------------------------------

### French Translation Example

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

This is an example of a .po file entry for a French translation. It shows the original message ID and its corresponding translation.

```ini
#: translate_demo\controllers\hello.py:6 translate_demo\controllers\hello.py:9
msgid "Hello"
msgstr "Bonjour"
```

--------------------------------

### Namespace API Usage Example - Static Dependencies (Version One - Use :attr:`.Namespace.attr`)

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/namespaces.rst

This example demonstrates how to use the :attr:`.Namespace.attr` attribute to access variables declared in the '<%! %>` section of a template, enabling the base template to dynamically include resources declared in child namespaces.

```APIDOC
## base.mako
## base-most template, renders layout etc.
<html>
<head>
## traverse through all namespaces present,
## look for an attribute named 'includes'
% for ns in context.namespaces.values():
    % for incl in getattr(ns.attr, 'includes', []):
        ${incl}
    % endfor
% endfor
</head>
<body>
${next.body()}
</body
</html>

## library.mako
## library functions.
<%!
    includes = [
        '<link rel="stylesheet" type="text/css" href="mystyle.css"/>',
        '<script type="text/javascript" src="functions.js"></script>'
]
%>

<%def name="mytag()">
    <form>
        ${caller.body()}
    </form>
</%def>

## index.mako
## calling template.
<%inherit file="base.mako"/>
<%namespace name="foo" file="library.mako"/>

<%foo:mytag>
    a form
</%foo:mytag>
```

--------------------------------

### Example Usage of decode_request

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

Demonstrates how to use the `decode_request` function to process request parameters. Avoid using with file uploads.

```python
unicode_params = decode_request(request.params)
```

--------------------------------

### Basic Translation String

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

This is an example of a string that would be extracted for translation using a function like _().

```python
msg = _("He told her not to go outside")
```

--------------------------------

### Mako Template with Gettext Message Extraction

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/usage.rst

Example of a Mako template demonstrating the use of the '_()' function for gettext message extraction, including translator comments.

```mako
<div id="name">
  Name:
  ## TRANSLATORS: This is a proper name. See the gettext
  ## manual, section Names.
  ${_('Francois Pinard')}
</div>
```

--------------------------------

### Define and Call Macro with Unicode Argument

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/unicode_arguments_py3k.html

Defines a Mako macro 'my_def' that accepts an argument 'x' and renders it. The example shows calling this macro with a Unicode string literal.

```html
<%def name="my_def(x)">
 x is: ${x}
</%def>

${my_def('drôle de petite voix m’a réveillé')}
```

--------------------------------

### Apply Multiple Filters (HTML Escape and Trim)

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/filtering.rst

Combine multiple filters by separating them with commas. The filters are applied in order from left to right. This example applies HTML escaping first, then trims whitespace.

```mako
${ " <tag>some value</tag> " | h,trim }
```

--------------------------------

### Include Translation Catalogs in setup.py

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

Configure your setup.py file to include the necessary translation catalog files (.mo) within the distributed egg.

```python
package_data={'translate_demo': ['i18n/*/LC_MESSAGES/*.mo']},
```

--------------------------------

### Template Class Initialization and Rendering

Source: https://context7.com/sqlalchemy/mako/llms.txt

Demonstrates how to create a `Template` object from a string or file and render its content. It also shows options for handling undefined variables and custom default filters.

```APIDOC
## Template

Compile and render a template from text or file

`Template` is the primary class for compiling a Mako template and rendering it into a string. It accepts either a `text` string or a `filename` path as the template source, along with numerous configuration options for encoding, filtering, caching, and error handling.

### Usage

```python
from mako.template import Template

# Render from a string
t = Template("""
Hello, ${name}!
Your items:
% for item in items:
  - ${item | h}
% endfor
""")

result = t.render(name="Alice", items=["<script>", "bread", "milk"])
print(result)

# Render as unicode
unicode_result = t.render_unicode(name="Bob", items=["apples"])
assert isinstance(unicode_result, str)

# Render from a file with module caching
file_tmpl = Template(
    filename="/path/to/templates/index.html",
    module_directory="/tmp/mako_modules",   # compiled .py files cached here
    output_encoding="utf-8",
    encoding_errors="replace",
)
output = file_tmpl.render()

# Strict undefined variables
strict_tmpl = Template(
    "Hello ${username}",
    strict_undefined=True,   # raises NameError instead of silently using UNDEFINED
)
try:
    strict_tmpl.render()     # no 'username' passed
except NameError as e:
    print(f"Caught: {e}")

# Custom default filters (auto-escape all expressions)
safe_tmpl = Template(
    "${user_input}",
    default_filters=["h"],   # applies html_escape to every ${} expression
)
print(safe_tmpl.render(user_input="<b>bold</b>"))

# Inspect generated Python source
t2 = Template("${x + 1}")
print(t2.source)   # original template source
print(t2.code)     # generated Python module code
```
```

--------------------------------

### Build Python Egg with Translations

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

Package your application as a Python egg, including translation files (.mo catalogs), using the setup.py script.

```python
python setup.py bdist_egg
```

--------------------------------

### Render Mako Template with Different Methods

Source: https://context7.com/sqlalchemy/mako/llms.txt

Demonstrates `render()`, `render_unicode()`, and `render_context()` for outputting template content. `render()` returns bytes or string based on `output_encoding`. `render_unicode()` always returns a string. `render_context()` writes to a provided buffer.

```python
from mako.template import Template
from mako.runtime import Context
import io

t = Template("""
<%page args="title, rows"/>
<h1>${title}</h1>
<table>
% for row in rows:
  <tr><td>${row[0]}</td><td>${row[1] | h}</td></tr>
% endfor
</table>
""")

# render() — returns str (no output_encoding set)
html = t.render(title="Report", rows=[("Alice", "<admin>"), ("Bob", "user")])
print(html)
```

```python
# render_unicode() — always str, useful when output_encoding is set on the template
t_enc = Template("${msg}", output_encoding="utf-8")
text = t_enc.render_unicode(msg="hello")   # str, not bytes
assert isinstance(text, str)
```

```python
# render_context() — write into a pre-existing Context
buf = io.StringIO()
ctx = Context(buf, title="Direct", rows=[("x", "y")])
t.render_context(ctx)
print(buf.getvalue())
```

--------------------------------

### Loading Template from Filename

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/usage.rst

Demonstrates how to create a Mako template by specifying the source file using the 'filename' argument. This is useful for organizing templates in separate files.

```python
from mako.template import Template

mytemplate = Template(filename='/docs/mytmpl.txt')
print(mytemplate.render())
```

--------------------------------

### Checking and Rendering Template Definitions

Source: https://context7.com/sqlalchemy/mako/llms.txt

Demonstrates how to check for the existence of a definition within a template and how to render specific definitions.

```python
print(t.has_def("header"))   # True
print(t.has_def("sidebar"))  # False

# render only the header def
header_tmpl = t.get_def("header")
print(header_tmpl.render(title="My Page"))
# <header><h1>My Page</h1></header>

# render only the footer def
footer_tmpl = t.get_def("footer")
print(footer_tmpl.render())
# <footer>Copyright 2025</footer>
```

--------------------------------

### Mako Inherited Attribute Output Example

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/inheritance.rst

The resulting HTML output when an inheritable attribute is overridden in a child template.

```html
<div class="white">
    This is the body
</div>
```

--------------------------------

### TemplateLookup Configuration and Usage

Source: https://context7.com/sqlalchemy/mako/llms.txt

Shows how to configure TemplateLookup for filesystem access, caching, and auto-reloading, and how to retrieve and render templates.

```python
from mako.lookup import TemplateLookup

lookup = TemplateLookup(
    directories=["/path/to/templates", "/path/to/shared"],
    module_directory="/tmp/mako_modules",
    filesystem_checks=True,      # auto-reload on source file change
    collection_size=500,         # LRU cache of up to 500 templates
    output_encoding="utf-8",
    default_filters=["h"],
    strict_undefined=True,
)

# Retrieve and render a template by URI
tmpl = lookup.get_template("/pages/home.html")
print(tmpl.render(user="Alice"))

# Programmatically add templates from strings
lookup.put_string("base.html", """
<html><head><title>${self.title()}</title></head>
<body>${self.body()}</body></html>
<%def name="title()">Default Title</%def>
""")

lookup.put_string("page.html", """
<%inherit file="base.html"/>
<%def name="title()">My Page</%def>
Hello, ${name}!
""")

result = lookup.get_template("page.html").render(name="World")
print(result)
# <html><head><title>My Page</title></head>
# <body>Hello, World!</body></html>

# Check template existence
print(lookup.has_template("/pages/home.html"))   # True or False

# Convert a filesystem path back to URI
uri = lookup.filename_to_uri("/path/to/templates/pages/home.html")
print(uri)   # /pages/home.html
```

--------------------------------

### Set and Get Language for Translation

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

Use h.set_lang() to set the desired language and h.get_lang() to retrieve the current language for translations.

```python
for lang in ['fr','en','es']:
    h.set_lang(lang)
    resp.write("%s: %s<br />" % (h.get_lang(), _('Hello')))
```

--------------------------------

### Configuring Cache Key for Page/Def Arguments

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/changelog.rst

Shows how to use the 'cache_key' argument to render arguments passed directly to the %page or %def directives, enabling dynamic cache keys.

```html
<%def name="foo(x)" cached="True" cache_key="${x}"/>
```

--------------------------------

### Jinja2 Conditional Loop Example

Source: https://github.com/sqlalchemy/mako/blob/main/examples/bench/jinja2/template.html

Renders a list of items only if the list exists, using a conditional and a for loop. Suitable for dynamic list generation.

```html
{% if list_items %}

{%- for list_item in list_items %}*   {{ list_item }}
{%- endfor %}

{%- endif %} {% include "footer.html" %}
```

--------------------------------

### Mako Template: Variable Interpolation and Loops

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/crlf.html

Illustrates basic Mako syntax for variable arguments, iterating through a list, and outputting values. Ensure the 'a' argument is provided when rendering.

```html
<%page args="a=\['foo', 'bar'\]"/> like the name says. % for x in [1,2,3]: ${x}\ % endfor
```

--------------------------------

### Enable Loop Context Per Template

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/runtime.rst

Demonstrates how to re-enable the 'loop' context for a specific template using the `<%page enable_loop="True"/>` tag.

```mako
<%page enable_loop="True"/>

% for i in collection:
    ${i} ${loop.index}
% endfor
```

--------------------------------

### Mako Anonymous Block Rendering

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/defs.rst

Demonstrates the basic usage of an anonymous <%block> tag, which renders its content in place. This example shows a block with no effect.

```mako
<html>
    <body>
        <%block>
            this is a block.
        </%block>
    </body>
</html>
```

```html
<html>
    <body>
            this is a block.
    </body>
</html>
```

--------------------------------

### Basic Template Rendering

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/usage.rst

Demonstrates the simplest way to create and render a Mako template directly from a string. The template text is compiled into a Python module with a render_body() function.

```python
from mako.template import Template

mytemplate = Template("hello world!")
print(mytemplate.render())
```

--------------------------------

### Set Default Filters Programmatically (str)

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/filtering.rst

Configure default filters for all templates managed by a TemplateLookup instance. This example sets the default filter to 'str'.

```python
t = TemplateLookup(directories=['/tmp'], default_filters=['str'])
```

--------------------------------

### Checkered Table using Parent Loop Context

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/runtime.rst

Demonstrates how to use `loop.parent.even` to create a checkered table effect by accessing the parent loop's iteration status.

```mako
<table>
% for consonant in 'pbj':
  <tr>
  % for vowel in 'iou':
    <td class="${'black' if (loop.parent.even == loop.even) else 'red'}">
      ${consonant + vowel}t
    </td>
  % endfor
  </tr>
% endfor
</table>
```

--------------------------------

### Nesting Blocks in Base Template

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/inheritance.rst

This example shows how blocks can be nested within other blocks in the base template. The 'title' block is nested within the 'header' block.

```mako
## base.html
<html>
    <body>
        <div class="header">
            <%block name="header">
                <h2>
                    <%block name="title"/>
                </h2>
            </%block>
        </div>

        ${self.body()}

```

--------------------------------

### Mako Dynamic Include with Blocks

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/inheritance.rst

Demonstrates how <%include> is a dynamic, runtime include and does not interact with inheritance structures. Blocks in included files are not overridden by blocks in the calling template.

```mako
## partials.mako
<%block name="header">
    Global Header
</%block>

## parent.mako
<%include file="partials.mako" />

## child.mako
<%inherit file="parent.mako" />
<%block name="header">
    Custom Header
</%block>
```

--------------------------------

### Decode Request Parameters in Pylons

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

Utility functions to decode GET and POST parameters of a Pylons request object. Use this to ensure all input is treated as Unicode.

```python
def decode_multi_dict(md, encoding="UTF-8", errors="strict"):
    """Given a MultiDict, decode all its parts from the given encoding. This modifies the MultiDict in place. encoding, strict These are passed to the decode function. """
    items = md.items()
    md.clear()
    for (k, v) in items:
        md.add(k.decode(encoding, errors), v.decode(encoding, errors))

def decode_request(request, encoding="UTF-8", errors="strict"):
    """Given a request object, decode GET and POST in place. This implicitly takes care of params as well. """
    decode_multi_dict(request.GET, encoding, errors)
    decode_multi_dict(request.POST, encoding, errors)
```

--------------------------------

### Render Template to Unicode String

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/unicode.rst

Use the `render_unicode` method to get the template output as a Python `str` object. This method ignores any output encoding arguments.

```python
print(mytemplate.render_unicode())
```

--------------------------------

### Configure Beaker Cache Regions

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/caching.rst

Set up Beaker cache regions with different types (e.g., 'memory', 'ext:memcached') and expiration times. This allows for external configuration of cache behavior.

```python
from beaker.cache import CacheManager

manager = CacheManager(cache_regions={
    'short_term':{
        'type': 'memory',
        'expire': 60
    },
    'long_term':{
        'type': 'ext:memcached',
        'url': '127.0.0.1:11211',
        'expire': 300
    }
})

lookup = TemplateLookup(

```

--------------------------------

### Babel Integration for Mako i18n Extraction

Source: https://context7.com/sqlalchemy/mako/llms.txt

Configures Babel to extract internationalizable strings from Mako templates using the `mako.ext.babelplugin.extract` function. Shows example usage with `_()` and `gettext()` calls.

```ini
# babel.cfg
[mako: templates/**.html]
encoding = utf-8
input_encoding = utf-8
```

```python
# setup.cfg / pyproject.toml equivalent programmatic usage
from mako.ext.babelplugin import extract
import io

template_source = b"""
<%! from myapp.i18n import _ %>
<h1>${_("Welcome")}</h1>
<p>${_("Hello, %(name)s", name=username)}</p>
"""

keywords = {"_" : None, "gettext": None, "ngettext": (1, 2)}
comment_tags = ["TRANS:"]
options = {"input_encoding": "utf-8"}

for lineno, funcname, messages, comments in extract(
    io.BytesIO(template_source), keywords, comment_tags, options
):
    print(f"Line {lineno}: {funcname}({messages!r})")
```

--------------------------------

### Registering a Custom Cache Backend in Mako

Source: https://context7.com/sqlalchemy/mako/llms.txt

Shows how to register and use a custom cache implementation ('dict' type) by subclassing Mako's CacheImpl. This allows for custom caching logic.

```python
from mako.cache import CacheImpl, register_plugin

class DictCacheImpl(CacheImpl):
    def __init__(self, cache):
        super().__init__(cache)
        self._store = {}

    def get_or_create(self, key, creation_function, **kw):
        if key not in self._store:
            self._store[key] = creation_function()
        return self._store[key]

    def set(self, key, value, **kw):
        self._store[key] = value

    def get(self, key, **kw):
        return self._store[key]

    def invalidate(self, key, **kw):
        self._store.pop(key, None)

register_plugin("dict", __name__, "DictCacheImpl")

cached_tmpl = Template(
    "<%page cached=\"True""/>Hello ${name}",
    cache_impl="dict",
)
print(cached_tmpl.render(name="World"))
```

--------------------------------

### Manually Encode Unicode Output

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/unicode.rst

To encode the Unicode output yourself, call the `.encode()` method on the string returned by `render_unicode`. This example uses UTF-8 encoding with 'replace' error handling.

```python
print(mytemplate.render_unicode().encode('utf-8', 'replace'))
```

--------------------------------

### Mako Conditional and Loop Syntax

Source: https://github.com/sqlalchemy/mako/blob/main/examples/bench/mako/template.html

Illustrates conditional rendering and looping constructs in Mako. Useful for dynamic content generation based on data.

```html
Loop
----

% if list_items:

% for i, list_item in enumerate(list_items):*   ${list_item}
% endfor

% endif <%include file="footer.html"/>
```

--------------------------------

### Incorrect Pluralization Example

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

Avoid using simple if-else statements for pluralization with the _() function, as it does not account for languages with more than two plural forms. Use gettext's pluralization support instead.

```python
# BAD! if n == 1:
#     msg = _("There was no dog.")
# else:
#     msg = _("There were no dogs.")
```

--------------------------------

### Defining and Using Reusable Def Components

Source: https://context7.com/sqlalchemy/mako/llms.txt

Shows how to define reusable components using `<%def>` within a Mako template, including support for arguments, default values, and composition.

```python
from mako.template import Template

t = Template("""
<%def name="render_card(title, body, footer=None)">
<div class="card">
  <div class="card-title">${title}</div>
  <div class="card-body">${body}</div>
  % if footer:
  <div class="card-footer">${footer}</div>
  % endif
</div>
</%def>

<%def name="render_list(items, ordered=False)">
  <${'ol' if ordered else 'ul'}>
  % for item in items:
    <li>${item | h}</li>
  % endfor
  </${'ol' if ordered else 'ul'}>
</%def>

${render_card("News", render_list(articles), footer="Read more")}
${render_card("Steps", render_list(steps, ordered=True))}
""")

result = t.render(
    articles=["<Breaking>", "Sports", "Weather"],
    steps=["Install", "Configure", "Run"],
)
print(result)
```

--------------------------------

### Enabling Simple Cache in Mako Template

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/caching.rst

Demonstrates how to enable the 'simple' cache implementation for a Mako template by specifying the cache_impl argument during Template instantiation.

```python
t = Template("mytemplate",
             file="mytemplate.html",
             cache_impl='simple')
```

--------------------------------

### TemplateLookup with Template Rendering

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/usage.rst

Demonstrates using TemplateLookup to retrieve and render templates by name. It configures both template search directories and a module cache directory for performance.

```python
from mako.template import Template
from mako.lookup import TemplateLookup

mylookup = TemplateLookup(directories=['/docs'], module_directory='/tmp/mako_modules')

def serve_template(templatename, **kwargs):
    mytemplate = mylookup.get_template(templatename)
    print(mytemplate.render(**kwargs))
```

--------------------------------

### Propagate Context Variables as Keyword Arguments

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/runtime.rst

Use the context.kwargs accessor to get a copy of the current context's variables. This is useful for passing these variables as keyword arguments to other functions or template calls.

```mako
${next.body(**context.kwargs)}
```

--------------------------------

### Django Template Inheritance and Loading

Source: https://github.com/sqlalchemy/mako/blob/main/examples/bench/django/templates/template.html

Demonstrates extending a base template and loading custom template tags. Use this for basic template structure.

```html
{% extends "base.html" %} {% load bench %} ${title|escape} {% block body %}
```

--------------------------------

### Override Cache Key

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/caching.rst

Use the 'cache_key' argument to specify a custom key for caching. This example uses the filename of the calling template to create a unique cache key, useful for caching inherited content.

```mako
<%page cached="True" cache_key="${self.filename}"/>

${next.body()}

## rest of template
```

--------------------------------

### Rendering with Explicit Context

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/usage.rst

Illustrates rendering a template using an explicitly created Mako Context object. This provides finer control over the rendering environment, including the output buffer and variable namespace.

```python
from mako.template import Template
from mako.runtime import Context
from io import StringIO

mytemplate = Template("hello, ${name}!")
buf = StringIO()
ctx = Context(buf, name="jack")
mytemplate.render_context(ctx)
print(buf.getvalue())
```

--------------------------------

### Using capture() with a Def

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/filtering.rst

Demonstrates how to use the capture function to buffer the output of a def, allowing it to be concatenated with other strings.

```mako
${capture(somedef)}
```

--------------------------------

### Set Default Expression Filter via Page Tag

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/filtering.rst

Configure a default filter for all expression tags on a page using the 'expression_filter' argument in the <%page> tag. This example sets HTML escaping as the default.

```mako
<%page expression_filter="h"/>

Escaped text:  ${ "<html>some html</html>" }
```

--------------------------------

### Define Arguments for Mako Body Method

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/namespaces.rst

Illustrates how to explicitly define arguments for the body() method using the <%page> tag. This allows for custom argument signatures, including positional, keyword, and variable keyword arguments.

```mako
<%page args="x, y, someval=8, scope='foo', **kwargs"/>
```

--------------------------------

### Mako Template Caching

Source: https://context7.com/sqlalchemy/mako/llms.txt

Mako supports template output caching using `<%page cached="True">` or `<%def cached="True">`. The `template.cache` object provides methods for direct cache manipulation like `get`, `set`, and `invalidate`.

```python
from mako.template import Template

# ── Cache entire template body ────────────────────────────────────────────────
t = Template("""
<%page cached="True" cache_timeout="60"/>

```

--------------------------------

### Render Mako Template from Command Line

Source: https://context7.com/sqlalchemy/mako/llms.txt

Utilizes the `mako-render` CLI tool to render templates, passing variables, specifying template directories, and controlling output encoding or file redirection.

```bash
# ── Render a template file ────────────────────────────────────────────────────
mako-render --var name=Alice --var count=3 template.html > output.html

# ── Render from stdin ─────────────────────────────────────────────────────────
echo 'Hello ${name}!' | mako-render --var name=World

# ── Set template lookup directories ──────────────────────────────────────────
mako-render --template-dir /app/templates --var title=Home page.html

# ── Force output encoding ─────────────────────────────────────────────────────
mako-render --output-encoding utf-8 --var msg="héllo" template.html

# ── Write output to a file ────────────────────────────────────────────────────
mako-render --var x=42 --output-file result.html template.html
```

```python
# ── Use programmatically (same as CLI) ────────────────────────────────────────
from mako.cmd import cmdline
cmdline(["--var", "x=5", "--var", "y=hello", "my_template.mako"])
```

--------------------------------

### Handling Unicode Filenames

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

Demonstrates creating and writing to a file using a Unicode filename. Most file operations support Unicode, with transparent conversion to the system's filesystem encoding.

```python
filename = u"\x66\u0072\u0061\U0000006e" + unichr(231) + u"ais"
f = open(filename, 'w')
f.write('Some data\n')
f.close()
```

--------------------------------

### Buffering Def Output with buffered="True"

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/filtering.rst

Set 'buffered="True"' on a %def tag to send its output to a separate buffer, which is then returned as a string. This is an alternative to the default behavior where output is sent directly to the context buffer.

```mako
<%def name="somedef()" buffered="True">
    somedef's results
</%def>
```

--------------------------------

### Define and Use Mako Template with Unicode

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/chs_unicode_py3k.html

Illustrates defining a Mako template that includes Unicode strings and a reusable function definition. Use this for internationalized content.

```html
<% msg = '新中国的主席' %> <%def name="welcome(who, place='北京')"> Welcome ${who} to ${place}. ${name} 是 ${msg}  
${welcome('你')}
```

--------------------------------

### Define and Import Namespaces in Mako

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/namespaces.rst

Defines two functions in 'components.html' and imports them into 'index.html' under the 'comp' namespace.

```mako
## components.html
<%def name="comp1()">
    this is comp1
</%def>

<%def name="comp2(x)">
    this is comp2, x is ${x}
</%def>
```

```mako
## index.html
<%namespace name="comp" file="components.html"/>

Here's comp1:  ${comp.comp1()}
Here's comp2:  ${comp.comp2(x=5)}
```

--------------------------------

### Mako Namespace for Including Child Blocks

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/inheritance.rst

Illustrates how to use <%namespace> to call blocks from a child template within a parent template, allowing both base and child blocks to render.

```mako
## base.mako
${self.body()}
<%block name="SectionA">
    base.mako
</%block>

## parent.mako
<%inherit file="base.mako" />
<%namespace name="child" file="child.mako" />

<%block name="SectionA">
    ${child.SectionA()}
</%block>

## child.mako
<%block name="SectionA">
    child.mako
</%block>
```

--------------------------------

### Mako Namespace for Block Inheritance

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/inheritance.rst

Shows how to use <%namespace> to explicitly call blocks from included templates, enabling interaction with the inheritance structure. This is the correct way to achieve inheritance-like behavior with included files.

```mako
## partials.mako
<%block name="header">
    Global Header
</%block>

## parent.mako
<%namespace name="partials" file="partials.mako"/>
<%block name="header">
    ${partials.header()}
</%block>

## child.mako
<%inherit file="parent.mako" />
<%block name="header">
    Custom Header
</%block>
```

--------------------------------

### Mako Template with Undefined Definitions

Source: https://github.com/sqlalchemy/mako/wiki/imported_issue_attachments/102/broken_def_render.txt

This snippet demonstrates the Mako template syntax that can lead to a SyntaxException. Ensure all <%def> blocks are properly closed with '%>'.

```python
template = Template("""
    <%def name = "hi(name)">
        hi ${name}!
    </%def>
    <%def name = "bye(name)">
        bye ${name}!
    </%def>
")
```

--------------------------------

### Capture Output in Mako

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/namespaces.rst

Demonstrates how to capture the output of a caller's body using the capture function within a Mako runtime context. This is useful for processing or wrapping template content.

```python
from mako.runtime import supports_caller, capture

@supports_caller
def my_tag(context):
    return "<div>%s</div>" % \
            capture(context, context['caller'].body, x="foo", y="bar")
```

--------------------------------

### Mako Defs for Template Inheritance

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/inheritance.rst

Illustrates template inheritance using the <%def> tag, which was the precursor to <%block>. Defs require separate definition and invocation, offering more flexibility but less suitability for layout compared to blocks.

```mako
## index.html
<%inherit file="base.html"/>

<%def name="header()">
    this is some header content
</%def>

this is the body content.
```

```mako
## base.html
<html>
    <body>
        <div class="header">
            ${self.header()}
        </div>

        ${self.body()}

        <div class="footer">
            ${self.footer()}
        </div>
    </body>
</html>

<%def name="header()"/>
<%def name="footer()">
    this is the footer
</%def>
```

--------------------------------

### Template Rendering with Variables

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/usage.rst

Shows how to render a Mako template with dynamic content by passing variables as keyword arguments to the render method. These variables are accessible within the template using ${variable_name}.

```python
from mako.template import Template

mytemplate = Template("hello, ${name}!")
print(mytemplate.render(name="jack"))
```

--------------------------------

### Basic Mako Template Structure

Source: https://github.com/sqlalchemy/mako/blob/main/examples/bench/mako/template.html

Demonstrates variable interpolation, function definition, and includes in a Mako template. Use this for standard page rendering.

```html
${title} <%def name="greeting(name)">

hello ${name}!

<%include file="header.html"/> ${greeting(user)} ${greeting('me')} ${greeting('world')}

```

--------------------------------

### Dynamic Namespace Import

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/namespaces.rst

Imports a namespace dynamically where the file path is determined by a context variable. The 'context' variable must be explicitly named.

```mako
<%namespace name="dyn" file="${context['namespace_name']}"/>
```

--------------------------------

### Render Template from File with Caching

Source: https://context7.com/sqlalchemy/mako/llms.txt

Compiles and renders a Mako template from a file, with options for output encoding and error handling. Compiled Python modules can be cached to a specified directory for performance.

```python
from mako.template import Template

# ── Render from a file with module caching ────────────────────────────────────
file_tmpl = Template(
    filename="/path/to/templates/index.html",
    module_directory="/tmp/mako_modules",   # compiled .py files cached here
    output_encoding="utf-8",
    encoding_errors="replace",
)
output = file_tmpl.render()
```

--------------------------------

### Template Rendering Methods

Source: https://context7.com/sqlalchemy/mako/llms.txt

Details the different methods available for rendering a compiled Mako template: `render()`, `render_unicode()`, and `render_context()`, explaining their return types and use cases.

```APIDOC
## Template.render() / render_unicode() / render_context()

Render a template

The three rendering methods produce output from a compiled template. `render()` returns bytes when `output_encoding` is set, or a string otherwise. `render_unicode()` always returns a `str`. `render_context()` writes directly into an existing `Context` buffer.

### Usage

```python
from mako.template import Template
from mako.runtime import Context
import io

t = Template("""
<%page args="title, rows"/>
<h1>${title}</h1>
<table>
% for row in rows:
  <tr><td>${row[0]}</td><td>${row[1] | h}</td></tr>
% endfor
</table>
""")

# render() — returns str (no output_encoding set)
html = t.render(title="Report", rows=[("Alice", "<admin>"), ("Bob", "user")])
print(html)

# render_unicode() — always str, useful when output_encoding is set on the template
t_enc = Template("${msg}", output_encoding="utf-8")
text = t_enc.render_unicode(msg="hello")   # str, not bytes
assert isinstance(text, str)

# render_context() — write into a pre-existing Context
buf = io.StringIO()
ctx = Context(buf, title="Direct", rows=[("x", "y")])
t.render_context(ctx)
print(buf.getvalue())
```
```

--------------------------------

### Generated Template Code with Imports and Filters

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/filtering.rst

Illustrates the internal structure of a generated template when default filters and imports are configured. It shows how filters are applied to expressions.

```python
# ....
from mypackage import myfilter

def render_body(context):
    context.write(myfilter(str("some text")))
```

--------------------------------

### Basic Unicode String Creation in Python

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

Demonstrates creating a basic Unicode string using the `unicode()` constructor. By default, it uses ASCII encoding, which will raise an error for characters outside the ASCII range.

```python
>>> unicode('hello')
u'hello'
>>> s = unicode('hello')
>>> type(s)
<type 'unicode'>
```

--------------------------------

### Buffering Def Output with capture()

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/filtering.rst

Use the built-in 'capture' function to buffer the output of a Mako callable. Pass the function itself as the first argument, followed by any arguments for the function.

```mako
${capture(somedef, 17, 'hi', use_paging=True)}
```

--------------------------------

### Cross-Template Component Libraries with `<%namespace>`

Source: https://context7.com/sqlalchemy/mako/llms.txt

Shows how to import defs from another template or Python module using `<%namespace>`, enabling shared component libraries. Imported defs are called on the namespace object.

```python
from mako.lookup import TemplateLookup

lookup = TemplateLookup()

lookup.put_string("components.html", """
<%def name="button(label, style='primary')">
<button class="btn btn-${style}">${label | h}</button>
</%def>

<%def name="alert(msg, level='info')">
<div class="alert alert-${level}">${msg | h}</div>
</%def>
""")

lookup.put_string("page.html", """
<%namespace name="ui" file="components.html"/>

<html><body>
  ${ui.alert("Welcome back!", level="success")}
  <form>
    ${ui.button("Submit")}
    ${ui.button("Cancel", style="secondary")}
  </form>
</body></html>
")

print(lookup.get_template("page.html").render())
# <html><body>
#   <div class="alert alert-success">Welcome back!</div>
#   <form>
#     <button class="btn btn-primary">Submit</button>
#     <button class="btn btn-secondary">Cancel</button>
#   </form>
# </body></html>
```

--------------------------------

### Define Inheriting Template (index.html)

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/inheritance.rst

This Mako template inherits from 'base.html' and defines a 'header' block and its main body content.

```mako
## index.html
<%inherit file="base.html"/>

<%block name="header">
    this is some header content
</%block>

this is the body content.
```

--------------------------------

### Mako def with arguments and defaults

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/defs.rst

Define defs with arguments, including keyword arguments with default values, similar to Python function signatures. Arguments follow Python's required/optional conventions.

```mako
${account(accountname='john')}

    <%def name="account(accountname, type='regular')">
        account name: ${accountname}, type: ${type}
    </%def>
```

--------------------------------

### Looping Constructs in Mako

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/syntax.rst

Use % for and % endfor to create loops, similar to Python's for loops. Full Python control expressions are supported.

```mako
% for a in ['one', 'two', 'three', 'four', 'five']:
    % if a[0] == 't':
    its two or three
    % elif a[0] == 'f':
    four/five
    % else:
    one
    % endif
% endfor
```

--------------------------------

### File-Based Template with Module Caching

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/usage.rst

Explains how to enable caching for file-based Mako templates by specifying a 'module_directory'. This improves performance by saving the compiled Python module to the filesystem for reuse.

```python
from mako.template import Template

mytemplate = Template(filename='/docs/mytmpl.txt', module_directory='/tmp/mako_modules')
print(mytemplate.render())
```

--------------------------------

### Custom Greeting Template Tag

Source: https://github.com/sqlalchemy/mako/blob/main/examples/bench/django/templates/template.html

Illustrates calling a custom 'greeting' template tag with different arguments. Useful for dynamic content generation.

```html
{% greeting user %}
```

```html
{% greeting "me" %}
```

```html
{% greeting "world" %}
```

--------------------------------

### Import All Names from Namespace

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/namespaces.rst

Imports all names from 'components.html' into the local namespace using the '*' operator. Note: This may decrease template performance in current Mako versions.

```mako
<%namespace file="components.html" import="*"/>

    Heres comp1:  ${comp1()}
    Heres comp2:  ${comp2(x=5)}
```

--------------------------------

### CacheImpl Interface

Source: https://github.com/sqlalchemy/mako/blob/main/doc/build/caching.rst

The base interface for Mako cache implementations.

```APIDOC
## CacheImpl

### Description
Base class for Mako cache implementations. Subclasses should implement methods for caching template output.

### Methods
- **get_or_create(key, creation_function, **kw)**: Retrieves a value from the cache or creates it using the provided function.
- **set(key, value, **kwargs)**: Sets a value in the cache.
- **get(key, **kwargs)**: Retrieves a value from the cache.
- **invalidate(key, **kwargs)**: Invalidates a specific key from the cache.

### Attributes
- **cache**: The cache object associated with the template.
- **cache.template**: The parent Template object.
- **cache.id**: The unique modulename of the template, useful for namespacing keys.
```

--------------------------------

### Define Strings for Translation in i18n.py

Source: https://github.com/sqlalchemy/mako/blob/main/test/templates/internationalization.html

Create a dedicated Python file (e.g., lib/i18n.py) to list strings that appear in templates, ensuring they are picked up by translation tools.

```python
from base import _
_('Good Morning')
```