Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.
from typing import Any, Dict, List, Sequence, Tuple
from .collections_search_text import fold_ascii ← from collections.search-text ^1.0.0 · built alongside by fune
from .collections_sort_by import sort_by ← from collections.sort-by ^1.0.0 · built alongside by fune
from .collections_sort_by_types import SortDirection
from .todo_item import Todo ← from todo.item ^1.0.0 · built alongside by fune
from .todo_item_validate_todo import is_utc_timestamp
from .todo_sort_types import TodoSortKey
_RANKS = {"none": 0, "low": 1, "medium": 2, "high": 3}
# Sort passes, least significant first; the last is the primary key and takes the direction.
_PASSES: Dict[str, Tuple[Tuple[str, str], ...]] = {
"manual": (("created", "asc"), ("order", "dir")),
"due": (("order", "asc"), ("rank", "desc"), ("due", "dir")),
"priority": (("order", "asc"), ("due", "asc"), ("rank", "dir")),
"created": (("order", "asc"), ("created", "dir")),
"title": (("order", "asc"), ("title", "dir")),
}
def _rank(priority: str) -> int:
if priority not in _RANKS:
raise ValueError(f'unknown priority "{priority}": expected none, low, medium or high')
return _RANKS[priority]
def _created_key(created_at: str) -> str:
"""A creation time that sorts as text: the fraction padded to nine digits."""
if not is_utc_timestamp(created_at):
raise ValueError(f'createdAt "{created_at}" is not a UTC timestamp, e.g. 2026-09-28T09:30:00Z')
fraction = created_at[20:-1] if len(created_at) > 20 else ""
return created_at[:19] + "." + fraction.ljust(9, "0")
def sort_todos(todos: Sequence[Todo], by: TodoSortKey, direction: SortDirection) -> List[Todo]:
"""Todos in list order for the chosen key: stable, direction on the primary key only."""
if not isinstance(by, str) or by not in _PASSES:
raise ValueError(f'unknown sort key "{by}": expected manual, due, priority, created or title')
if direction not in ("asc", "desc"):
raise ValueError(f'direction must be "asc" or "desc", received "{direction}"')
passes = _PASSES[by]
used = {field for field, _ in passes}
records: List[Dict[str, Any]] = []
for i, todo in enumerate(todos):
r: Dict[str, Any] = {"i": i, "order": todo.order}
if "created" in used:
r["created"] = _created_key(todo.created_at)
if "rank" in used:
r["rank"] = _rank(todo.priority)
if "due" in used:
r["due"] = todo.due
if "title" in used:
r["title"] = fold_ascii(todo.title)
records.append(r)
for field, d in passes:
records = sort_by(records, field, direction if d == "dir" else d) # type: ignore[assignment]
return [todos[r["i"]] for r in records]