Module

`environment.filters`

Built-in filters for Kida templates.

Filters transform values in template expressions using the pipe syntax:

{{ value | filter }}or{{ value | filter(arg1, arg2) }}

Constants for sort key tuples:

SORT_KEY_NONE: (1, 0, 0) - Used for None/empty values (sorts last) SORT_KEY_NUMERIC: (0, 0, value) - Used for numeric values SORT_KEY_STRING: (0, 1, value) - Used for string values

Categories:

String Manipulation:

capitalize,lower,upper,title: Case conversion
trim/strip: Remove whitespace
truncate: Shorten with ellipsis
replace,striptags: Text transformation
center,indent,wordwrap: Formatting

HTML/Security:

escape/e: HTML entity encoding (auto-applied with autoescape)
safe: Mark content as trusted HTML (skip escaping)
striptags: Remove HTML tags

Collections:

first,last: Get endpoints
length/count: Item count
sort: Sort sequence (withattribute=for objects)
reverse: Reverse order
unique: Remove duplicates
batch,slice: Group items
map,select,reject: Functional operations
selectattr,rejectattr: Filter by attribute
groupby: Group by attribute
join: Concatenate with separator

Numbers:

abs,round,int,float: Math operations
filesizeformat: Human-readable file sizes

Type Conversion:

string,int,float,list: Type coercion
tojson: JSON serialization (auto-escaped)

Debugging:

debug: Print variable info to stderr
pprint: Pretty-print value

Validation:

default/d: Fallback for None/undefined
require: Raise error if None

None-Resilient Behavior: Filters handle None gracefully (like Hugo):

{{ none | default('N/A') }}->'N/A'
{{ none | length }}->0
{{ none | first }}->None

Custom Filters:

>>> env.add_filter('double', lambda x: x * 2)
>>> env.add_filter('money', lambda x, currency='$': f'{currency}{x:,.2f}')

Or with decorator:

>>> @env.filter()
... def reverse_words(s):
...     return ' '.join(s.split()[::-1])

Functions

_make_sort_key_numeric 1 tuple[int, int, int | fl… ▼

Create sort key for numeric value.

def _make_sort_key_numeric(value: int | float) -> tuple[int, int, int | float]

Parameters

Name	Type	Description
`value`	`int \| float`

Returns

tuple[int, int, int | float]

_make_sort_key_string 1 tuple[int, int, str] ▼

Create sort key for string value.

def _make_sort_key_string(value: str) -> tuple[int, int, str]

Parameters

Name	Type	Description
`value`	`str`

Returns

tuple[int, int, str]

_filter_abs 1 Any ▼

Return absolute value.

def _filter_abs(value: Any) -> Any

Parameters

Name	Type	Description
`value`	`Any`

Returns

Any

_filter_capitalize 1 str ▼

Capitalize first character.

def _filter_capitalize(value: str) -> str

Parameters

Name	Type	Description
`value`	`str`

Returns

str

_filter_default 3 Any ▼

Return default if value is undefined or falsy. With None-resilient handling, e…

def _filter_default(value: Any, default: Any = '', boolean: bool = False) -> Any

Return default if value is undefined or falsy.

With None-resilient handling, empty string is treated as missing (like None). This matches Hugo behavior where nil access returns empty string.

Parameters

Name	Type	Description
`value`	`Any`
`default`	`Any`	Default:`''`
`boolean`	`bool`	Default:`False`

Returns

Any

_filter_escape 1 Markup ▼

HTML-escape the value. Returns a Markup object so the result won't be escaped …

def _filter_escape(value: Any) -> Markup

HTML-escape the value.

Returns a Markup object so the result won't be escaped again by autoescape. Uses optimized html_escape_filter from utils.html module.

Parameters

Name	Type	Description
`value`	`Any`

Returns

Markup

_filter_first 1 Any ▼

Return first item of sequence.

def _filter_first(value: Any) -> Any

Parameters

Name	Type	Description
`value`	`Any`

Returns

Any

_filter_int 3 int ▼

Convert to integer.

def _filter_int(value: Any, default: int = 0, strict: bool = False) -> int

Parameters

Name	Type	Description
`value`	`Any`	Value to convert to integer.
`default`	`int`	Default value to return if conversion fails (default: 0). Default:`0`
`strict`	`bool`	If True, raise TemplateRuntimeError on conversion failure instead of returning default (default: False). Default:`False`

Returns

int

_filter_join 2 str ▼

Join sequence with separator.

def _filter_join(value: Any, separator: str = '') -> str

Parameters

Name	Type	Description
`value`	`Any`
`separator`	`str`	Default:`''`

Returns

str

_filter_last 1 Any ▼

Return last item of sequence.

def _filter_last(value: Any) -> Any

Parameters

Name	Type	Description
`value`	`Any`

Returns

Any

_filter_length 1 int ▼

Return length of sequence.

def _filter_length(value: Any) -> int

Parameters

Name	Type	Description
`value`	`Any`

Returns

int

_filter_list 1 list[Any] ▼

Convert to list.

def _filter_list(value: Any) -> list[Any]

Parameters

Name	Type	Description
`value`	`Any`

Returns

list[Any]

_filter_lower 1 str ▼

Convert to lowercase.

def _filter_lower(value: str) -> str

Parameters

Name	Type	Description
`value`	`str`

Returns

str

_filter_replace 4 str ▼

Replace occurrences.

def _filter_replace(value: str, old: str, new: str, count: int = -1) -> str

Parameters

Name	Type	Description
`value`	`str`
`old`	`str`
`new`	`str`
`count`	`int`	Default:`-1`

Returns

str

_filter_reverse 1 Any ▼

Reverse sequence.

def _filter_reverse(value: Any) -> Any

Parameters

Name	Type	Description
`value`	`Any`

Returns

Any

_filter_safe 2 Any ▼

Mark value as safe (no HTML escaping).

def _filter_safe(value: Any, reason: str | None = None) -> Any

Parameters

Name	Type	Description
`value`	`Any`	Content to mark as safe for raw HTML output.
`reason`	`str \| None`	Optional documentation of why this content is trusted. Purely for code review and audit purposes - not used at runtime. Default:`None`

Returns

Any

_filter_sort 4 list[Any] ▼

Sort sequence with improved error handling for None values. When sorting fails…

def _filter_sort(value: Any, reverse: bool = False, case_sensitive: bool = False, attribute: str | None = None) -> list[Any]

Sort sequence with improved error handling for None values.

When sorting fails due to None comparisons, provides detailed error showing which items have None values for the sort attribute.

Parameters

Name	Type	Description
`value`	`Any`
`reverse`	`bool`	Default:`False`
`case_sensitive`	`bool`	Default:`False`
`attribute`	`str \| None`	Default:`None`

Returns

list[Any]

_filter_string 1 str ▼

Convert to string.

def _filter_string(value: Any) -> str

Parameters

Name	Type	Description
`value`	`Any`

Returns

str

_filter_title 1 str ▼

Title case.

def _filter_title(value: str) -> str

Parameters

Name	Type	Description
`value`	`str`

Returns

str

_filter_trim 2 str ▼

Strip whitespace or specified characters.

def _filter_trim(value: str, chars: str | None = None) -> str

Parameters

Name	Type	Description
`value`	`str`	String to trim
`chars`	`str \| None`	Optional characters to strip (default: whitespace) Default:`None`

Returns

str

_filter_truncate 5 str ▼

Truncate string to specified length.

def _filter_truncate(value: str, length: int = 255, killwords: bool = False, end: str = '...', leeway: int | None = None) -> str

Parameters

Name	Type	Description
`value`	`str`	String to truncate
`length`	`int`	Maximum length including end marker Default:`255`
`killwords`	`bool`	If False (default), truncate at word boundary; if True, cut mid-word Default:`False`
`end`	`str`	String to append when truncated (default: "...") Default:`'...'`
`leeway`	`int \| None`	Allow slightly longer strings before truncating (Jinja2 compat, ignored) Default:`None`

Returns

str

_filter_upper 1 str ▼

Convert to uppercase.

def _filter_upper(value: str) -> str

Parameters

Name	Type	Description
`value`	`str`

Returns

str

_filter_tojson 2 Any ▼

Convert value to JSON string (marked safe to prevent escaping).

def _filter_tojson(value: Any, indent: int | None = None) -> Any

Parameters

Name	Type	Description
`value`	`Any`
`indent`	`int \| None`	Default:`None`

Returns

Any

_filter_batch 3 list[Any] ▼

Batch items into groups of linecount.

def _filter_batch(value: Any, linecount: int, fill_with: Any = None) -> list[Any]

Parameters

Name	Type	Description
`value`	`Any`
`linecount`	`int`
`fill_with`	`Any`	Default:`None`

Returns

list[Any]

_filter_slice 3 list[Any] ▼

Slice items into number of groups.

def _filter_slice(value: Any, slices: int, fill_with: Any = None) -> list[Any]

Parameters

Name	Type	Description
`value`	`Any`
`slices`	`int`
`fill_with`	`Any`	Default:`None`

Returns

list[Any]

_filter_take 2 list[Any] ▼

Take the first N items from a sequence. Kida-native filter for readable pipeli…

def _filter_take(value: Any, count: int) -> list[Any]

Take the first N items from a sequence.

Kida-native filter for readable pipeline operations.

Parameters

Name	Type	Description
`value`	`Any`	Sequence to take from
`count`	`int`	Number of items to take

Returns

list[Any]

_filter_skip 2 list[Any] ▼

Skip the first N items from a sequence. Kida-native filter for readable pipeli…

def _filter_skip(value: Any, count: int) -> list[Any]

Skip the first N items from a sequence.

Kida-native filter for readable pipeline operations.

Parameters

Name	Type	Description
`value`	`Any`	Sequence to skip from
`count`	`int`	Number of items to skip

Returns

list[Any]

_filter_compact 1 list[Any] ▼

Remove None values (and optionally all falsy values) from a sequence. Enables …

def _filter_compact(value: Any) -> list[Any]

Remove None values (and optionally all falsy values) from a sequence.

Enables declarative list building with conditional items, replacing imperative {% do %} patterns.

Parameters

Name	Type	Description
`value`	`Any`	Sequence to compact

Returns

list[Any]

_filter_map 1 list[Any] ▼

Map an attribute or method from a sequence.

def _filter_map(value: Any, *args: Any) -> list[Any]

Parameters

Name	Type	Description
`value`	`Any`

Returns

list[Any]

_filter_selectattr 2 list[Any] ▼

Select items where attribute passes test.

def _filter_selectattr(value: Any, attr: str, *args: Any) -> list[Any]

Parameters

Name	Type	Description
`value`	`Any`
`attr`	`str`

Returns

list[Any]

_filter_rejectattr 2 list[Any] ▼

Reject items where attribute passes test.

def _filter_rejectattr(value: Any, attr: str, *args: Any) -> list[Any]

Parameters

Name	Type	Description
`value`	`Any`
`attr`	`str`

Returns

list[Any]

_filter_select 2 list[Any] ▼

Select items that pass a test.

def _filter_select(value: Any, test_name: str | None = None, *args: Any) -> list[Any]

Parameters

Name	Type	Description
`value`	`Any`
`test_name`	`str \| None`	Default:`None`

Returns

list[Any]

_filter_reject 2 list[Any] ▼

Reject items that pass a test.

def _filter_reject(value: Any, test_name: str | None = None, *args: Any) -> list[Any]

Parameters

Name	Type	Description
`value`	`Any`
`test_name`	`str \| None`	Default:`None`

Returns

list[Any]

_filter_groupby 2 list[Any] ▼

Group items by attribute with None-safe sorting. Items with None/empty values …

def _filter_groupby(value: Any, attribute: str) -> list[Any]

Group items by attribute with None-safe sorting.

Items with None/empty values for the attribute are grouped together and sorted last.

Parameters

Name	Type	Description
`value`	`Any`
`attribute`	`str`

Returns

list[Any]

_filter_striptags 1 str ▼

Strip HTML tags.

def _filter_striptags(value: str) -> str

Parameters

Name	Type	Description
`value`	`str`

Returns

str

_filter_wordwrap 3 str ▼

Wrap text at width.

def _filter_wordwrap(value: str, width: int = 79, break_long_words: bool = True) -> str

Parameters

Name	Type	Description
`value`	`str`
`width`	`int`	Default:`79`
`break_long_words`	`bool`	Default:`True`

Returns

str

_filter_indent 3 str ▼

Indent text lines.

def _filter_indent(value: str, width: int = 4, first: bool = False) -> str

Parameters

Name	Type	Description
`value`	`str`
`width`	`int`	Default:`4`
`first`	`bool`	Default:`False`

Returns

str

_filter_urlencode 1 str ▼

URL-encode a string.

def _filter_urlencode(value: str) -> str

Parameters

Name	Type	Description
`value`	`str`

Returns

str

_filter_pprint 1 str ▼

Pretty-print a value.

def _filter_pprint(value: Any) -> str

Parameters

Name	Type	Description
`value`	`Any`

Returns

str

_filter_xmlattr 1 Markup ▼

Convert dict to XML attributes. Returns Markup to prevent double-escaping when…

def _filter_xmlattr(value: dict[str, Any]) -> Markup

Convert dict to XML attributes.

Returns Markup to prevent double-escaping when autoescape is enabled.

Parameters

Name	Type	Description
`value`	`dict[str, Any]`

Returns

Markup

_filter_unique 3 list[Any] ▼

Return unique items.

def _filter_unique(value: Any, case_sensitive: bool = False, attribute: str | None = None) -> list[Any]

Parameters

Name	Type	Description
`value`	`Any`
`case_sensitive`	`bool`	Default:`False`
`attribute`	`str \| None`	Default:`None`

Returns

list[Any]

_filter_min 2 Any ▼

Return minimum value.

def _filter_min(value: Any, attribute: str | None = None) -> Any

Parameters

Name	Type	Description
`value`	`Any`
`attribute`	`str \| None`	Default:`None`

Returns

Any

_filter_max 2 Any ▼

Return maximum value.

def _filter_max(value: Any, attribute: str | None = None) -> Any

Parameters

Name	Type	Description
`value`	`Any`
`attribute`	`str \| None`	Default:`None`

Returns

Any

_filter_sum 3 Any ▼

Return sum of values.

def _filter_sum(value: Any, attribute: str | None = None, start: int = 0) -> Any

Parameters

Name	Type	Description
`value`	`Any`
`attribute`	`str \| None`	Default:`None`
`start`	`int`	Default:`0`

Returns

Any

_filter_attr 2 Any ▼

Get attribute from object or dictionary key. Returns "" for None/missing value…

def _filter_attr(value: Any, name: str) -> Any

Get attribute from object or dictionary key.

Returns "" for None/missing values (None-resilient, like Hugo).

Parameters

Name	Type	Description
`value`	`Any`
`name`	`str`

Returns

Any

_filter_get 3 Any ▼

Safe dictionary/object access that avoids Python method name conflicts. When a…

def _filter_get(value: Any, key: str, default: Any = None) -> Any

Safe dictionary/object access that avoids Python method name conflicts.

When accessing dict keys like 'items', 'keys', 'values', or 'get', using dotted access (e.g.,schema.items) returns the method, not the key value. This filter provides clean syntax for safe key access.

Parameters

Name	Type	Description
`value`	`Any`	Dict, object, or None to access
`key`	`str`	Key or attribute name to access
`default`	`Any`	Value to return if key doesn't exist (default: None) Default:`None`

Returns

Any

_filter_format 1 str ▼

Format string with args/kwargs.

def _filter_format(value: str, *args: Any, **kwargs: Any) -> str

Parameters

Name	Type	Description
`value`	`str`

Returns

str

_filter_center 2 str ▼

Center string in width.

def _filter_center(value: str, width: int = 80) -> str

Parameters

Name	Type	Description
`value`	`str`
`width`	`int`	Default:`80`

Returns

str

_filter_round 3 float ▼

Round a number to a given precision.

def _filter_round(value: Any, precision: int = 0, method: str = 'common') -> float

Parameters

Name	Type	Description
`value`	`Any`
`precision`	`int`	Default:`0`
`method`	`str`	Default:`'common'`

Returns

float

_filter_format_number 2 str ▼

Format a number with thousands separators.

def _filter_format_number(value: Any, decimal_places: int = 0) -> str

Parameters

Name	Type	Description
`value`	`Any`
`decimal_places`	`int`	Default:`0`

Returns

str

_filter_commas 1 str ▼

Format a number with commas as thousands separators. Alias for format_number w…

def _filter_commas(value: Any) -> str

Format a number with commas as thousands separators.

Alias for format_number without decimal places.

Parameters

Name	Type	Description
`value`	`Any`

Returns

str

_filter_dictsort 4 list[tuple[str, Any]] ▼

Sort a dict and return list of (key, value) pairs.

def _filter_dictsort(value: dict[str, Any], case_sensitive: bool = False, by: str = 'key', reverse: bool = False) -> list[tuple[str, Any]]

Parameters

Name	Type	Description
`value`	`dict[str, Any]`
`case_sensitive`	`bool`	Default:`False`
`by`	`str`	Default:`'key'`
`reverse`	`bool`	Default:`False`

Returns

list[tuple[str, Any]]

_filter_wordcount 1 int ▼

Count words in a string.

def _filter_wordcount(value: str) -> int

Parameters

Name	Type	Description
`value`	`str`

Returns

int

_filter_float 3 float ▼

Convert value to float.

def _filter_float(value: Any, default: float = 0.0, strict: bool = False) -> float

Parameters

Name	Type	Description
`value`	`Any`	Value to convert to float.
`default`	`float`	Default value to return if conversion fails (default: 0.0). Default:`0.0`
`strict`	`bool`	If True, raise TemplateRuntimeError on conversion failure instead of returning default (default: False). Default:`False`

Returns

float

_filter_filesizeformat 2 str ▼

Format a file size as human-readable.

def _filter_filesizeformat(value: int | float, binary: bool = False) -> str

Parameters

Name	Type	Description
`value`	`int \| float`
`binary`	`bool`	Default:`False`

Returns

str

_filter_require 3 Any ▼

Require a value to be non-None, raising a clear error if it is. **Usage:** {{ …

def _filter_require(value: Any, message: str | None = None, field_name: str | None = None) -> Any

Require a value to be non-None, raising a clear error if it is.

Usage: {{ user.name | require('User name is required') }} {{ config.api_key | require(field_name='api_key') }}

Parameters

Name	Type	Description
`value`	`Any`	The value to check
`message`	`str \| None`	Custom error message if value is None Default:`None`
`field_name`	`str \| None`	Field name for the default error message Default:`None`

Returns

Any

_filter_random 1 Any ▼

Return a random item from the sequence. Warning: This filter is impure (non-de…

def _filter_random(value: Any) -> Any

Return a random item from the sequence.

Warning: This filter is impure (non-deterministic).

Parameters

Name	Type	Description
`value`	`Any`	A sequence to pick from.

Returns

Any

_filter_shuffle 1 list[Any] ▼

Return a shuffled copy of the sequence. Warning: This filter is impure (non-de…

def _filter_shuffle(value: Any) -> list[Any]

Return a shuffled copy of the sequence.

Warning: This filter is impure (non-deterministic).

Parameters

Name	Type	Description
`value`	`Any`	A sequence to shuffle.

Returns

list[Any]

_filter_debug 3 Any ▼

Debug filter that prints variable info to stderr and returns the value unchange…

def _filter_debug(value: Any, label: str | None = None, max_items: int = 5) -> Any

Debug filter that prints variable info to stderr and returns the value unchanged.

Usage: {{ posts | debug }} -> Shows type and length {{ posts | debug('my posts') }} -> Shows with custom label {{ posts | debug(max_items=10) }} -> Show more items

Output example: DEBUG [my posts]: <list[5]> [0] Page(title='Getting Started', weight=10) [1] Page(title='Installation', weight=None) <-- None! ...

Parameters

Name	Type	Description
`value`	`Any`	The value to inspect
`label`	`str \| None`	Optional label for the output Default:`None`
`max_items`	`int`	Maximum number of items to show for sequences Default:`5`

Returns

Any

_debug_repr 2 str ▼

Create a compact repr for debug output.

def _debug_repr(value: Any, max_len: int = 60) -> str

Parameters

Name	Type	Description
`value`	`Any`
`max_len`	`int`	Default:`60`

Returns

str