utils.html

A string subclass marking content as safe (won't be auto-escaped).

The Markup class implements the__html__protocol used by template engines to identify pre-escaped content. When combined with regular strings via operators like+, the non-Markup strings are automatically escaped.

This is Kida's native implementation — no external dependencies required.

A string safe for JavaScript string literal context.

Similar to Markup but for JavaScript strings instead of HTML. Prevents accidental double-escaping in JS contexts.

A string wrapper that defers str evaluation.

Useful for expensive string operations that may not be needed. Commonly used with missing template variables or expensive lookups.

Thread-Safety: The lazy evaluation is NOT thread-safe. If you need thread-safe lazy evaluation, compute the value before passing to templates.

Escape a string for HTML (internal helper).

Uses O(n) single-pass str.translate() for all strings.

Rationale: benchmarks on 2026-01-11 (Python 3.14) showed the previous frozenset intersection "fast path" was slower for 64–8192 byte inputs with no escapable characters (154ns → 5.9µs for translate-only vs 569ns → 50µs with intersection). We now always translate; CPython returns the original string when no substitutions are needed.

Complexity: O(n) single pass. No backtracking, no regex.

Escape a value if it's a string but not Markup.

Used for escaping format arguments.

O(n) single-pass HTML escaping with type optimization.

Returns plain str (for template._escape use).

Complexity: O(n) single-pass using str.translate().

Security:

• Escapes &, <, >, ", '
• Strips NUL bytes () which can bypass some filters
• Objects with html() are returned as-is (already safe)

Optimizations:

1. Skip Markup objects (already safe)

   2. Skip objects with html() method (protocol-based safety)

   3. Skip numeric types (int, float, bool) - cannot contain HTML chars

   4. Single-pass translation instead of 5 chained .replace()

      The numeric type optimization provides ~2.5x speedup for number-heavy templates (benchmarks/test_benchmark_optimization_levers.py).

HTML escape returning Markup (for filter use).

Returns Markup object so result won't be escaped again by autoescape.

Check if attribute name is valid per HTML5 spec.

Uses O(n) single-pass check with frozenset for O(1) char lookup. No regex.

Convert dict to XML/HTML attributes string.

Escapes attribute values and formats as key="value" pairs. Returns Markup to prevent double-escaping when autoescape is enabled.

Attribute ordering: Python 3.7+ dicts maintain insertion order. Output order matches input dict order.

Security:

• Validates attribute names per HTML5 spec
• Warns on event handler attributes (onclick, onerror, etc.)
• Escapes all attribute values

Escape a value for use inside JavaScript string literals.

This escapes characters that could break out of a JS string or inject code. Use this when embedding user data in inline scripts.

Complexity: O(n) single pass using str.translate().

Escape a value for use in CSS contexts.

Protects against breaking out of quotes in properties or injecting malicious content into url() or @import.

Complexity: O(n) single pass using str.translate().

Check if a URL has a safe protocol scheme.

Protects against javascript:, vbscript:, and data: URLs that can execute code when used in href/src attributes.

Uses window-based parsing: O(n) single pass, no regex.

Return URL if safe, otherwise return fallback.

Use in templates where you need a safe URL value (href, src, etc.).

Remove HTML tags from string.

IMPORTANT: This is for DISPLAY purposes only, not security.

This function uses regex-based tag removal which can be bypassed with malformed HTML. It is suitable for:

• Displaying text previews
• Extracting text content for search indexing
• Formatting plain-text emails from HTML

For security (preventing XSS), always use html_escape() or the Markup class with autoescape enabled.

Uses pre-compiled regex for performance. O(n) single pass.

Format a string with HTML escaping of all arguments.

Like str.format() but escapes all arguments for HTML safety. The format string itself is trusted (not escaped).

This is a convenience wrapper around Markup().format().