todo.list

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 List, Sequence

from .todo_item import Todo, TodoDraft, validate_draft  ← from todo.item ^1.0.0 · built alongside by fune
from .todo_item_validate_draft import trim_space
from .todo_item_validate_todo import is_utc_timestamp
from .todo_normalise_tags import normalise_tags  ← from todo.normalise-tags ^1.0.0 · built alongside by fune


def require_utc_now(now: str) -> None:
    """Refuse a clock reading that would not compare as a string with the stored ones."""
    if not is_utc_timestamp(now):
        raise ValueError("now must be a UTC timestamp like 2026-09-28T09:30:00Z")


def checked_draft(draft: TodoDraft) -> TodoDraft:
    """The draft as it will be stored (trimmed, blank notes None, tags normalised), checked.

    The first field in field order that fails validate_draft is the error.
    """
    notes = "" if draft.notes is None else trim_space(draft.notes)
    clean = TodoDraft(
        title=trim_space(draft.title),
        notes=None if notes == "" else notes,
        priority=draft.priority,
        due=draft.due,
        tags=list(normalise_tags(draft.tags)),
        recurrence=draft.recurrence,
    )
    verdict = validate_draft(clean)
    for field, message in verdict.errors.items():
        raise ValueError(f"invalid todo: {field}: {message}")
    return clean


def add_todo(todos: Sequence[Todo], draft: TodoDraft, id: str, now: str) -> List[Todo]:
    """Add a todo from the add form: open, created now, last in manual order, appended.

    Caller mistakes (id, clock) are reported before form mistakes (the draft).
    """
    if trim_space(id) == "":
        raise ValueError("a todo needs an id")
    if any(t.id == id for t in todos):
        raise ValueError(f'a todo with id "{id}" already exists')
    require_utc_now(now)
    clean = checked_draft(draft)
    order = 0
    for t in todos:
        if t.order + 1 > order:
            order = t.order + 1
    todo = Todo(
        id=id,
        title=clean.title,
        notes=clean.notes,
        done=False,
        priority=clean.priority,
        due=clean.due,
        tags=clean.tags,
        recurrence=clean.recurrence,
        created_at=now,
        completed_at=None,
        order=order,
    )
    return list(todos) + [todo]

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from dataclasses import replace
from typing import List, Sequence

from .todo_item import Todo, TodoDraft  ← from todo.item ^1.0.0 · built alongside by fune
from .todo_list_add_todo import checked_draft  ← addTodo, another function of this group · built into the same file, even by a slim install


def index_of_todo(todos: Sequence[Todo], id: str) -> int:
    """The position of the todo with this id, or the unknown-id error every list operation shares."""
    for i, t in enumerate(todos):
        if t.id == id:
            return i
    raise ValueError(f'no todo with id "{id}"')


def update_todo(todos: Sequence[Todo], id: str, draft: TodoDraft) -> List[Todo]:
    """Save the edit form; id, done state, timestamps, order and place are kept."""
    at = index_of_todo(todos, id)
    clean = checked_draft(draft)
    out = list(todos)
    out[at] = replace(
        todos[at],
        title=clean.title,
        notes=clean.notes,
        priority=clean.priority,
        due=clean.due,
        tags=clean.tags,
        recurrence=clean.recurrence,
    )
    return out

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from dataclasses import replace
from typing import List, Sequence

from .todo_item import Todo  ← from todo.item ^1.0.0 · built alongside by fune
from .todo_item_validate_draft import is_iso_date
from .todo_list_add_todo import require_utc_now  ← addTodo, another function of this group · built into the same file, even by a slim install
from .todo_list_update_todo import index_of_todo  ← updateTodo, another function of this group · built into the same file, even by a slim install
from .todo_next_occurrence import next_occurrence  ← from todo.next-occurrence ^1.0.0 · built alongside by fune


def require_today(today: str) -> None:
    """Refuse a today that is not a real YYYY-MM-DD date, whether or not a repeat needs it."""
    if not is_iso_date(today):
        raise ValueError("today must be a date like 2026-09-28")


def complete_todo(todo: Todo, now: str, today: str) -> Todo:
    """Complete one open todo; a repeating one stays open and rolls forward to its next occurrence."""
    if todo.recurrence is None:
        return replace(todo, done=True, completed_at=now)
    if todo.due is None:
        raise ValueError(f'repeating todo "{todo.id}" has no due date')
    return replace(todo, done=False, completed_at=None, due=next_occurrence(todo.recurrence, todo.due, today))


def toggle_todo(todos: Sequence[Todo], id: str, now: str, today: str) -> List[Todo]:
    """Tick or untick one todo. Reopening clears the completion time."""
    at = index_of_todo(todos, id)
    require_utc_now(now)
    require_today(today)
    out = list(todos)
    t = todos[at]
    out[at] = replace(t, done=False, completed_at=None) if t.done else complete_todo(t, now, today)
    return out

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 List, Sequence

from .todo_item import Todo  ← from todo.item ^1.0.0 · built alongside by fune
from .todo_list_update_todo import index_of_todo  ← updateTodo, another function of this group · built into the same file, even by a slim install


def remove_todo(todos: Sequence[Todo], id: str) -> List[Todo]:
    """Delete one todo; the others keep their order values (gaps are harmless)."""
    at = index_of_todo(todos, id)
    return [t for i, t in enumerate(todos) if i != at]

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 List, Sequence

from .todo_item import Todo  ← from todo.item ^1.0.0 · built alongside by fune


def clear_completed(todos: Sequence[Todo]) -> List[Todo]:
    """Every done todo removed, the rest untouched and in order."""
    return [t for t in todos if not t.done]

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from dataclasses import replace
from typing import List, Sequence

from .todo_item import Todo  ← from todo.item ^1.0.0 · built alongside by fune
from .todo_list_add_todo import require_utc_now  ← addTodo, another function of this group · built into the same file, even by a slim install
from .todo_list_toggle_todo import complete_todo, require_today  ← toggleTodo, another function of this group · built into the same file, even by a slim install


def toggle_all(todos: Sequence[Todo], now: str, today: str) -> List[Todo]:
    """Complete every open todo as toggle_todo would, or reopen all once none is open."""
    require_utc_now(now)
    require_today(today)
    if any(not t.done for t in todos):
        return [t if t.done else complete_todo(t, now, today) for t in todos]
    return [replace(t, done=False, completed_at=None) for t in todos]

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from dataclasses import replace
from typing import List, Sequence

from .todo_item import Todo  ← from todo.item ^1.0.0 · built alongside by fune
from .todo_list_update_todo import index_of_todo  ← updateTodo, another function of this group · built into the same file, even by a slim install


def move_todo(todos: Sequence[Todo], id: str, to_index: int) -> List[Todo]:
    """Move a todo to to_index in manual order (order, then array position) and renumber 0..n-1."""
    source = index_of_todo(todos, id)
    last = len(todos) - 1
    if isinstance(to_index, bool) or not isinstance(to_index, int) or to_index < 0 or to_index > last:
        raise ValueError(f"toIndex must be between 0 and {last}, received {to_index}")
    positions = sorted(range(len(todos)), key=lambda i: (todos[i].order, i))
    rest = [i for i in positions if i != source]
    rest.insert(to_index, source)
    return [replace(todos[i], order=n) for n, i in enumerate(rest)]