Skip to content

steps

steps #

The steps table: every step a living process has open, and how far along it is.

StepRow dataclass #

One open step: what it is, who runs it, and how far along it is.

Attributes:

Name Type Description
id str

The step's identifier.
parent_id str | None

The step it opened beneath, if any.
call_key CallKey | None

The call key, when the step is a memoized call.
identity str | None

The function identity, when the step is a memoized call.
label str

What the step is doing.
owner_pid int

The process running it.
owner_boot int

That process's liveness nonce.
workspace Path | None

The workspace a memoized call computes in.
started_at float

When the step opened.
done int

How many units are done.
total int | None

How many there are, if known.
note str | None

The step's last message, if any.
fields dict[str, JSONValue]

The named values its notes carried.
Source code in capturegraph-lib/capturegraph/recipes/scratch/index/steps.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
@dataclass(frozen=True, slots=True)
class StepRow:
    """One open step: what it is, who runs it, and how far along it is.

    Attributes:
        id: The step's identifier.
        parent_id: The step it opened beneath, if any.
        call_key: The call key, when the step is a memoized call.
        identity: The function identity, when the step is a memoized call.
        label: What the step is doing.
        owner_pid: The process running it.
        owner_boot: That process's liveness nonce.
        workspace: The workspace a memoized call computes in.
        started_at: When the step opened.
        done: How many units are done.
        total: How many there are, if known.
        note: The step's last message, if any.
        fields: The named values its notes carried.
    """

    id: str
    parent_id: str | None
    call_key: CallKey | None
    identity: str | None
    label: str
    owner_pid: int
    owner_boot: int
    workspace: Path | None
    started_at: float
    done: int
    total: int | None
    note: str | None
    fields: dict[str, JSONValue]

all_rows(db) #

Every step row, oldest first.

Source code in capturegraph-lib/capturegraph/recipes/scratch/index/steps.py 
101
102
103
104
def all_rows(db: sqlite3.Connection) -> list[StepRow]:
    """Every step row, oldest first."""
    rows = db.execute(f"SELECT {_COLUMNS} FROM steps ORDER BY started_at").fetchall()
    return [_row(row) for row in rows]

delete(db, id) #

Forget the step id.

Source code in capturegraph-lib/capturegraph/recipes/scratch/index/steps.py 
96
97
98
def delete(db: sqlite3.Connection, id: str) -> None:
    """Forget the step ``id``."""
    db.execute("DELETE FROM steps WHERE id = ?", (id,))

upsert(db, row) #

Write row, replacing what the index held for its id.

Source code in capturegraph-lib/capturegraph/recipes/scratch/index/steps.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def upsert(db: sqlite3.Connection, row: StepRow) -> None:
    """Write ``row``, replacing what the index held for its ``id``."""
    db.execute(
        f"INSERT OR REPLACE INTO steps ({_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
        (
            row.id,
            row.parent_id,
            row.call_key.hex if row.call_key is not None else None,
            row.identity,
            row.label,
            row.owner_pid,
            row.owner_boot,
            str(row.workspace) if row.workspace is not None else None,
            row.started_at,
            row.done,
            row.total,
            row.note,
            json.dumps(row.fields),
        ),
    )