Jinja2 Migration

{{ variable }}
{{ user.name }}
{{ items | join(", ") }}
{% if condition %}...{% end %}
{% for item in items %}...{% end %}
{% extends "base.html" %}
{% block content %}...{% end %}
{% include "partial.html" %}
{# comments #}

{# Jinja2 #}
{% if user %}...{% endif %}
{% for x in items %}...{% endfor %}
{% block nav %}...{% endblock %}

{# Kida #}
{% if user %}...{% end %}
{% for x in items %}...{% end %}
{% block nav %}...{% end %}

{# Jinja2 — filters read right-to-left #}
{{ title | truncate(50) | upper | escape }}

{# Kida — pipeline reads left-to-right #}
{{ title |> escape |> upper |> truncate(50) }}

{# Jinja2 — chained if/elif #}
{% if status == "active" %}
    <span class="green">Active</span>
{% elif status == "pending" %}
    <span class="yellow">Pending</span>
{% elif status == "inactive" %}
    <span class="red">Inactive</span>
{% else %}
    <span>Unknown</span>
{% endif %}

{# Kida — pattern matching #}
{% match status %}
    {% case "active" %}<span class="green">Active</span>
    {% case "pending" %}<span class="yellow">Pending</span>
    {% case "inactive" %}<span class="red">Inactive</span>
    {% case _ %}<span>Unknown</span>
{% end %}

{# Jinja2 #}
{% set name = "Alice" %}

{# Kida — three scoping options #}
{% set name = "Alice" %}      {# Block-scoped: doesn't leak out #}
{% let name = "Alice" %}      {# Template-wide: visible everywhere #}
{% export name = "Alice" %}   {# Exports to template scope from inner blocks #}
{% promote name = "Alice" %}  {# Alias for export — same behavior #}

{# Jinja2 — verbose default pattern #}
{% if title is not defined %}{% set title = "Untitled" %}{% endif %}

{# Kida — one line #}
{% let title ??= "Untitled" %}

{# Jinja2 — errors if value is None #}
{{ value | upper }}

{# Kida — skips filter on None, provides fallback #}
{{ value ?| upper ?? "N/A" }}
{{ user?.name ?|> upper ?|> trim ?? "Anonymous" }}

{% cache "sidebar" %}
    {# Expensive rendering cached automatically #}
    {% for item in nav_items %}
        <a href="{{ item.url }}">{{ item.title }}</a>
    {% end %}
{% end %}

pip install kida

from jinja2 import Environment, FileSystemLoader
from markupsafe import Markup

from kida import Environment, FileSystemLoader
from kida import Markup  # Built-in, no markupsafe

env = Environment(
    loader=FileSystemLoader('templates'),
    autoescape=select_autoescape(),
    extensions=['jinja2.ext.do'],
)

env = Environment(
    loader=FileSystemLoader('templates'),
    autoescape=True,
    cache_size=400,
    fragment_ttl=300.0,
)

{% if condition %}
    content
{% endif %}

{% for item in items %}
    {{ item }}
{% endfor %}

{% block content %}
    ...
{% endblock %}

{% if condition %}
    content
{% end %}

{% for item in items %}
    {{ item }}
{% end %}

{% block content %}
    ...
{% end %}

def format_money(value, currency='$'):
    return f'{currency}{value:,.2f}'

env.filters['money'] = format_money

def format_money(value, currency='$'):
    return f'{currency}{value:,.2f}'

env.add_filter('money', format_money)

# Or use the decorator
@env.filter()
def format_money(value, currency='$'):
    return f'{currency}{value:,.2f}'

def is_prime(n):
    return n > 1 and all(n % i for i in range(2, n))

env.tests['prime'] = is_prime

env.add_test('prime', is_prime)

# Or use the decorator
@env.test()
def is_prime(n):
    return n > 1 and all(n % i for i in range(2, n))

{{ title |> escape |> upper |> truncate(50) }}

{% match status %}
{% case "active" %}
    ✓ Active
{% case "pending" %}
    ⏳ Pending
{% case _ %}
    Unknown
{% end %}

{% cache "sidebar-" ~ user.id %}
    {{ render_sidebar(user) }}
{% end %}

from kida import Environment

env = Environment()
template = env.from_string("Hello, {{ name }}!")
result = template.render(name="World")
assert result == "Hello, World!"
print("✅ Migration successful!")

from kida import Markup  # Not from markupsafe

env.add_filter('name', func)  # Not env.filters['name'] = func

{% if x %}...{% end %}  # Not {% endif %}

{{ name }}
{{ user.email }}
{{ items[0] }}
{{ 1 + 2 }}

{{ user.name }}
{{ page.metadata.title }}

{{ data.key }}
{{ data["key-with-dashes"] }}

{# data = {"items": ["a", "b"], "keys": ["x", "y"]} #}

{{ data.items }}    {# → ["a", "b"] — the key, not dict.items() #}
{{ data.keys }}     {# → ["x", "y"] — the key, not dict.keys() #}

{{ items[0] }}
{{ items[-1] }}  {# Last item #}
{{ matrix[0][1] }}

{{ "<script>" }}

{{ html_content | safe }}

{{ cms_block | safe(reason="sanitized by bleach") }}

{{ name | upper }}
{{ title | escape | truncate(50) }}

{{ title |> escape |> upper |> truncate(50) }}

{# Traditional pipe #}
{{ items | sort(attribute='date') | first }}

{# Pipeline operator #}
{{ items |> sort(attribute='date') |> first }}

{# Without ?|> — errors if user.name is None #}
{{ user.name |> upper |> trim }}

{# With ?|> — safely returns None, then ?? provides fallback #}
{{ user?.name ?|> upper ?|> trim ?? "Anonymous" }}

{# Errors if value is None #}
{{ value | upper }}

{# Safely skips — returns None, then ?? provides fallback #}
{{ value ?| upper ?? "N/A" }}

{# Chain multiple optional filters #}
{{ config?.debug ?| string ?? "unset" }}

{{ user.nickname | default("Anonymous") }}
{{ count | default(0) }}

{{ missing | d("fallback") }}

{{ price * 1.1 }}
{{ "Hello, " + name }}
{{ items | length > 0 }}
{{ value if condition else fallback }}

{{ "Hello" }}
{{ 'World' }}
{{ "It's fine" }}
{{ 'Say "hi"' }}

{{ "Hello, " + name }}
{{ count + " items" }}
{{ "/path/" ~ id ~ "/action" }}
hx-post="{{ '/chains/' ~ chain_id ~ '/add-step' }}"

{{ name.upper() }}
{{ items.count(x) }}
{{ text.split(',')[0] }}

{{ range(10) }}
{{ len(items) }}
{{ dict(a=1, b=2) }}

{% if user.is_admin %}
    <span class="badge">Admin</span>
{% elif user.is_moderator %}
    <span class="badge">Mod</span>
{% else %}
    <span class="badge">User</span>
{% end %}

{{ "Active" if is_active else "Inactive" }}

{% if user and user.is_active %}
{% if not disabled %}
{% if a or b %}
{% if (a and b) or c %}

{% if count > 0 %}
{% if status == "active" %}
{% if value in allowed_values %}
{% if item is defined %}

{% for item in items %}
    <li>{{ item.name }}</li>
{% end %}

{% for item in items %}
    <li>{{ item.name }}</li>
{% else %}
    <li>No items found</li>
{% end %}

{% for item in items %}
    {{ loop.index }}      {# 1-based index #}
    {{ loop.index0 }}     {# 0-based index #}
    {{ loop.first }}      {# True on first iteration #}
    {{ loop.last }}       {# True on last iteration #}
    {{ loop.length }}     {# Total items #}
    {{ loop.revindex }}   {# Reverse index (1-based) #}
    {{ loop.revindex0 }}  {# Reverse index (0-based) #}
{% end %}

{% for key, value in data.items() %}
    {{ key }}: {{ value }}
{% end %}

{% for x, y, z in coordinates %}
    Point: ({{ x }}, {{ y }}, {{ z }})
{% end %}

{% for user in users if user.is_active %}
    {{ user.name }}
{% end %}

{% match status %}
{% case "active" %}
    ✓ Active
{% case "pending" %}
    ⏳ Pending
{% case "error" %}
    ✗ Error: {{ error_message }}
{% case _ %}
    Unknown status
{% end %}

{% match user %}
{% case {"role": "admin"} %}
    Full access
{% case {"role": "user", "verified": true} %}
    Standard access
{% case _ %}
    Limited access
{% end %}

{% let name = "Alice" %}
{% let items = [1, 2, 3] %}
{% let total = price * quantity %}
{{ name }}  → Alice

{% let x = "outer" %}
{% if true %}
    {% set x = "inner" %}
    {{ x }}  → inner
{% end %}
{{ x }}  → outer   {# set did not modify the outer variable #}

{% let total = 0 %}
{% for item in items %}
    {% export total = total + item.price %}
{% end %}
{{ total }}  → sum of all prices

{% for item in items %}
    {% promote first_item ??= item %}
{% end %}
{{ first_item }}  → first item in the list

{# Set defaults without overwriting existing values #}
{% let title ??= "Untitled" %}
{% let show_sidebar ??= true %}

{# In loops — capture only the first value #}
{% for item in items %}
    {% promote winner ??= item %}
{% end %}
{{ winner }}  → first item (??= is a no-op after that)

{# With context variables — respect what the caller passed #}
{% let page_class ??= "default" %}

{%- if true -%}
    trimmed
{%- end -%}

{{ name | upper }}
{{ title | truncate(50) }}
{{ items | join(", ") }}

{{ name | lower | capitalize }}
{{ text | striptags | truncate(100) }}

{{ title |> escape |> upper |> truncate(50) }}

{{ user?.name ?|> upper ?|> trim ?? "Anonymous" }}

{{ value ?| upper ?? "N/A" }}
{{ config?.debug ?| string ?? "unset" }}

{{ text | truncate(50) }}
{{ text | truncate(50, killwords=true) }}
{{ text | truncate(50, end="...") }}
{{ items | sort(attribute="date", reverse=true) }}

{% for post in posts | sort(attribute="date") %}
    {{ post.title }}
{% end %}

{# Multiple attributes #}
{% for page in pages | sort(attribute="weight,title") %}
    {{ page.title }}
{% end %}

{# Reverse order #}
{% for post in posts | sort(attribute="date", reverse=true) %}
    {{ post.title }}
{% end %}

{% for group in posts | groupby("category") %}
    <h2>{{ group.grouper }}</h2>
    {% for post in group.list %}
        {{ post.title }}
    {% end %}
{% end %}

{# Select items matching condition #}
{{ items | selectattr("is_active") }}
{{ items | selectattr("status", "eq", "published") }}

{# Reject items matching condition #}
{{ items | rejectattr("is_draft") }}

{{ html_content | safe }}

{# With reason for code review #}
{{ cms_block | safe(reason="sanitized by bleach library") }}

from kida import Environment

env = Environment()

def double(value):
    return value * 2

env.add_filter("double", double)

{{ 21 | double }}
{# Output: 42 #}

@env.filter()
def double(value):
    return value * 2

@env.filter("twice")  # Custom name
def my_double(value):
    return value * 2

@env.filter()
def truncate_words(value, count=10, end="..."):
    words = str(value).split()
    if len(words) <= count:
        return value
    return " ".join(words[:count]) + end

{{ text | truncate_words(5) }}
{{ text | truncate_words(10, end="[more]") }}

@env.filter()
def format_number(value, decimals=2, separator=","):
    formatted = f"{value:,.{decimals}f}"
    if separator != ",":
        formatted = formatted.replace(",", separator)
    return formatted

{{ price | format_number }}
{{ price | format_number(decimals=0) }}
{{ price | format_number(separator=".") }}

@env.filter()
def upper_safe(value):
    if value is None:
        return ""
    return str(value).upper()

from kida import Markup

@env.filter()
def bold(value):
    escaped = Markup.escape(str(value))
    return Markup(f"<b>{escaped}</b>")

@env.filter()
def link(value, url):
    escaped_text = Markup.escape(str(value))
    escaped_url = Markup.escape(str(url))
    return Markup(f'<a href="{escaped_url}">{escaped_text}</a>')

filters = {
    "double": lambda x: x * 2,
    "triple": lambda x: x * 3,
    "reverse": lambda x: x[::-1],
}

env.update_filters(filters)

@env.filter()
def currency(value, symbol="$", decimals=2):
    if value is None:
        return ""
    return f"{symbol}{value:,.{decimals}f}"

from datetime import datetime

@env.filter()
def format_date(value, pattern="%Y-%m-%d"):
    if value is None:
        return ""
    if isinstance(value, str):
        value = datetime.fromisoformat(value)
    return value.strftime(pattern)

import re

@env.filter()
def slugify(value):
    if value is None:
        return ""
    text = str(value).lower()
    text = re.sub(r"[^\w\s-]", "", text)
    return re.sub(r"[-\s]+", "-", text).strip("-")

@env.filter()
def pluralize(count, singular, plural=None):
    if plural is None:
        plural = singular + "s"
    return singular if count == 1 else plural

{{ items | length }} {{ items | length | pluralize("item") }}

# ✅ Pure: no side effects
@env.filter()
def process(value):
    return value.upper()

# ❌ Impure: modifies external state
counter = 0
@env.filter()
def count_calls(value):
    global counter
    counter += 1  # Side effect
    return value

@env.filter()
def safe_divide(value, divisor):
    if divisor == 0:
        return 0  # Or raise error
    return value / divisor

@env.filter()
def initials(name, separator=""):
    """
    Extract initials from a name.

    Args:
        name: Full name string
        separator: Character between initials

    Returns:
        Initials (e.g., "JD" for "John Doe")
    """
    if not name:
        return ""
    return separator.join(
        word[0].upper() for word in name.split() if word
    )