roadkeep 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- roadkeep/__init__.py +79 -0
- roadkeep/adopting.py +2347 -0
- roadkeep/attesting.py +293 -0
- roadkeep/authoring.py +2117 -0
- roadkeep/backlog.py +767 -0
- roadkeep/blocking.py +1622 -0
- roadkeep/briefing.py +970 -0
- roadkeep/budgeting.py +2056 -0
- roadkeep/capturing.py +1699 -0
- roadkeep/claiming.py +1019 -0
- roadkeep/cli.py +638 -0
- roadkeep/commanding.py +487 -0
- roadkeep/config.py +1832 -0
- roadkeep/counting.py +376 -0
- roadkeep/criteria.py +933 -0
- roadkeep/deferring.py +708 -0
- roadkeep/describing.py +568 -0
- roadkeep/exporting.py +808 -0
- roadkeep/fixing.py +629 -0
- roadkeep/governing.py +934 -0
- roadkeep/graph.py +395 -0
- roadkeep/guarding.py +1028 -0
- roadkeep/history.py +2403 -0
- roadkeep/ids.py +301 -0
- roadkeep/installing.py +2145 -0
- roadkeep/kernel/__init__.py +24 -0
- roadkeep/kernel/document.py +1719 -0
- roadkeep/kernel/schema.py +2308 -0
- roadkeep/linting.py +4420 -0
- roadkeep/locking.py +209 -0
- roadkeep/markers.py +172 -0
- roadkeep/merging.py +1159 -0
- roadkeep/picking.py +772 -0
- roadkeep/provenance.py +789 -0
- roadkeep/queueing.py +752 -0
- roadkeep/ranking.py +139 -0
- roadkeep/referring.py +231 -0
- roadkeep/remaining.py +336 -0
- roadkeep/remedying.py +1989 -0
- roadkeep/rendering.py +1601 -0
- roadkeep/renumbering.py +503 -0
- roadkeep/repairing.py +295 -0
- roadkeep/reverting.py +144 -0
- roadkeep/scoping.py +708 -0
- roadkeep/screening.py +196 -0
- roadkeep/sections.py +4121 -0
- roadkeep/serving.py +2909 -0
- roadkeep/shipping.py +3993 -0
- roadkeep/showing.py +613 -0
- roadkeep/storing.py +224 -0
- roadkeep/verbs/__init__.py +26 -0
- roadkeep/verbs/adopting.py +974 -0
- roadkeep/verbs/authoring.py +566 -0
- roadkeep/verbs/declaring.py +335 -0
- roadkeep/verbs/linting.py +645 -0
- roadkeep/verbs/querying.py +2138 -0
- roadkeep/verbs/reading.py +307 -0
- roadkeep/verbs/refusing.py +146 -0
- roadkeep/verbs/sections.py +1433 -0
- roadkeep/verbs/shipping.py +819 -0
- roadkeep/weighing.py +380 -0
- roadkeep-0.2.0.dist-info/METADATA +453 -0
- roadkeep-0.2.0.dist-info/RECORD +67 -0
- roadkeep-0.2.0.dist-info/WHEEL +5 -0
- roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
- roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
- roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/picking.py
ADDED
|
@@ -0,0 +1,772 @@
|
|
|
1
|
+
"""What to work on next, and the reason it was chosen (RK11).
|
|
2
|
+
|
|
3
|
+
"What do I work on" is the question a roadmap is asked most often and answers worst: the
|
|
4
|
+
rule — *lowest-numbered task whose deps are all shipped* — is a join over two files that
|
|
5
|
+
costs reading both of them, every session, to learn one line. So it is a command, and the
|
|
6
|
+
answer carries **why**, because an unexplained pick cannot be checked and a pick nobody
|
|
7
|
+
checks is a pick nobody trusts (L5).
|
|
8
|
+
|
|
9
|
+
Three tiers, in this order, and each one is a fact rather than a taste:
|
|
10
|
+
|
|
11
|
+
1. **Work already in progress.** A 🛠 line says someone started; picking something else
|
|
12
|
+
leaves it half-done, and half-done work is the one state the marker set can express
|
|
13
|
+
and no count can repair. This tier is why `pick` does not simply mean "lowest".
|
|
14
|
+
2. **The declared priority.** A `## Priority` section of the roadmap, or `priority =
|
|
15
|
+
["RK14", "Block D"]` in `roadkeep.toml` (L6), applied in the order written. The section
|
|
16
|
+
wins where both exist, and `roadkeep.queueing` is the reader — the objection this tier
|
|
17
|
+
used to state, that Shio's "## Priority queue" is a paragraph about why reachability
|
|
18
|
+
comes first, is about *interpreting prose* (L4) and does not reach a list this tool
|
|
19
|
+
renders (RK325). What the move buys is that the queue's tokens name work that **leaves**,
|
|
20
|
+
and the file the plan is in is the one every departure already rewrites.
|
|
21
|
+
3. **The lowest ready id**, numerically. Blocks are ordered by dependency, so the id
|
|
22
|
+
order already follows the build order and needs no second opinion.
|
|
23
|
+
|
|
24
|
+
What never gets offered: anything :class:`Readiness.BLOCKED`, and — the distinction that
|
|
25
|
+
makes this useful — anything :class:`Readiness.OUTSIDE`. A task waiting on work this
|
|
26
|
+
backlog does not track never becomes ready by shipping tasks, so offering it as "next"
|
|
27
|
+
sends the caller at something that cannot be finished (RK28). :class:`Readiness.PAUSED`
|
|
28
|
+
is the third (RK92) and gets its own number for the same reason: a backlog stuck on
|
|
29
|
+
deferred deps is stuck on a decision nobody revisited, which no amount of shipping moves.
|
|
30
|
+
|
|
31
|
+
The stalled list is the other half of the same honesty: a 🛠 task that is *blocked* is
|
|
32
|
+
reported beside the answer, because that is the state a reader most needs to know about
|
|
33
|
+
and the one tier 1 cannot pick.
|
|
34
|
+
|
|
35
|
+
**Ready and implementable are two different states** (RK83). The tiers rank by id and
|
|
36
|
+
never by marker, so a block holding both designs and ideas answers a caller who asked to
|
|
37
|
+
execute it with a design session. Two things follow, and neither is a fourth tier: the
|
|
38
|
+
answer *says* when the line it chose still needs designing, because the complaint was
|
|
39
|
+
never that it chose wrongly but that it chose silently; and ``designed`` sets those lines
|
|
40
|
+
aside, because the bias belongs to the caller's intent and not to the ranking — a block
|
|
41
|
+
whose ideas are never offered is a block whose ideas are never designed.
|
|
42
|
+
|
|
43
|
+
**One backlog and two workers is one answer too few** (RK119). Every tier above is a pure
|
|
44
|
+
function of the file, so a second caller reading an unchanged roadmap is handed the line the
|
|
45
|
+
first one took — tier 1 most confidently of all, since a 🛠 line is *evidence* somebody
|
|
46
|
+
started. So a claim that is still live is stepped around before the tiers see it, and
|
|
47
|
+
:func:`take` is the door that makes one: it answers and flips the marker inside a single
|
|
48
|
+
serialised transaction, because a pick that answered and then wrote would be two steps with
|
|
49
|
+
the race in the middle. What a claim is, how it expires and why it names nobody is
|
|
50
|
+
:mod:`roadkeep.claiming`; what is here is that a held line is **named** in the answer rather
|
|
51
|
+
than silently absent, which is the same rule ``designed`` follows for the lines it sets
|
|
52
|
+
aside — and the only way a caller can recognise a claim as its own.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
from __future__ import annotations
|
|
56
|
+
|
|
57
|
+
from collections.abc import Mapping, Sequence
|
|
58
|
+
from dataclasses import dataclass, replace
|
|
59
|
+
from enum import StrEnum
|
|
60
|
+
|
|
61
|
+
from roadkeep import claiming
|
|
62
|
+
from roadkeep.authoring import StatusChange, set_status
|
|
63
|
+
from roadkeep.backlog import Backlog, DepStatus, Readiness, Stage, Standing, id_order
|
|
64
|
+
from roadkeep.claiming import Held
|
|
65
|
+
from roadkeep.config import Config
|
|
66
|
+
from roadkeep.kernel.document import Entry, declares, shading
|
|
67
|
+
from roadkeep.locking import exclusive
|
|
68
|
+
from roadkeep.queueing import declared
|
|
69
|
+
from roadkeep.kernel.schema import IN_PROGRESS, Dep
|
|
70
|
+
|
|
71
|
+
#: How many runners-up an answer carries. Bounded on purpose: the value of `pick` is that
|
|
72
|
+
#: its output fits in a tool result, and a ranked list of everything is the file again.
|
|
73
|
+
ALTERNATIVES = 3
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class Tier(StrEnum):
|
|
77
|
+
"""Which rule produced the answer. Printed, so the pick can be argued with."""
|
|
78
|
+
|
|
79
|
+
STARTED = "in-progress"
|
|
80
|
+
PRIORITY = "declared-priority"
|
|
81
|
+
LOWEST = "lowest-ready-id"
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
@dataclass(frozen=True, slots=True)
|
|
85
|
+
class Stalled:
|
|
86
|
+
"""A started task that cannot be continued, and what is holding it."""
|
|
87
|
+
|
|
88
|
+
id: str
|
|
89
|
+
blockers: tuple[str, ...]
|
|
90
|
+
#: The live claim on this line, where there is one (RK152). Its own field and not
|
|
91
|
+
#: :attr:`Choice.held`, which is the ready lines a claim kept out of the ranking: one word
|
|
92
|
+
#: for both facts is how this report came to be silent about the second. The two states it
|
|
93
|
+
#: separates are "somebody started this and hit a wall", which invites unblocking it, and
|
|
94
|
+
#: "somebody is on this now, and the dep is what they are waiting for", which does not.
|
|
95
|
+
claimed: Held | None = None
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
#: How many releasing ids a waiting row names (RK1304), bounded for RK1301's reason: a
|
|
99
|
+
#: priority waiting on eleven things is one whose next step is a decision and not a command,
|
|
100
|
+
#: and the count says that where the roster would only spend the answer saying it.
|
|
101
|
+
RELEASES = 4
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
@dataclass(frozen=True, slots=True)
|
|
105
|
+
class Waiting:
|
|
106
|
+
"""A declared priority nothing ready answers, and what would release it (RK1304).
|
|
107
|
+
|
|
108
|
+
Observed over four consecutive sessions on a port whose roadmap declares Priority as
|
|
109
|
+
Block H then Block I. Every line in both was blocked, so the pick fell through to the
|
|
110
|
+
lowest ready id and said so: *the roadmap's queue names nothing ready*. True, and one step
|
|
111
|
+
short — Block H held one line, blocked on a single task in another block, and nothing in
|
|
112
|
+
the answer said which. The caller who wanted the priority had to open the roadmap, read
|
|
113
|
+
the queue, find the block's lines, read their deps and look each one up, which is the
|
|
114
|
+
reading this verb exists to replace, done by hand, at the moment it was least obvious.
|
|
115
|
+
|
|
116
|
+
Beside the pick and never instead of it: the pick may still be the right call when the
|
|
117
|
+
blocker is expensive. The case that makes this worth having is the other one, where it is
|
|
118
|
+
cheap and nobody looked.
|
|
119
|
+
"""
|
|
120
|
+
|
|
121
|
+
#: The queue token, as the queue spells it — a `Block X` or an id.
|
|
122
|
+
token: str
|
|
123
|
+
#: Open lines the token names. Every one of them blocked, or this row would not exist.
|
|
124
|
+
lines: int
|
|
125
|
+
#: The ids whose shipping would release one of those lines: their unsatisfied deps,
|
|
126
|
+
#: deduplicated and in id order, bounded by :data:`RELEASES`.
|
|
127
|
+
releases: tuple[str, ...] = ()
|
|
128
|
+
#: How many there are in all, so a cut roster is never read as a short one.
|
|
129
|
+
of: int = 0
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
@dataclass(frozen=True, slots=True)
|
|
133
|
+
class Lacking:
|
|
134
|
+
"""A ready line this caller cannot finish, and what it would take (RK1297).
|
|
135
|
+
|
|
136
|
+
Named and never merely counted, for the reason :attr:`Choice.held` is: a number the
|
|
137
|
+
caller cannot read is a line it asks about twice. Here the id is not even the actionable
|
|
138
|
+
half — :attr:`missing` is, because what closes this is somebody with a DualSense on the
|
|
139
|
+
desk rather than any command the caller could run.
|
|
140
|
+
"""
|
|
141
|
+
|
|
142
|
+
id: str
|
|
143
|
+
#: The declared requirements this caller did not say it has, in the line's own order.
|
|
144
|
+
missing: tuple[str, ...]
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
@dataclass(frozen=True, slots=True)
|
|
148
|
+
class Choice:
|
|
149
|
+
"""The answer, or the reasoned absence of one."""
|
|
150
|
+
|
|
151
|
+
entry: Entry | None
|
|
152
|
+
tier: Tier | None
|
|
153
|
+
reason: str
|
|
154
|
+
#: The block the question was scoped to, when it was (RK40). Every count and every
|
|
155
|
+
#: alternative below is then about that block and nothing else.
|
|
156
|
+
block: str | None = None
|
|
157
|
+
#: The next few ready tasks, in the same order the pick came from.
|
|
158
|
+
alternatives: tuple[str, ...] = ()
|
|
159
|
+
ready: int = 0
|
|
160
|
+
blocked: int = 0
|
|
161
|
+
outside: int = 0
|
|
162
|
+
#: Open lines waiting on work somebody set aside (RK92). Its own number for RK28's
|
|
163
|
+
#: reason: a backlog stuck on paused deps is stuck on a decision, not on a task.
|
|
164
|
+
paused: int = 0
|
|
165
|
+
stalled: tuple[Stalled, ...] = ()
|
|
166
|
+
#: Whether the chosen line still needs designing (RK83). Said, never acted on: it is
|
|
167
|
+
#: the sentence that stops the pick being silent about which of the two states it is.
|
|
168
|
+
needs_design: bool = False
|
|
169
|
+
#: How many ready lines ``designed`` set aside. 0 whenever the flag was not passed, so
|
|
170
|
+
#: a non-zero value is always the caller's own filter and never a fact about the file.
|
|
171
|
+
undesigned: int = 0
|
|
172
|
+
#: The ready lines a live claim kept out of the ranking (RK119). Named and not counted,
|
|
173
|
+
#: because a claim names nobody: a caller can only tell one of these is its own by
|
|
174
|
+
#: reading the id, and a number it cannot read is a line it will ask about twice.
|
|
175
|
+
held: tuple[Held, ...] = ()
|
|
176
|
+
#: The ready lines a requirement this caller does not have kept out of the ranking
|
|
177
|
+
#: (RK1297). Beside `held` and `undesigned` because it is the third thing that narrows an
|
|
178
|
+
#: offer without narrowing the truth — `ready` still counts these — and apart from both
|
|
179
|
+
#: because it is the only one nothing the caller does will change: a claim expires and a
|
|
180
|
+
#: design gets written, and a PS5 does not arrive because a command was run.
|
|
181
|
+
lacking: tuple[Lacking, ...] = ()
|
|
182
|
+
#: What the declared priority is waiting on, where nothing ready answers it (RK1304).
|
|
183
|
+
#: Empty on every other call — a queue the pick came *from* has nothing to be waiting for,
|
|
184
|
+
#: and a project that declares none has no queue to ask about.
|
|
185
|
+
waiting: tuple[Waiting, ...] = ()
|
|
186
|
+
#: What became of the block the question was scoped to (RK429). Absent on an unscoped
|
|
187
|
+
#: pick, where there is no label to have a state — and carried even when a line *was*
|
|
188
|
+
#: chosen, so a caller reading the payload never has to ask a second command what the
|
|
189
|
+
#: scope it just picked from is.
|
|
190
|
+
standing: Standing | None = None
|
|
191
|
+
|
|
192
|
+
@property
|
|
193
|
+
def found(self) -> bool:
|
|
194
|
+
return self.entry is not None
|
|
195
|
+
|
|
196
|
+
@property
|
|
197
|
+
def stage(self) -> Stage | None:
|
|
198
|
+
"""The scope's state as the one word a caller branches on, or None if unscoped."""
|
|
199
|
+
return None if self.standing is None else self.standing.stage
|
|
200
|
+
|
|
201
|
+
@property
|
|
202
|
+
def counts(self) -> str:
|
|
203
|
+
"""All four numbers, always: a zero is the fact a reader is checking for."""
|
|
204
|
+
return (
|
|
205
|
+
f"{self.ready} ready, {self.blocked} blocked, "
|
|
206
|
+
f"{self.outside} blocked outside the backlog, "
|
|
207
|
+
f"{self.paused} blocked on paused work"
|
|
208
|
+
)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def pick(
|
|
212
|
+
config: Config,
|
|
213
|
+
block: str | None = None,
|
|
214
|
+
designed: bool = False,
|
|
215
|
+
*,
|
|
216
|
+
backlog: Backlog | None = None,
|
|
217
|
+
claims: bool = True,
|
|
218
|
+
available: Sequence[str] = (),
|
|
219
|
+
) -> Choice:
|
|
220
|
+
"""Apply the three tiers to the roadmap, and say which one answered.
|
|
221
|
+
|
|
222
|
+
``block`` scopes every part of the answer — the tiers, the counts, the alternatives —
|
|
223
|
+
so that "nothing to pick" is a statement about *that* block (RK40). Unscoped, the
|
|
224
|
+
lowest ready id can live in another block, and reading that as "this block is
|
|
225
|
+
finished" is a mistake the ids being non-sequential makes easy.
|
|
226
|
+
|
|
227
|
+
``designed`` sets aside the ready lines whose marker says the design is unwritten
|
|
228
|
+
(RK83), for a caller who asked to *execute* rather than to plan. It narrows what may
|
|
229
|
+
be chosen and nothing else: ``ready`` still counts every ready line, because the
|
|
230
|
+
number of lines this backlog could start is not a fact the caller's intent changes.
|
|
231
|
+
|
|
232
|
+
``available`` is what the caller says it has, and it is the axis the other two are not
|
|
233
|
+
(RK1297): a line whose `(needs: …)` names anything absent from it is set aside, counted
|
|
234
|
+
and **named**. Empty by default, and that default is the decision — the caller who
|
|
235
|
+
cannot press a button is the one who does not think to say so, and a `pick` that offered
|
|
236
|
+
hardware work to it was the five identical answers this exists to stop. A person at the
|
|
237
|
+
desk says `--have`, and gets the line the agent could not have.
|
|
238
|
+
|
|
239
|
+
``backlog`` answers over files somebody else read — the state a transaction is about to
|
|
240
|
+
write, or a revision (RK104) — and ``claims = False`` asks the question the tiers were
|
|
241
|
+
before RK119: *what do the files alone say*. Both exist for the projection (RK39), which
|
|
242
|
+
is published, has to be idempotent, and is derived from the repository — so a next-ready
|
|
243
|
+
line that moved because a claim in one checkout expired would put a README permanently
|
|
244
|
+
one temp file away from stale, with nothing in any commit to explain it.
|
|
245
|
+
"""
|
|
246
|
+
if backlog is None:
|
|
247
|
+
backlog = Backlog.load(config)
|
|
248
|
+
if block is not None and block not in backlog.declared_blocks():
|
|
249
|
+
declared = sorted(backlog.declared_blocks())
|
|
250
|
+
raise KeyError(
|
|
251
|
+
f"no heading declares {config.schema.block_named(block)}"
|
|
252
|
+
# And not every label that is declared (RK296): the caller typed a block, they are
|
|
253
|
+
# not choosing from a menu of the other eighty-nine.
|
|
254
|
+
f"{declares(declared)}"
|
|
255
|
+
# As at the write refusal (RK216): scoping a pick to `A` where `AJ` is declared
|
|
256
|
+
# would otherwise read as "that block is empty" dressed as "that block is absent".
|
|
257
|
+
f"{shading(block, declared)}"
|
|
258
|
+
)
|
|
259
|
+
scope = f" in {config.schema.block_named(block)}" if block else ""
|
|
260
|
+
# Read before the survey and kept whatever the answer is (RK429): the ledger is what
|
|
261
|
+
# tells a finished block from a heading opened before its lines, and the tiers below
|
|
262
|
+
# cannot see it — they rank open lines, and both of those states have none.
|
|
263
|
+
standing = None if block is None else backlog.standing(block)
|
|
264
|
+
considered = [
|
|
265
|
+
entry
|
|
266
|
+
for entry in backlog.roadmap.entries
|
|
267
|
+
if block is None or entry.task.block == block
|
|
268
|
+
]
|
|
269
|
+
# Over every line in scope and not only the ready ones (RK152): a blocked 🛠 line was
|
|
270
|
+
# never a candidate and is still the line a reader most needs to know somebody is on.
|
|
271
|
+
claimed = (
|
|
272
|
+
{entry.id: entry for entry in claiming.live(config, considered)} if claims else {}
|
|
273
|
+
)
|
|
274
|
+
survey = _survey(backlog, considered, claimed)
|
|
275
|
+
ordered = sorted(survey.ready, key=lambda e: id_order(e.task.id, config.schema))
|
|
276
|
+
# Before the tiers and before `designed`, because a claim is a fact about the checkout
|
|
277
|
+
# while the flag is the caller's intent (RK119) — and because tier 1 would otherwise
|
|
278
|
+
# prefer exactly the held line, its premise being that a 🛠 line is work to continue.
|
|
279
|
+
held = tuple(claimed[e.task.id] for e in ordered if e.task.id in claimed)
|
|
280
|
+
if held:
|
|
281
|
+
ordered = [e for e in ordered if e.task.id not in claimed]
|
|
282
|
+
# Before the tiers, for the claim's own reason (RK1297): tier 1 prefers a 🛠 line, and a
|
|
283
|
+
# started line whose hardware is not on this desk is exactly the one that comes back
|
|
284
|
+
# every call — somebody began it where the controller was, and this caller cannot
|
|
285
|
+
# continue it. Stepped around here, so the tiers rank only what could actually be done.
|
|
286
|
+
has = frozenset(available)
|
|
287
|
+
lacking = tuple(
|
|
288
|
+
Lacking(entry.task.id, missing)
|
|
289
|
+
for entry in ordered
|
|
290
|
+
if (missing := tuple(one for one in entry.task.requires if one not in has))
|
|
291
|
+
)
|
|
292
|
+
if lacking:
|
|
293
|
+
short = {one.id for one in lacking}
|
|
294
|
+
ordered = [e for e in ordered if e.task.id not in short]
|
|
295
|
+
# Narrowed after the ordering and not before it, so `ready` keeps counting what the
|
|
296
|
+
# file holds: the caller's intent decides what may be offered, never what is true.
|
|
297
|
+
offered = [e for e in ordered if not config.schema.needs_design(e.task.status)]
|
|
298
|
+
set_aside = len(ordered) - len(offered) if designed else 0
|
|
299
|
+
if designed:
|
|
300
|
+
ordered = offered
|
|
301
|
+
counts = {
|
|
302
|
+
"block": block,
|
|
303
|
+
"blocked": survey.blocked,
|
|
304
|
+
"outside": survey.outside,
|
|
305
|
+
"paused": survey.paused,
|
|
306
|
+
"stalled": survey.stalled,
|
|
307
|
+
"undesigned": set_aside,
|
|
308
|
+
"held": held,
|
|
309
|
+
"lacking": lacking,
|
|
310
|
+
"standing": standing,
|
|
311
|
+
# Asked of the whole survey and not of `ordered` alone (RK1304): the question is what
|
|
312
|
+
# the queue's *blocked* lines are waiting on, and `ordered` is by construction the
|
|
313
|
+
# lines that are waiting on nothing.
|
|
314
|
+
"waiting": _waiting(backlog, config, ordered, considered),
|
|
315
|
+
}
|
|
316
|
+
if not ordered:
|
|
317
|
+
return Choice(
|
|
318
|
+
entry=None,
|
|
319
|
+
tier=None,
|
|
320
|
+
reason=_absence(
|
|
321
|
+
scope,
|
|
322
|
+
open_lines=bool(considered),
|
|
323
|
+
held=held,
|
|
324
|
+
set_aside=set_aside,
|
|
325
|
+
lacking=lacking,
|
|
326
|
+
standing=standing,
|
|
327
|
+
),
|
|
328
|
+
ready=len(survey.ready),
|
|
329
|
+
**counts,
|
|
330
|
+
)
|
|
331
|
+
|
|
332
|
+
chosen, tier, why = _first(ordered, config)
|
|
333
|
+
rest = tuple(e.task.id for e in ordered if e is not chosen)[:ALTERNATIVES]
|
|
334
|
+
needs_design = config.schema.needs_design(chosen.task.status)
|
|
335
|
+
reason = f"{why}{scope}" if tier is Tier.LOWEST else why
|
|
336
|
+
if needs_design:
|
|
337
|
+
# Appended to the tier's own reason rather than replacing it: the tier still fired
|
|
338
|
+
# and is still a fact, and what was missing was never the choice but the caveat.
|
|
339
|
+
reason = f"{reason} — it still needs designing, which `--designed` skips"
|
|
340
|
+
return Choice(
|
|
341
|
+
entry=chosen,
|
|
342
|
+
tier=tier,
|
|
343
|
+
reason=reason,
|
|
344
|
+
alternatives=rest,
|
|
345
|
+
ready=len(survey.ready),
|
|
346
|
+
needs_design=needs_design,
|
|
347
|
+
**counts,
|
|
348
|
+
)
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
@dataclass(frozen=True, slots=True)
|
|
352
|
+
class Claim:
|
|
353
|
+
"""A line taken, and the marker change that took it (RK119)."""
|
|
354
|
+
|
|
355
|
+
#: Absent where the caller named the id (RK149): there was no choice, so there is no tier
|
|
356
|
+
#: and no runner-up to report, and inventing an empty one would read as a pick that found
|
|
357
|
+
#: nothing rather than a pick that never happened.
|
|
358
|
+
choice: Choice | None
|
|
359
|
+
#: Absent when there was nothing to claim — an empty answer, not a refused write.
|
|
360
|
+
change: StatusChange | None = None
|
|
361
|
+
|
|
362
|
+
@property
|
|
363
|
+
def taken(self) -> bool:
|
|
364
|
+
return self.change is not None
|
|
365
|
+
|
|
366
|
+
|
|
367
|
+
def take(
|
|
368
|
+
config: Config,
|
|
369
|
+
block: str | None = None,
|
|
370
|
+
designed: bool = False,
|
|
371
|
+
*,
|
|
372
|
+
available: Sequence[str] = (),
|
|
373
|
+
) -> Claim:
|
|
374
|
+
"""Answer and claim in one indivisible step (RK119).
|
|
375
|
+
|
|
376
|
+
The lock is around **both**, and that is the whole mechanism: a pick that answered and
|
|
377
|
+
then flipped the marker would be two commands with the race between them, which is the
|
|
378
|
+
defect one layer along rather than the fix. What the claim consists of is the 🛠 the
|
|
379
|
+
roadmap now carries — durable, and git's to move — plus its date in
|
|
380
|
+
:mod:`roadkeep.claiming`, which is neither.
|
|
381
|
+
|
|
382
|
+
Nothing ready is not a failure: the empty answer comes back exactly as `pick` gave it,
|
|
383
|
+
because a caller asking for work and being told there is none got the fact it asked for.
|
|
384
|
+
The marker is written through `set_status`, so every refusal that guards a marker guards
|
|
385
|
+
this one too — a sibling file already stating status, a duplicated id — and a line
|
|
386
|
+
already at 🛠 whose claim expired is re-dated without a write it does not need.
|
|
387
|
+
|
|
388
|
+
**The claim is that marker write and nothing else** (RK159). Dating it here as well would
|
|
389
|
+
be a second writer of the one rule this design states out loud — a claim follows the
|
|
390
|
+
marker — and two writers of one rule is how the doors came to disagree to begin with.
|
|
391
|
+
"""
|
|
392
|
+
with exclusive(config.root):
|
|
393
|
+
choice = pick(config, block, designed, available=available)
|
|
394
|
+
if choice.entry is None:
|
|
395
|
+
return Claim(choice=choice)
|
|
396
|
+
change = set_status(config, choice.entry.task.id, IN_PROGRESS)
|
|
397
|
+
# The entry is replaced by the line as written, so the answer shows the marker the
|
|
398
|
+
# caller now holds rather than the one it was chosen under.
|
|
399
|
+
return Claim(choice=replace(choice, entry=change.entry), change=change)
|
|
400
|
+
|
|
401
|
+
|
|
402
|
+
def hold(config: Config, task_id: str) -> Claim:
|
|
403
|
+
"""Claim the line a caller named, refusing one another worker is already holding (RK149).
|
|
404
|
+
|
|
405
|
+
The second door, because a *named* claim is a different act from a chosen one, and the
|
|
406
|
+
difference is only visible on a collision: :func:`take` steps around a live claim because
|
|
407
|
+
it was choosing anyway, and here there is nowhere to step — so the answer is
|
|
408
|
+
:class:`~roadkeep.claiming.AlreadyHeld`, and never a second worker sent at one line.
|
|
409
|
+
|
|
410
|
+
What it does not do is judge the line. `pick` never offers blocked work, and a caller
|
|
411
|
+
that named an id may be about to unblock it; the marker door this goes through has always
|
|
412
|
+
allowed that, and a policy here would be this command re-deciding what `status` decides.
|
|
413
|
+
|
|
414
|
+
It neither writes the registry nor reads it (RK159, RK160): the claim *and* the refusal
|
|
415
|
+
both belong to the marker write, which is one name for one rule — and the refusal had to
|
|
416
|
+
move there anyway, `status <id> 🛠` being the same write with nothing guarding it.
|
|
417
|
+
"""
|
|
418
|
+
with exclusive(config.root):
|
|
419
|
+
return Claim(choice=None, change=set_status(config, task_id, IN_PROGRESS))
|
|
420
|
+
|
|
421
|
+
|
|
422
|
+
def _absence(
|
|
423
|
+
scope: str,
|
|
424
|
+
*,
|
|
425
|
+
open_lines: bool,
|
|
426
|
+
held: tuple[Held, ...],
|
|
427
|
+
set_aside: int,
|
|
428
|
+
lacking: tuple[Lacking, ...] = (),
|
|
429
|
+
standing: Standing | None = None,
|
|
430
|
+
) -> str:
|
|
431
|
+
"""Why nothing was offered — five sentences, because they are five different states.
|
|
432
|
+
|
|
433
|
+
Telling them apart is the whole point of the scope (RK40): a block with nothing left is
|
|
434
|
+
finished, one whose lines are all blocked is not, one whose ready lines are all ideas is
|
|
435
|
+
waiting on a design session, and one whose ready lines are all claimed is waiting on the
|
|
436
|
+
workers holding them — which is the only one of the four that ends by itself.
|
|
437
|
+
|
|
438
|
+
The first of those four was itself two (RK429). "Nothing is open in Block C" is what a
|
|
439
|
+
finished block and a heading opened before its lines both produce, and the caller who
|
|
440
|
+
typed the wrong letter reads the same words — so where a label was named, the sentence
|
|
441
|
+
is :attr:`Standing.sentence` and states which. Unscoped there is no label to have a
|
|
442
|
+
state, and the old sentence is still the whole truth.
|
|
443
|
+
|
|
444
|
+
The fifth is the one whose remedy is a **person** and not a command (RK1297). Every
|
|
445
|
+
other sentence here ends by somebody shipping, resuming, designing or letting a claim
|
|
446
|
+
go; this one ends by whoever has the hardware asking for the same line, which is why it
|
|
447
|
+
names what is missing rather than what to run — and why it goes first, being the only
|
|
448
|
+
one that tells the caller reading it that the work is not theirs to do.
|
|
449
|
+
"""
|
|
450
|
+
if lacking and not held and not set_aside:
|
|
451
|
+
return (
|
|
452
|
+
f"every ready task{scope} needs something this caller does not have: "
|
|
453
|
+
f"{_missing(lacking)} — `--have` is how a caller that has one says so"
|
|
454
|
+
)
|
|
455
|
+
if held and not set_aside:
|
|
456
|
+
return f"every ready task{scope} is claimed by a worker who has not finished it"
|
|
457
|
+
if set_aside:
|
|
458
|
+
return (
|
|
459
|
+
f"every ready task{scope} still needs designing, so there is nothing "
|
|
460
|
+
"to implement"
|
|
461
|
+
)
|
|
462
|
+
if not open_lines:
|
|
463
|
+
return f"nothing is open{scope}" if standing is None else standing.sentence
|
|
464
|
+
return f"every open task{scope} is blocked, so there is nothing to start"
|
|
465
|
+
|
|
466
|
+
|
|
467
|
+
def _missing(lacking: Sequence[Lacking]) -> str:
|
|
468
|
+
"""Every requirement standing between this caller and the ranking, once each.
|
|
469
|
+
|
|
470
|
+
The union and not a line-by-line list: the sentence is about what the caller has to
|
|
471
|
+
acquire, and one word repeated across six lines is one thing to go and get. Which lines
|
|
472
|
+
those are is :attr:`Choice.lacking`, printed under it and named there.
|
|
473
|
+
"""
|
|
474
|
+
return ", ".join(dict.fromkeys(one for entry in lacking for one in entry.missing))
|
|
475
|
+
|
|
476
|
+
|
|
477
|
+
@dataclass(frozen=True, slots=True)
|
|
478
|
+
class _Survey:
|
|
479
|
+
"""One pass over the lines in scope: who is ready, and who is not and why not."""
|
|
480
|
+
|
|
481
|
+
ready: tuple[Entry, ...]
|
|
482
|
+
blocked: int
|
|
483
|
+
outside: int
|
|
484
|
+
stalled: tuple[Stalled, ...]
|
|
485
|
+
paused: int = 0
|
|
486
|
+
|
|
487
|
+
|
|
488
|
+
def _survey(
|
|
489
|
+
backlog: Backlog, considered: list[Entry], claimed: Mapping[str, Held]
|
|
490
|
+
) -> _Survey:
|
|
491
|
+
ready: list[Entry] = []
|
|
492
|
+
blocked = outside = paused = 0
|
|
493
|
+
stalled: list[Stalled] = []
|
|
494
|
+
for entry in considered:
|
|
495
|
+
readiness = backlog.readiness(entry.task)
|
|
496
|
+
if readiness is Readiness.READY:
|
|
497
|
+
ready.append(entry)
|
|
498
|
+
continue
|
|
499
|
+
if readiness is Readiness.OUTSIDE:
|
|
500
|
+
outside += 1
|
|
501
|
+
elif readiness is Readiness.PAUSED:
|
|
502
|
+
paused += 1
|
|
503
|
+
else:
|
|
504
|
+
blocked += 1
|
|
505
|
+
if entry.task.status == IN_PROGRESS:
|
|
506
|
+
stalled.append(
|
|
507
|
+
Stalled(
|
|
508
|
+
id=entry.task.id,
|
|
509
|
+
blockers=tuple(
|
|
510
|
+
r.dep.id for r in backlog.resolve(entry.task) if not r.satisfied
|
|
511
|
+
),
|
|
512
|
+
claimed=claimed.get(entry.task.id),
|
|
513
|
+
)
|
|
514
|
+
)
|
|
515
|
+
return _Survey(
|
|
516
|
+
ready=tuple(ready),
|
|
517
|
+
blocked=blocked,
|
|
518
|
+
outside=outside,
|
|
519
|
+
stalled=tuple(stalled),
|
|
520
|
+
paused=paused,
|
|
521
|
+
)
|
|
522
|
+
|
|
523
|
+
|
|
524
|
+
def _waiting(
|
|
525
|
+
backlog: Backlog, config: Config, ordered: list[Entry], considered: list[Entry]
|
|
526
|
+
) -> tuple[Waiting, ...]:
|
|
527
|
+
"""What the declared priority is waiting on, where nothing ready answers it (RK1304).
|
|
528
|
+
|
|
529
|
+
Empty the moment **any** token names a ready line, which is the state `_first`'s second
|
|
530
|
+
tier fires in: the queue was answered, the pick came from it, and a row about what some
|
|
531
|
+
other token is blocked on would be a cost quoted against a question nobody asked. So this
|
|
532
|
+
is the sentence for exactly one state — the one the fall-through already names in prose
|
|
533
|
+
and stopped short of making actionable.
|
|
534
|
+
|
|
535
|
+
The blockers are read through :meth:`Backlog.resolve`, which is where :class:`Stalled`
|
|
536
|
+
reads its own: an unsatisfied dep is one answer in this tool and a second walk here would
|
|
537
|
+
be a second answer about what is holding a line.
|
|
538
|
+
|
|
539
|
+
**Only the open ones**, unlike :class:`Stalled`, and the difference is what the two rows
|
|
540
|
+
claim: that one names what is holding a line and this one names what would *release* it.
|
|
541
|
+
Nothing now open satisfies an `UNRESOLVABLE` dep by construction (RK432), a `DEFERRED` one
|
|
542
|
+
needs a `resume` before any ship, and an `UNKNOWN` id is a finding rather than a target —
|
|
543
|
+
so naming any of them here would be an offer nothing answers, which is worse than the
|
|
544
|
+
count on its own (RK16). A token left with no id says exactly that.
|
|
545
|
+
"""
|
|
546
|
+
queue = declared(config)
|
|
547
|
+
if not queue:
|
|
548
|
+
return ()
|
|
549
|
+
ready = {entry.task.id for entry in ordered}
|
|
550
|
+
named: list[tuple[str, list[Entry]]] = []
|
|
551
|
+
for token in queue.tokens:
|
|
552
|
+
label = config.schema.block_of_dep(Dep(token))
|
|
553
|
+
under = [
|
|
554
|
+
entry
|
|
555
|
+
for entry in considered
|
|
556
|
+
if (entry.task.block == label if label is not None else entry.task.id == token)
|
|
557
|
+
]
|
|
558
|
+
if any(entry.task.id in ready for entry in under):
|
|
559
|
+
return ()
|
|
560
|
+
if under:
|
|
561
|
+
named.append((token, under))
|
|
562
|
+
out: list[Waiting] = []
|
|
563
|
+
for token, under in named:
|
|
564
|
+
blockers = sorted(
|
|
565
|
+
{
|
|
566
|
+
resolution.dep.id
|
|
567
|
+
for entry in under
|
|
568
|
+
for resolution in backlog.resolve(entry.task)
|
|
569
|
+
if resolution.status is DepStatus.OPEN
|
|
570
|
+
},
|
|
571
|
+
key=lambda one: id_order(one, config.schema),
|
|
572
|
+
)
|
|
573
|
+
out.append(
|
|
574
|
+
Waiting(
|
|
575
|
+
token=token,
|
|
576
|
+
lines=len(under),
|
|
577
|
+
releases=tuple(blockers[:RELEASES]),
|
|
578
|
+
of=len(blockers),
|
|
579
|
+
)
|
|
580
|
+
)
|
|
581
|
+
return tuple(out)
|
|
582
|
+
|
|
583
|
+
|
|
584
|
+
def _first(ordered: list[Entry], config: Config) -> tuple[Entry, Tier, str]:
|
|
585
|
+
"""The three tiers, in order, each returning the reason it fired."""
|
|
586
|
+
started = [e for e in ordered if e.task.status == IN_PROGRESS]
|
|
587
|
+
if started:
|
|
588
|
+
return (
|
|
589
|
+
started[0],
|
|
590
|
+
Tier.STARTED,
|
|
591
|
+
f"{started[0].task.id} is already in progress and ready to continue",
|
|
592
|
+
)
|
|
593
|
+
|
|
594
|
+
# The roadmap's section where one is declared, and `roadkeep.toml` otherwise (RK325).
|
|
595
|
+
# Named in the reason rather than merely applied: a project that wrote a section and is
|
|
596
|
+
# still being ordered by its config has a fact to learn, and the tier is where it reads.
|
|
597
|
+
queue = declared(config)
|
|
598
|
+
named = "the roadmap's queue" if queue.declared_in == "roadmap" else "declared priority"
|
|
599
|
+
for token in queue.tokens:
|
|
600
|
+
# Typed by the code that types a dep, so `Block X` cannot come to mean two things.
|
|
601
|
+
label = config.schema.block_of_dep(Dep(token))
|
|
602
|
+
if label is not None:
|
|
603
|
+
inside = [e for e in ordered if e.task.block == label]
|
|
604
|
+
if inside:
|
|
605
|
+
return (
|
|
606
|
+
inside[0],
|
|
607
|
+
Tier.PRIORITY,
|
|
608
|
+
f"{named} names Block {label}, whose lowest ready id it is",
|
|
609
|
+
)
|
|
610
|
+
continue
|
|
611
|
+
match = next((e for e in ordered if e.task.id == token), None)
|
|
612
|
+
if match is not None:
|
|
613
|
+
return match, Tier.PRIORITY, f"{named} names {token} and it is ready"
|
|
614
|
+
|
|
615
|
+
if queue:
|
|
616
|
+
return (
|
|
617
|
+
ordered[0],
|
|
618
|
+
Tier.LOWEST,
|
|
619
|
+
f"lowest ready id; {named} names nothing ready",
|
|
620
|
+
)
|
|
621
|
+
return ordered[0], Tier.LOWEST, "lowest ready id"
|
|
622
|
+
|
|
623
|
+
|
|
624
|
+
@dataclass(frozen=True, slots=True)
|
|
625
|
+
class Picked:
|
|
626
|
+
"""What `pick` answers: the choice, and the claim where the call took one (RK1170).
|
|
627
|
+
|
|
628
|
+
Three values reached the handler and were rendered there — the choice, the claim and the
|
|
629
|
+
event — so this verb's two registers were a printer in `verbs/querying.py` and a builder in
|
|
630
|
+
`rendering.py`, neither of them where the choice is made. One record carries both, and the
|
|
631
|
+
five sentences it shares with `brief` compose here because those produce rows now.
|
|
632
|
+
|
|
633
|
+
`config` is a field and not a parameter, unlike `View.stated`'s: every row this renders needs
|
|
634
|
+
it — the file a line sits on, the claim window, the offer to withdraw a heading — and this
|
|
635
|
+
record is built by the verb that already holds the project.
|
|
636
|
+
"""
|
|
637
|
+
|
|
638
|
+
config: Config
|
|
639
|
+
choice: Choice
|
|
640
|
+
claim: Claim | None
|
|
641
|
+
event: Mapping[str, object] | None
|
|
642
|
+
|
|
643
|
+
def __str__(self) -> str: # noqa: PLR0912 - the rows are a list, not a branch tree
|
|
644
|
+
"""The answer a reader scans, or the reasoned absence of one.
|
|
645
|
+
|
|
646
|
+
Nothing ready is an answer and not a failure: the exit stays 0 and the reason carries the
|
|
647
|
+
counts, so a caller can tell *backlog finished* from *everything is blocked*.
|
|
648
|
+
"""
|
|
649
|
+
from roadkeep.rendering import ( # noqa: PLC0415 - RK260, the cycle's one direction
|
|
650
|
+
_claim_rows,
|
|
651
|
+
_event_rows,
|
|
652
|
+
_held_rows,
|
|
653
|
+
_lacking_rows,
|
|
654
|
+
_stalled_rows,
|
|
655
|
+
_undesigned_rows,
|
|
656
|
+
_waiting_rows,
|
|
657
|
+
)
|
|
658
|
+
|
|
659
|
+
choice, config = self.choice, self.config
|
|
660
|
+
if choice.entry is None:
|
|
661
|
+
return "\n".join(
|
|
662
|
+
[
|
|
663
|
+
f"nothing to pick: {choice.reason}",
|
|
664
|
+
f" backlog {choice.counts}",
|
|
665
|
+
*_undesigned_rows(choice),
|
|
666
|
+
*_lacking_rows(choice),
|
|
667
|
+
*_waiting_rows(choice),
|
|
668
|
+
*_held_rows(choice),
|
|
669
|
+
*_stalled_rows(choice),
|
|
670
|
+
]
|
|
671
|
+
)
|
|
672
|
+
entry = choice.entry
|
|
673
|
+
where = f"{config.relative(config.path('roadmap'))}:{entry.lineno}"
|
|
674
|
+
rows = [
|
|
675
|
+
f"{entry.task.id} Block {entry.task.block} {entry.task.status} {where}",
|
|
676
|
+
f" because {choice.reason}",
|
|
677
|
+
f" backlog {choice.counts}",
|
|
678
|
+
f" symptom {entry.task.symptom}",
|
|
679
|
+
]
|
|
680
|
+
if choice.alternatives:
|
|
681
|
+
rows.append(f" or {', '.join(choice.alternatives)}")
|
|
682
|
+
rows += _undesigned_rows(choice)
|
|
683
|
+
rows += _lacking_rows(choice)
|
|
684
|
+
# Beside the pick and never instead of it (RK1304): the fall-through is still the right
|
|
685
|
+
# call when the blocker is expensive, and the caller is the one who knows which it is.
|
|
686
|
+
rows += _waiting_rows(choice)
|
|
687
|
+
rows += _held_rows(choice)
|
|
688
|
+
rows += _stalled_rows(choice)
|
|
689
|
+
taken = _claim_rows(self.claim, config)
|
|
690
|
+
rows += taken
|
|
691
|
+
if taken and self.event is not None:
|
|
692
|
+
# Beside the claim and not at the end, which is where `brief` puts it too: an event
|
|
693
|
+
# line after a paragraph of prose is one a hook reader has to hunt for.
|
|
694
|
+
rows += _event_rows(dict(self.event), " ")
|
|
695
|
+
return "\n".join(rows)
|
|
696
|
+
|
|
697
|
+
def payload(self) -> dict[str, object]:
|
|
698
|
+
"""The answer as one object, beside `Brief`'s and for the same reason it exists."""
|
|
699
|
+
choice, config = self.choice, self.config
|
|
700
|
+
entry = choice.entry
|
|
701
|
+
return {
|
|
702
|
+
"pick": None
|
|
703
|
+
if entry is None
|
|
704
|
+
else {
|
|
705
|
+
"id": entry.task.id,
|
|
706
|
+
"block": entry.task.block,
|
|
707
|
+
"status": entry.task.status,
|
|
708
|
+
"file": config.relative(config.path("roadmap")),
|
|
709
|
+
"line": entry.lineno,
|
|
710
|
+
"symptom": entry.task.symptom,
|
|
711
|
+
"ref": entry.task.ref,
|
|
712
|
+
},
|
|
713
|
+
"tier": None if choice.tier is None else str(choice.tier),
|
|
714
|
+
"reason": choice.reason,
|
|
715
|
+
"scope": choice.block,
|
|
716
|
+
# Beside `scope` and never instead of it (RK429): the label is what was asked and
|
|
717
|
+
# this is what became of it, so a loop scoped to a block reads one word rather than
|
|
718
|
+
# matching the sentence `reason` states it in.
|
|
719
|
+
"standing": None if choice.standing is None else choice.standing.payload(),
|
|
720
|
+
"alternatives": list(choice.alternatives),
|
|
721
|
+
"ready": choice.ready,
|
|
722
|
+
"blocked": choice.blocked,
|
|
723
|
+
"outside": choice.outside,
|
|
724
|
+
"paused": choice.paused,
|
|
725
|
+
"needs_design": choice.needs_design,
|
|
726
|
+
"undesigned": choice.undesigned,
|
|
727
|
+
# `claimed` on a stalled line and `held` beside it are two facts with two names
|
|
728
|
+
# (RK152): one is a line somebody is on that nothing could offer, the other is a
|
|
729
|
+
# candidate the ranking stepped around.
|
|
730
|
+
"stalled": [
|
|
731
|
+
{
|
|
732
|
+
"id": one.id,
|
|
733
|
+
"blockers": list(one.blockers),
|
|
734
|
+
"claimed": None
|
|
735
|
+
if one.claimed is None
|
|
736
|
+
else {"age": round(one.claimed.age), "since": one.claimed.since},
|
|
737
|
+
}
|
|
738
|
+
for one in choice.stalled
|
|
739
|
+
],
|
|
740
|
+
"held": [
|
|
741
|
+
{"id": one.id, "age": round(one.age), "since": one.since}
|
|
742
|
+
for one in choice.held
|
|
743
|
+
],
|
|
744
|
+
# The ready lines this caller cannot finish, and what each would take (RK1297).
|
|
745
|
+
# A list and not a count, for `held`'s reason and one more: a loop that hands
|
|
746
|
+
# work back to a person has to be able to say *which* work and *what for*.
|
|
747
|
+
"lacking": [
|
|
748
|
+
{"id": one.id, "missing": list(one.missing)} for one in choice.lacking
|
|
749
|
+
],
|
|
750
|
+
# What the declared priority is waiting on (RK1304), where nothing ready answers
|
|
751
|
+
# it. `[]` on every other call and never omitted: a consumer reading a missing key
|
|
752
|
+
# cannot tell "the queue was answered" from "an older server".
|
|
753
|
+
"waiting": [
|
|
754
|
+
{
|
|
755
|
+
"token": one.token,
|
|
756
|
+
"lines": one.lines,
|
|
757
|
+
"releases": list(one.releases),
|
|
758
|
+
# The roster bounded and the count whole, which is RK1301's rule: a cut
|
|
759
|
+
# list is never read as a short one.
|
|
760
|
+
"of": one.of,
|
|
761
|
+
}
|
|
762
|
+
for one in choice.waiting
|
|
763
|
+
],
|
|
764
|
+
"claimed": None
|
|
765
|
+
if self.claim is None
|
|
766
|
+
else {
|
|
767
|
+
"taken": self.claim.taken,
|
|
768
|
+
"from": None if self.claim.change is None else self.claim.change.before,
|
|
769
|
+
"to": None if self.claim.change is None else self.claim.change.after,
|
|
770
|
+
},
|
|
771
|
+
"event": None if self.event is None else dict(self.event),
|
|
772
|
+
}
|