Configuration

All Environment configuration options.

Environment Constructor

from kida import Environment, FileSystemLoader

env = Environment(
    loader=FileSystemLoader("templates/"),
    autoescape=True,
    auto_reload=True,
    cache_size=400,
    fragment_cache_size=1000,
    fragment_ttl=300.0,
)

Core Options

loader

Template source provider.

# FileSystemLoader
loader = FileSystemLoader("templates/")

# Multiple paths
loader = FileSystemLoader(["templates/", "shared/"])

# DictLoader
loader = DictLoader({"page.html": "..."})

autoescape

HTML auto-escaping for output.

# Always escape
autoescape=True

# Never escape
autoescape=False

# Conditional by filename
def should_escape(name):
    if name is None:
        return True
    return name.endswith((".html", ".xml"))

autoescape=should_escape

auto_reload

Check for template source changes.

# Development: check for changes
auto_reload=True

# Production: skip checks
auto_reload=False

Cache Options

cache_size

Maximum compiled templates to cache.

# Small cache (testing)
cache_size=10

# Large cache (production)
cache_size=1000

fragment_cache_size

Maximum{% cache %}fragments to cache.

fragment_ttl

Fragment cache time-to-live in seconds.

# Short TTL for development
fragment_ttl=1.0

# Longer TTL for production
fragment_ttl=3600.0  # 1 hour

fragment_ttl is the default for {% cache %}blocks. You can override TTL per block:

{% cache "user-" ~ user.id, ttl="5m" %}
    {{ render_profile(user) }}
{% end %}

Supported ttlformats in templates:

• Numeric seconds (ttl=30, ttl=0.5)
• Duration strings ("30s", "5m", "2h", "1d")

bytecode_cache

Persistent bytecode cache for cold-start performance.

from kida.bytecode_cache import BytecodeCache

# Auto-detect (default)
bytecode_cache=None

# Explicit disable
bytecode_cache=False

# Custom location
bytecode_cache=BytecodeCache("__pycache__/kida/")

static_context

Static values for partial evaluation at compile time. Expressions that depend only on these values are evaluated during compilation and replaced with constants in the bytecode — enabling near-str.format() speed for static regions (e.g. site.title, config.base_url).

# Site-wide config available in all templates
env = Environment(
    loader=FileSystemLoader("templates/"),
    static_context={"site": site_config, "config": app_config},
)

# from_string() accepts its own static_context kwarg (takes precedence)
template = env.from_string("{{ site.title }}", static_context={"site": {"title": "My Site"}})

Applied automatically to all templates loaded via get_template(). Use from_string(source, static_context={...})to override per-call.

Lexer Options

Control template syntax delimiters.

block_start / block_end

Tag delimiters.

variable_start / variable_end

Output delimiters.

comment_start / comment_end

Comment delimiters.

Custom Delimiters

# Ruby-like syntax
env = Environment(
    block_start="<%",
    block_end="%>",
    variable_start="<%=",
    variable_end="%>",
    comment_start="<%#",
    comment_end="%>",
)

Whitespace Options

trim_blocks

Remove newline after block tags.

lstrip_blocks

Remove leading whitespace before block tags.

env = Environment(
    trim_blocks=True,
    lstrip_blocks=True,
)

Behavior Options

strict_none

Strict None comparison in sorting.

# Lenient (default): None sorts last
strict_none=False

# Strict: raise error on None
strict_none=True

strict_undefined

Strict attribute access — raiseUndefinedError on missing attributes instead of returning the _Undefinedsentinel.

# Lenient (default): missing attributes return _Undefined sentinel
strict_undefined=False

# Strict: missing attributes raise UndefinedError immediately
strict_undefined=True

When enabled, {{ user.typo }}raises immediately instead of rendering as empty string. Useful for catching attribute typos during development. Error messages distinguish between "Undefined variable", "Undefined attribute", and "Undefined key".

jinja2_compat_warnings

EmitMigrationWarning when {% set %}is used inside blocks where Jinja2 scoping would differ from Kida.

# Enable for migration (recommended when porting from Jinja2)
jinja2_compat_warnings=True

When enabled, using {% set x = ... %} inside {% if %}, {% for %}, or other blocks emits a MigrationWarning (K-WARN-002) explaining that {% set %} is block-scoped in Kida and does not leak to the outer scope. The warning suggests {% export %} or {% let %}as alternatives.

fstring_coalescing

Enable f-string output coalescing optimization.

When enabled, the compiler merges consecutive output nodes (static text and simple expressions) into single f-string appends, reducing function call overhead by ~37% in output-heavy templates.

# Enabled (default) — recommended for production
fstring_coalescing=True

# Disable for debugging compiled output
fstring_coalescing=False

See Compiler Internals for details on how coalescing works.

pure_filters

Additional filters the compiler can treat as side-effect-free.

Filters in this set are assumed to have no side effects and can be coalesced into f-strings alongside built-in pure filters (escape, upper, lower, trim, default, etc.). When static_contextis provided, pure filters with fully static inputs are evaluated at compile time and replaced with constants.

# Manual registration via configuration
pure_filters={"markdown", "highlight", "currency"}

The preferred approach is the @pure decorator, which auto-registers filters as pure when added via add_filter():

from kida import Environment, pure

@pure
def currency(value, symbol="$"):
    return f"{symbol}{value:,.2f}"

env = Environment()
env.add_filter("currency", currency)
# "currency" is automatically added to pure_filters

validate_calls

Enable compile-time call-site validation for{% def %}functions.

When enabled, the compiler checks every{{ func(...) }} call against the matching {% def %} signature and emits UserWarningfor unknown parameters, missing required arguments, and other mismatches.

# Enable call validation (recommended for development/CI)
validate_calls=True

# Disabled (default) — no validation overhead
validate_calls=False

See Static Analysis — Call-Site Validation for programmatic API details.

preserve_ast

Preserve AST for template introspection.

# Enable introspection (default)
preserve_ast=True

# Disable to save memory
preserve_ast=False

max_extends_depth / max_include_depth

Resource limits for DoS protection. Configurable for deployments with deep template hierarchies.

# Deeper inheritance for complex sites
env = Environment(
    max_extends_depth=100,
    max_include_depth=75,
)

Exceeding these limits raises TemplateRuntimeError. See Security Hardening for details.

enable_htmx_helpers

Register HTMX helper globals (hx_request, hx_target, hx_trigger, hx_boosted, csrf_token).

When enabled, templates can usehx_request(), hx_target(), etc. Frameworks must set metadata via render_context().set_meta()before rendering. See Custom Globals for HTMX helper details.

Development vs Production

Development

env = Environment(
    loader=FileSystemLoader("templates/"),
    autoescape=True,
    auto_reload=True,          # Check for changes
    cache_size=50,             # Small cache
    fragment_ttl=1.0,          # Short TTL
)

Production

env = Environment(
    loader=FileSystemLoader("templates/"),
    autoescape=True,
    auto_reload=False,         # No reload checks
    cache_size=1000,           # Large cache
    fragment_ttl=3600.0,       # 1 hour TTL
)

Cache Methods

cache_info()

Get cache statistics.

info = env.cache_info()
print(info["template"])
# {'size': 5, 'max_size': 400, 'hits': 100, 'misses': 5, 'hit_rate': 0.95}

clear_cache(include_bytecode=False)

Clear all caches.

env.clear_cache()                    # Memory only
env.clear_cache(include_bytecode=True)  # Include disk

clear_template_cache(names=None)

Clear specific templates.

env.clear_template_cache()           # All
env.clear_template_cache(["base.html", "page.html"])  # Specific

clear_fragment_cache()

Clear fragment cache only.

env.clear_fragment_cache()

See Also

• API Reference — Environment methods
• Loading Templates — Loader configuration
• Performance — Optimization tips