templating - API Specification

Version: v1.1.9 | Status: Active | Last Updated: February 2026

Overview

The templating module provides template rendering utilities with support for Jinja2 syntax, variable substitution, and template management.

Classes

TemplateEngine

Jinja2-based template rendering engine.

from codomyrmex.templating import TemplateEngine

Constructor

TemplateEngine(
    template_dir: Optional[str] = None,
    auto_escape: bool = True,
    undefined_strict: bool = False
)

Parameter	Type	Default	Description
template_dir	str	None	Directory containing templates
auto_escape	bool	True	Enable HTML auto-escaping
undefined_strict	bool	False	Raise error on undefined variables

Methods

render

def render(template: str, context: Dict[str, Any]) -> str

Render template string with context.

Parameter	Type	Description
template	str	Template string with Jinja2 syntax
context	Dict[str, Any]	Variables for template

Returns: str - Rendered output

Raises: TemplatingError if rendering fails

render_file

def render_file(template_name: str, context: Dict[str, Any]) -> str

Load and render template from file.

Parameter	Type	Description
template_name	str	Name of template file in template_dir
context	Dict[str, Any]	Variables for template

Returns: str - Rendered output

render_to_file

def render_to_file(template: str, context: Dict[str, Any], output_path: str) -> bool

Render template and write to file.

add_filter

def add_filter(name: str, func: Callable) -> None

Add custom filter function.

add_global

def add_global(name: str, value: Any) -> None

Add global variable accessible in all templates.

---

TemplateManager

Template collection management utility.

from codomyrmex.templating import TemplateManager

Methods

list_templates

def list_templates() -> List[str]

List available templates.

get_template

def get_template(name: str) -> str | Template | None

Get the registered template by name. String registrations return their source; object registrations return the original Template instance so its engine and identity are preserved. Missing names return None. The legacy module imports codomyrmex.templating.template_engine and codomyrmex.templating.template_manager remain supported.

create_template

def create_template(name: str, content: str) -> bool

Create new template.

delete_template

def delete_template(name: str) -> bool

Delete template by name.

---

Exceptions

TemplatingError

from codomyrmex.templating import TemplatingError

Raised when template operations fail. Inherits from CodomyrmexError.

---

Usage Examples

Basic Rendering

from codomyrmex.templating import TemplateEngine

engine = TemplateEngine()

template = "Hello, {{ name }}! You have {{ count }} messages."
result = engine.render(template, {"name": "World", "count": 5})
# Output: "Hello, World! You have 5 messages."

Template Files

from codomyrmex.templating import TemplateEngine

engine = TemplateEngine(template_dir="./templates")

# Render templates/email.html with context
html = engine.render_file("email.html", {
    "user": "John",
    "items": ["Item 1", "Item 2", "Item 3"]
})

Control Structures

template = """
{% for item in items %}
- {{ item.name }}: {{ item.price }}
{% endfor %}

{% if discount %}
Discount applied: {{ discount }}%
{% endif %}
"""

result = engine.render(template, {
    "items": [
        {"name": "Widget", "price": 10.00},
        {"name": "Gadget", "price": 25.00}
    ],
    "discount": 15
})

Custom Filters

from codomyrmex.templating import TemplateEngine

engine = TemplateEngine()

# Add custom filter
engine.add_filter("uppercase", lambda s: s.upper())

template = "{{ message | uppercase }}"
result = engine.render(template, {"message": "hello"})
# Output: "HELLO"

Code Generation

from codomyrmex.templating import TemplateEngine

engine = TemplateEngine()

python_template = '''
class {{ class_name }}:
    """{{ docstring }}"""
    
    def __init__(self{% for attr in attributes %}, {{ attr.name }}: {{ attr.type }}{% endfor %}):
{% for attr in attributes %}
        self.{{ attr.name }} = {{ attr.name }}
{% endfor %}
'''

code = engine.render(python_template, {
    "class_name": "Person",
    "docstring": "Represents a person.",
    "attributes": [
        {"name": "name", "type": "str"},
        {"name": "age", "type": "int"}
    ]
})

---

Template Syntax

Variables

• {{ variable }} - Output variable
• {{ obj.attribute }} - Access attribute
• {{ list[0] }} - Access list element

Filters

• {{ name | upper }} - Uppercase
• {{ name | lower }} - Lowercase
• {{ name | title }} - Title case
• {{ list | join(", ") }} - Join list
• {{ value | default("N/A") }} - Default value

Control

• {% if condition %}...{% endif %} - Conditional
• {% for item in list %}...{% endfor %} - Loop
• {% include "partial.html" %} - Include template
• {% macro name(args) %}...{% endmacro %} - Macro definition

---

Integration

Dependencies

• jinja2 - Template engine
• codomyrmex.logging_monitoring for logging
• codomyrmex.exceptions for error handling

Related Modules

• documentation - Documentation generation
• deployment - Code generation
• module_template - Module scaffolding

---

Navigation

• Human Documentation: README.md
• Technical Documentation: AGENTS.md
• Functional Specification: SPEC.md
• Parent: codomyrmex