Quickstart¶

This page adds 3 tasks of a to-do list to a world. It marks 1 task done, asks 2 questions, writes 1 function and writes 1 sentence.

Real output

The code on this page is one script, quickstart.py. The documentation build runs the script. Each output on this page comes from that run.

1. Declare a type¶

from scriptt.world import Fact, Facts, Key, World, say


class Task(Fact):
    id: Key[str]
    title: str
    done: bool = False

A type gives the fields of 1 kind of fact. Here the type is Task. A task has an id, a title and a done flag.
A fact is 1 statement of a type, with its source and its dates. Example: the task t1 has the title "Buy milk".
Key[str] marks the key. The key names the thing that a fact is about. A later task with the same id is a new version of the same task.
done: bool = False gives a default. A new task is open.

2. Add 3 tasks¶

todo = World.new(Task)
for id, title in [("t1", "Buy milk"), ("t2", "Send the report"), ("t3", "Book a room")]:
    todo.add(
        Task(id=id, title=title),
        source="me",
        true_from="2 Nov 2026",
        known="2 Nov 2026 09:00",
    )

World.new(Task) makes an empty world for the type Task. A world keeps facts in a log. Each add writes 1 entry at the end of the log. Each add has 3 more arguments.

Argument	Meaning	Value here
`source`	Where the fact came from.	`"me"`
`true_from`	The date from which the fact is true.	2 Nov 2026
`known`	The time at which you got the fact.	2 Nov 2026 at 09:00

3. Ask what is true on a date¶

print(todo.on("2 Nov 2026").facts(Task))

id  title            done
t1  Buy milk         no
t2  Send the report  no
t3  Book a room      no

on gives a view. A view contains the facts that are true on 1 date. It is a World object that reads the same log. facts(Task) gives the tasks of the view as a table. On 2 Nov all 3 tasks are open.

4. Mark a task done¶

report = todo.on("2 Nov 2026").one(Task, id="t2")
todo.add(
    report.but(done=True),
    source="me",
    true_from="3 Nov 2026",
    known="4 Nov 2026 10:00",
)
print(todo.on("3 Nov 2026").facts(Task))

id  title            done
t1  Buy milk         no
t2  Send the report  yes
t3  Book a room      no

one(Task, id="t2") gives the task with the key t2.
but(done=True) gives a copy of the task with 1 field changed. A fact never changes. A copy with the same key is a new version of the task.
The report was done on 3 Nov. You wrote it down on 4 Nov at 10:00. Thus true_from is 3 Nov and known is 4 Nov at 10:00.

Output line	Meaning
2	The task `t1` is open.
3	The task `t2` is done from 3 Nov. The view of 3 Nov shows the new version.
4	The task `t3` is open.

5. Ask what you knew at a time¶

print(todo.on("3 Nov 2026").known("3 Nov 2026 18:00").facts(Task))

id  title            done
t1  Buy milk         no
t2  Send the report  no
t3  Book a room      no

known limits a view to the facts that you got by a time. At 18:00 on 3 Nov you did not have the new version. Thus the report is open in this view. The page What was true, and what you knew shows the 2 dates in more detail.

6. Write a function¶

def open_tasks(view: World) -> Facts[Task]:
    """The tasks that are not done on the date of the view."""
    return view.facts(Task).where(lambda task: not task.done)


print(open_tasks(todo.on("4 Nov 2026")))

id  title        done
t1  Buy milk     no
t3  Book a room  no

A function reads a view and gives an answer. open_tasks keeps the tasks for which not task.done is true. where takes the rule as a Python function. Facts[Task] is the type of the result. Your editor completes its fields, and your type checker checks it.

7. Write a sentence¶

today = todo.on("4 Nov 2026")
print(say(t"On {today.on_date} you have {open_tasks(today).count()} open tasks."))

On 4 Nov 2026 you have 2 open tasks.

say fills a Python t-string. A t-string is a string with the prefix t, new in Python 3.14. It keeps each {value} apart from the text. say writes each date as "4 Nov 2026" and each fact by its type and key.

Next¶

Page	Contents
Tutorial: a to-do app	Lists, due dates, mistakes, rules, changes and the functions of a to-do app.
What was true, and what you knew	The 2 dates of a fact and the 4 answers that they give.
Mental model	The words of the library, and 4 questions before you start.