templating.filters

Page actions AI-ready formats and sharing
Open LLM text
Share with AI
Ask Claude Ask ChatGPT Ask Gemini Ask Copilot
module

Built-in chirp template filters.

These are web-framework-specific filters auto-registered on every chirp kida Environment. They complement Kida's built-in filters with patterns common in server-rendered HTML + htmx apps.

Built-in chirp template filters.

These are web-framework-specific filters auto-registered on every chirp kida Environment. They complement Kida's built-in filters with patterns common in server-rendered HTML + htmx apps.

templating.filters

Name Type Default Description
type —
qualified_name —
element_type —
description —
source_file —
line_number —
is_autodoc —
autodoc_element —
_autodoc_template —
_autodoc_url_path —
_autodoc_page_type —
title —
doc_content_hash —

Symbols on this page

function bem

Build chirpui BEM class string: chirpui-{block} chirpui-{block}--{variant} etc.

Jump to symbol function attr

Output an HTML attribute when value is truthy, else empty string.

Shorthand for optional attributes without{% if %}blocks.

Jump to symbol function _serialize_attr_value

Serialize attribute value into a stable string.

Jump to symbol function html_attrs

Render HTML attributes from mapping or legacy raw string.

Contract:

  • dict / Mapping: escaped, deterministic HTML attributes
  • str / Markup: pass through…
Jump to symbol function field_errors

Extract validation errors for a single form field.

Safely navigates a{field: [messages]}dict, returning an empty list when errorsis None, missing, or…

Jump to symbol function qs

Append query-string parameters to a URL path.

Omits parameters whose values are falsy (None, "", 0, False) so callers can pass optional filters without…

Jump to symbol function timeago

Convert a unix timestamp to a human-readable relative time.

Jump to symbol function pluralize

Pluralize a word based on count.

Jump to symbol function format_time

Format a unix timestamp asHH:MM:SS(UTC).

Jump to symbol function url

Safelist URL for href attributes. Uses Kida's url_is_safe.

Returns the URL if the scheme is safe (http, https, relative), otherwise returns fallback. Use when…

Jump to symbol function island_props

Serialize a value for safe use indata-island-props.

Returns HTML-escaped JSON as Markup so templates can embed props without manual escaping:

<div data-island-props="{{…
Jump to symbol function island_attrs

Build a safe island mount attribute string.

Designed for framework-agnostic mount roots:

<div{{ island_attrs("editor", props=state, mount_id="editor-root") }}>
    ...
</div>
Jump to symbol function primitive_attrs

Build island attributes with primitive metadata conventions.

Jump to symbol function optimistic_attrs

Mount the blessedoptimistic_applyisland primitive.

Sugar overprimitive_attrs("optimistic_apply", ...). Put the htmx trigger (hx-postetc.) on the SAME element; this helper…

Jump to symbol
bem
function 
def bem(block: str, variant: str = '', modifier: str = '', cls: str = '') -> str

Build chirpui BEM class string: chirpui-{block} chirpui-{block}--{variant} etc.

Parameters

Name Type Default Description
block str —
variant str ''
modifier str ''
cls str ''
attr
function 
def attr(value: Any, name: str) -> str | Markup

Output an HTML attribute when value is truthy, else empty string.

Shorthand for optional attributes without{% if %}blocks.

Parameters

Name Type Default Description
value Any —
name str —
_serialize_attr_value
function 
def _serialize_attr_value(value: Any) -> str

Serialize attribute value into a stable string.

Parameters

Name Type Default Description
value Any —
html_attrs
function 
def html_attrs(value: Any) -> str | Markup

Render HTML attributes from mapping or legacy raw string.

Contract:

  • dict / Mapping: escaped, deterministic HTML attributes
  • str / Markup: pass through (legacy compatibility)
  • None / False: no output

Mapping values follow HTML attribute semantics:

  • True renders as a valueless attribute (e.g. disabled)
  • False / Noneare omitted
  • other values are escaped and rendered askey="value"

Parameters

Name Type Default Description
value Any —
field_errors
function 
def field_errors(errors: Any, field_name: str) -> list[str]

Extract validation errors for a single form field.

Safely navigates a{field: [messages]}dict, returning an empty list when errors is None, missing, or the field has no errors.

Parameters

Name Type Default Description
errors Any —
field_name str —
qs
function 
def qs(base: str, **params: Any) -> str

Append query-string parameters to a URL path.

Omits parameters whose values are falsy (None, "", 0, False) so callers can pass optional filters without manual guards.

Parameters

Name Type Default Description
base str —
**params Any —
timeago
function 
def timeago(unix_ts: int | float) -> str

Convert a unix timestamp to a human-readable relative time.

Parameters

Name Type Default Description
unix_ts int | float —
pluralize
function 
def pluralize(count: int, singular: str, plural: str | None = None) -> str

Pluralize a word based on count.

Parameters

Name Type Default Description
count int —
singular str —
plural str | None None
format_time
function 
def format_time(unix_ts: float) -> str

Format a unix timestamp asHH:MM:SS(UTC).

Parameters

Name Type Default Description
unix_ts float —
url
function 
def url(value: str, fallback: str = '#') -> str

Safelist URL for href attributes. Uses Kida's url_is_safe.

Returns the URL if the scheme is safe (http, https, relative), otherwise returns fallback. Use when building href from user or external data.

Parameters

Name Type Default Description
value str —
fallback str '#'
island_props
function 
def island_props(value: Any) -> Markup

Serialize a value for safe use indata-island-props.

Returns HTML-escaped JSON as Markup so templates can embed props without manual escaping:

<div data-island-props="{{ props | island_props }}"></div>

Parameters

Name Type Default Description
value Any —
island_attrs
function 
def island_attrs(name: str, props: Any | None = None, *, mount_id: str | None = None, version: str = '1', src: str | None = None, cls: str = '') -> Markup

Build a safe island mount attribute string.

Designed for framework-agnostic mount roots:

<div{{ island_attrs("editor", props=state, mount_id="editor-root") }}>
    ...
</div>

Parameters

Name Type Default Description
name str —
props Any | None None
mount_id str | None None
version str '1'
src str | None None
cls str ''
primitive_attrs
function 
def primitive_attrs(primitive: str, props: dict[str, Any] | None = None, *, mount_id: str | None = None, version: str = '1', src: str | None = None, cls: str = '') -> Markup

Build island attributes with primitive metadata conventions.

Parameters

Name Type Default Description
primitive str —
props dict[str, Any] | None None
mount_id str | None None
version str '1'
src str | None None
cls str ''
optimistic_attrs
function 
def optimistic_attrs(ops: list[dict[str, Any]] | dict[str, Any], *, region: str | None = None, mount_id: str | None = None, version: str = '1', pending_class: str = 'is-optimistic-pending', error_class: str = 'is-optimistic-error', cls: str = '') -> Markup

Mount the blessedoptimistic_applyisland primitive.

Sugar overprimitive_attrs("optimistic_apply", ...). Put the htmx trigger (hx-postetc.) on the SAME element; this helper only adds the optimistic mount metadata. The runtime appliesopslocally and instantly from the client's OWN pre-mutation snapshot, lets htmx do the real request, swaps the authoritative server fragment on success (last-write-wins), and reverts to the snapshot only when no authoritative fragment lands.

<button hx-post="/like" hx-swap="outerHTML"
        {{ optimistic_attrs([{"op": "toggleClass", "value": "liked"}],
                            mount_id="like-1") }}>...</button>

RaisesTypeError for a malformed op (non-object, or a non-string op name) andValueErrorfor a policy violation (unknown op, missing op arguments, or any server-correlation key), so the helper — the authoritative enforcement point — can never emit a mount that would grow per-client server view state. Validity is decided by the shared chirp.contracts.rules_islands.validate_optimistic_op, so the helper and the staticapp.check()contract never drift.

Parameters

Name Type Default Description
ops list[dict[str, Any]] | dict[str, Any] —
region str | None None
mount_id str | None None
version str '1'
pending_class str 'is-optimistic-pending'
error_class str 'is-optimistic-error'
cls str ''

View source · /home/runner/work/chirp/chirp/site/../src/chirp/templating/filters.py:1