Module

rendering.template_functions.collections

Collection manipulation functions for templates.

Provides 15+ functions for filtering, sorting, and transforming lists and dicts. Includes advanced page querying and manipulation functions.

View source
18 Functions

Functions

register
Register collection functions with Jinja2 environment.
2 None 
def register(env: Environment, site: Site) -> None

Register collection functions with Jinja2 environment.

Parameters 2

Name Type Default Description
env Environment —
site Site —
_get_nested_value
Get nested value using dot notation (e.g., 'metadata.track_id').
2 Any 
def _get_nested_value(obj: Any, path: str) -> Any

Get nested value using dot notation (e.g., 'metadata.track_id').

Parameters 2

Name Type Default Description
obj Any —
path str —

Returns

Any

where
Filter items where key matches value using specified operator. Supports nested attribute access (e…
4 list[dict[str, Any]] 
def where(items: list[dict[str, Any]], key: str, value: Any = None, operator: str = 'eq') -> list[dict[str, Any]]

Filter items where key matches value using specified operator.

Supports nested attribute access (e.g., 'metadata.track_id') and comparison operators.

Parameters 4

Name Type Default Description
items list[dict[str, Any]] —

List of dictionaries or objects to filter
key str —

Dictionary key or attribute path to check (supports dot notation like 'metadata.track_id')
value Any None

Value to compare against (required for all operators)
operator str 'eq'

Comparison operator: 'eq' (default), 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not in'

Returns

list[dict[str, Any]] —

Filtered list

where_not
Filter items where key does not equal value. Supports nested attribute access (e.g., 'metadata.tra…
3 list[dict[str, Any]] 
def where_not(items: list[dict[str, Any]], key: str, value: Any) -> list[dict[str, Any]]

Filter items where key does not equal value.

Supports nested attribute access (e.g., 'metadata.track_id').

Parameters 3

Name Type Default Description
items list[dict[str, Any]] —

List of dictionaries or objects to filter
key str —

Dictionary key or attribute path to check (supports dot notation like 'metadata.track_id')
value Any —

Value to exclude

Returns

list[dict[str, Any]] —

Filtered list

group_by
Group items by key value.
2 dict[Any, list[dict… 
def group_by(items: list[dict[str, Any]], key: str) -> dict[Any, list[dict[str, Any]]]

Group items by key value.

Parameters 2

Name Type Default Description
items list[dict[str, Any]] —

List of dictionaries to group
key str —

Dictionary key to group by

Returns

dict[Any, list[dict[str, Any]]] —

Dictionary mapping key values to lists of items

sort_by
Sort items by key.
3 list[Any] 
def sort_by(items: list[Any], key: str, reverse: bool = False) -> list[Any]

Sort items by key.

Parameters 3

Name Type Default Description
items list[Any] —

List to sort
key str —

Dictionary key or object attribute to sort by
reverse bool False

Sort in descending order (default: False)

Returns

list[Any] —

Sorted list

limit
Limit items to specified count.
2 list[Any] 
def limit(items: list[Any], count: int) -> list[Any]

Limit items to specified count.

Parameters 2

Name Type Default Description
items list[Any] —

List to limit
count int —

Maximum number of items

Returns

list[Any] —

First N items

offset
Skip first N items.
2 list[Any] 
def offset(items: list[Any], count: int) -> list[Any]

Skip first N items.

Parameters 2

Name Type Default Description
items list[Any] —

List to skip from
count int —

Number of items to skip

Returns

list[Any] —

Items after offset

uniq
Remove duplicate items while preserving order.
1 list[Any] 
def uniq(items: list[Any]) -> list[Any]

Remove duplicate items while preserving order.

Parameters 1

Name Type Default Description
items list[Any] —

List with potential duplicates

Returns

list[Any] —

List with duplicates removed

flatten
Flatten nested lists into single list. Only flattens one level deep.
1 list[Any] 
def flatten(items: list[list[Any]]) -> list[Any]

Flatten nested lists into single list.

Only flattens one level deep.

Parameters 1

Name Type Default Description
items list[list[Any]] —

List of lists

Returns

list[Any] —

Flattened list

first
Get first item from list.
1 Any 
def first(items: list[Any]) -> Any

Get first item from list.

Parameters 1

Name Type Default Description
items list[Any] —

List to get first item from

Returns

Any —

First item or None if list is empty

last
Get last item from list.
1 Any 
def last(items: list[Any]) -> Any

Get last item from list.

Parameters 1

Name Type Default Description
items list[Any] —

List to get last item from

Returns

Any —

Last item or None if list is empty

reverse
Reverse a list.
1 list[Any] 
def reverse(items: list[Any]) -> list[Any]

Reverse a list.

Parameters 1

Name Type Default Description
items list[Any] —

List to reverse

Returns

list[Any] —

Reversed copy of list

_get_item_key
Get unique key for an item (for set operations).
1 Any 
def _get_item_key(item: Any) -> Any

Get unique key for an item (for set operations).

Parameters 1

Name Type Default Description
item Any —

Returns

Any

union
Combine two lists, removing duplicates (set union). Preserves order from first list, then adds ite…
2 list[Any] 
def union(items1: list[Any], items2: list[Any]) -> list[Any]

Combine two lists, removing duplicates (set union).

Preserves order from first list, then adds items from second list that aren't already present.

Parameters 2

Name Type Default Description
items1 list[Any] —

First list
items2 list[Any] —

Second list

Returns

list[Any] —

Combined list with duplicates removed

intersect
Get items that appear in both lists (set intersection).
2 list[Any] 
def intersect(items1: list[Any], items2: list[Any]) -> list[Any]

Get items that appear in both lists (set intersection).

Parameters 2

Name Type Default Description
items1 list[Any] —

First list
items2 list[Any] —

Second list

Returns

list[Any] —

List of items present in both lists

complement
Get items in first list that are not in second list (set difference).
2 list[Any] 
def complement(items1: list[Any], items2: list[Any]) -> list[Any]

Get items in first list that are not in second list (set difference).

Parameters 2

Name Type Default Description
items1 list[Any] —

First list (items to keep)
items2 list[Any] —

Second list (items to exclude)

Returns

list[Any] —

List of items in first list but not in second list

resolve_pages
Resolve page paths to Page objects. Used with query indexes to convert O(1) path lookups into Page…
2 list[Any] 
def resolve_pages(page_paths: list[str], site: Site) -> list[Any]

Resolve page paths to Page objects.

Used with query indexes to convert O(1) path lookups into Page objects: {% set blog_paths = site.indexes.section.get('blog') %} {% set blog_pages = blog_paths | resolve_pages %}

PERFORMANCE: Uses cached page path map from Site for O(1) lookups. The cache is automatically invalidated when pages are added/removed.

Parameters 2

Name Type Default Description
page_paths list[str] —

List of page source paths (strings)
site Site —

Site instance with pages

Returns

list[Any] —

List of Page objects