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/commanding.py
ADDED
|
@@ -0,0 +1,487 @@
|
|
|
1
|
+
"""The command surface as data, so nothing outside a terminal declares it twice (RK1401).
|
|
2
|
+
|
|
3
|
+
`--help` is the only reader of the parser this package builds, and it is text: a usage line
|
|
4
|
+
wrapped to a console width, arguments grouped the way `argparse` groups them, sentences
|
|
5
|
+
folded at whatever column the terminal is. Anything that wants the *facts* — a reference
|
|
6
|
+
page, a completion list, a table in an area a browser serves — either scrapes that output or
|
|
7
|
+
types the verbs again, and both go stale in the commit after the one that wrote them.
|
|
8
|
+
|
|
9
|
+
The package already holds every fact such a reader wants. Each verb declares its help
|
|
10
|
+
sentence beside the argument, `reads_only` and `writes_when` say whether running it changes
|
|
11
|
+
a file (RK117, RK167), and :data:`~roadkeep.serving.TOOLS` says which of them an agent is
|
|
12
|
+
sent and which of their arguments it may set (RK1360). `cost --tools` proves that surface can
|
|
13
|
+
be walked as data, because pricing a served description is exactly that walk. What no read
|
|
14
|
+
did was **print** it.
|
|
15
|
+
|
|
16
|
+
**Nothing here is a second statement of the surface.** The verbs come off the subparser tree,
|
|
17
|
+
the sentence off the `help=` its author already wrote, the default off the action, and the
|
|
18
|
+
exposure off the tool table `tools/list` answers from. The one thing this module decides is
|
|
19
|
+
what a *reader outside the process* needs each fact called — which is :class:`Argument`'s
|
|
20
|
+
fields and nothing else.
|
|
21
|
+
|
|
22
|
+
This is :mod:`roadkeep.describing` for the other half of the contract. That module answers
|
|
23
|
+
what `roadkeep.toml` may declare; this one answers what may be typed. Both name the build
|
|
24
|
+
that gave the answer, for the same reason: what is published is what **this** copy accepts,
|
|
25
|
+
so a flag a reader's copy does not have is an upgrade rather than a mistake.
|
|
26
|
+
|
|
27
|
+
A read about the tool and never about a governed file, so it costs a session nothing until it
|
|
28
|
+
is called (L5) and it answers on a tree with no configuration at all — which is the caller who
|
|
29
|
+
most needs it, since deciding to adopt comes before there is anything to configure.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
from __future__ import annotations
|
|
33
|
+
|
|
34
|
+
import argparse
|
|
35
|
+
from collections.abc import Mapping, Sequence
|
|
36
|
+
from dataclasses import dataclass
|
|
37
|
+
|
|
38
|
+
from roadkeep.config import Config
|
|
39
|
+
|
|
40
|
+
__all__ = ["Argument", "Command", "Listing", "commands", "payload", "stated"]
|
|
41
|
+
|
|
42
|
+
#: The one action every parser declares and no reader asked about: `--help` is argparse's,
|
|
43
|
+
#: not this tool's, and a reference page listing it once per verb would spend a row on the
|
|
44
|
+
#: fact that this is a command-line program.
|
|
45
|
+
_UNASKED = frozenset({"help"})
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _rendered(value: object) -> str:
|
|
49
|
+
"""A default as a reader outside Python needs it spelled.
|
|
50
|
+
|
|
51
|
+
:func:`roadkeep.describing._rendered`'s rule for the other half of the contract, and
|
|
52
|
+
deliberately the same one: a project reading both should not have to learn that a boolean
|
|
53
|
+
is `true` in a config listing and `True` in a command listing.
|
|
54
|
+
"""
|
|
55
|
+
if isinstance(value, bool):
|
|
56
|
+
return "true" if value else "false"
|
|
57
|
+
if isinstance(value, str):
|
|
58
|
+
return f'"{value}"'
|
|
59
|
+
if isinstance(value, tuple | list):
|
|
60
|
+
return "[" + ", ".join(_rendered(one) for one in value) + "]"
|
|
61
|
+
return str(value)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
@dataclass(frozen=True, slots=True)
|
|
65
|
+
class Argument:
|
|
66
|
+
"""One thing a verb takes, as a reader outside the process needs it.
|
|
67
|
+
|
|
68
|
+
Keyed by :attr:`dest` rather than by spelling, because that is what the rest of this
|
|
69
|
+
package is keyed by: `writes_when` names a dest, a tool exposes a dest, and a flag
|
|
70
|
+
carrying two spellings — `--status`/`--marker`, `--reason`/`--why` (RK399, RK1038) — is
|
|
71
|
+
one argument under both, which a reader keyed on the first spelling would report as two.
|
|
72
|
+
"""
|
|
73
|
+
|
|
74
|
+
#: Every spelling, in the order the parser declares them, so a caller can print the
|
|
75
|
+
#: primary and still recognise the alias somebody else's skill was written against. A
|
|
76
|
+
#: positional carries the one name `--help` calls it by.
|
|
77
|
+
spelling: tuple[str, ...]
|
|
78
|
+
dest: str
|
|
79
|
+
#: Whether it is taken by position. The difference is not decoration: `show RK1` and
|
|
80
|
+
#: `show --id RK1` is the mistake RK1254 was filed for, so which of the two a verb wants
|
|
81
|
+
#: is the fact a reference page exists to state.
|
|
82
|
+
positional: bool
|
|
83
|
+
#: What its value is called — the metavar the parser declares, or `""` where the argument
|
|
84
|
+
#: takes no value at all and is a switch.
|
|
85
|
+
takes: str
|
|
86
|
+
#: Whether it may be given more than once, however the parser says so — an append action
|
|
87
|
+
#: or an `nargs` that consumes several.
|
|
88
|
+
repeatable: bool
|
|
89
|
+
required: bool
|
|
90
|
+
#: What the verb uses when it is not given, rendered — or `None`, which says there is no
|
|
91
|
+
#: default rather than that the default is empty.
|
|
92
|
+
default: str | None
|
|
93
|
+
#: The closed set of values, where the parser declares one; empty otherwise.
|
|
94
|
+
choices: tuple[str, ...]
|
|
95
|
+
#: The sentence the parser already carries. Harvested and never restated, which is the
|
|
96
|
+
#: whole of why it is worth publishing: a second copy is the one that goes stale.
|
|
97
|
+
help: str
|
|
98
|
+
#: Whether an agent on **this** project may set it over the served surface (RK1360). Per
|
|
99
|
+
#: project and not per build, because `[files]` and `[ids]` decide it (L6). Spelled the
|
|
100
|
+
#: way :meth:`~roadkeep.serving.Tool.exposed` spells it, and deliberately not `served`:
|
|
101
|
+
#: that word is taken across this package for the prefix a session's tools arrive under
|
|
102
|
+
#: (RK1246), and one field answering for two facts is what `tests/carrying.py` exists to
|
|
103
|
+
#: refuse.
|
|
104
|
+
exposed: bool = False
|
|
105
|
+
#: Whether the served surface passes it on every call without exposing it — which is how
|
|
106
|
+
#: a flag becomes a tool (RK150), and a different fact from being withheld.
|
|
107
|
+
always: bool = False
|
|
108
|
+
|
|
109
|
+
@property
|
|
110
|
+
def primary(self) -> str:
|
|
111
|
+
"""The spelling `--help` leads with, which is what a reference page prints."""
|
|
112
|
+
return self.spelling[0] if self.spelling else self.dest
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@dataclass(frozen=True, slots=True)
|
|
116
|
+
class Command:
|
|
117
|
+
"""One verb this build declares, and what running it costs.
|
|
118
|
+
|
|
119
|
+
A **group** — `section`, `block`, `record` — is one of these too, carrying no arguments
|
|
120
|
+
and reaching nothing. Published rather than filtered out, because `section --help` is a
|
|
121
|
+
real door and a listing that skipped it would leave the nesting to be inferred from the
|
|
122
|
+
spaces in its children's paths.
|
|
123
|
+
"""
|
|
124
|
+
|
|
125
|
+
#: The subcommand path, space-separated where it is nested (`"section add"`). The argv is
|
|
126
|
+
#: this split, which is the same thing :class:`~roadkeep.serving.Tool` means by it.
|
|
127
|
+
path: str
|
|
128
|
+
help: str
|
|
129
|
+
description: str
|
|
130
|
+
arguments: tuple[Argument, ...]
|
|
131
|
+
#: Whether running it changes a governed file. The parser's own claim (RK117) and never a
|
|
132
|
+
#: table beside it: `lint` is a read and `lint --fix` is not, which a boolean alone gets
|
|
133
|
+
#: backwards and :attr:`turns_on` is the other half of.
|
|
134
|
+
writes: bool
|
|
135
|
+
#: The dests that turn a declared read into a write (RK167, RK307). Empty on a verb that
|
|
136
|
+
#: writes either way, where the question does not arise.
|
|
137
|
+
turns_on: tuple[str, ...] = ()
|
|
138
|
+
#: Whether it reaches a handler at all. False for a group, whose whole content is the
|
|
139
|
+
#: verbs under it.
|
|
140
|
+
runs: bool = True
|
|
141
|
+
#: The protocol names this command is served under, in :data:`~roadkeep.serving.TOOLS`
|
|
142
|
+
#: order. Several where `always` has put two tools on one command (RK150) — `brief` and
|
|
143
|
+
#: the `--claim` that writes — and empty where the CLI keeps a verb to itself.
|
|
144
|
+
tools: tuple[str, ...] = ()
|
|
145
|
+
#: Whether **this** project is sent it, which is a narrower question than having a tool at
|
|
146
|
+
#: all: a verb whose vocabulary the project never declared is withheld (RK1360).
|
|
147
|
+
published: bool = False
|
|
148
|
+
#: The role a withheld tool needs, so the answer names the `declare` that opens it rather
|
|
149
|
+
#: than leaving an absence for a reader to explain.
|
|
150
|
+
needs: str = ""
|
|
151
|
+
#: Which verb family declares it — `authoring`, `querying`, `sections` and three more, the
|
|
152
|
+
#: modules under `verbs/` that `cli.build_parser` calls in order (RK1402).
|
|
153
|
+
#:
|
|
154
|
+
#: **Derived from where the handler lives**, not declared a second time beside the parser.
|
|
155
|
+
#: A verb's family is already a fact about this package's layout — `agents.md` says a module
|
|
156
|
+
#: per verb family and the dispatch calls them in order — so a table here would be that
|
|
157
|
+
#: layout restated, and wrong the first time a verb moves between two of them. A group has
|
|
158
|
+
#: no handler and takes the family its children share.
|
|
159
|
+
family: str = ""
|
|
160
|
+
|
|
161
|
+
@property
|
|
162
|
+
def depth(self) -> int:
|
|
163
|
+
return self.path.count(" ")
|
|
164
|
+
|
|
165
|
+
@property
|
|
166
|
+
def leaf(self) -> str:
|
|
167
|
+
"""The last word of the path — what `--help` lists it under, one level up."""
|
|
168
|
+
return self.path.rsplit(" ", 1)[-1]
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
@dataclass(frozen=True, slots=True)
|
|
172
|
+
class Listing:
|
|
173
|
+
"""Every verb, and the build that answered — which is half of what makes it usable."""
|
|
174
|
+
|
|
175
|
+
commands: tuple[Command, ...]
|
|
176
|
+
version: str
|
|
177
|
+
#: The config this project's exposure was read against, or `None` where there is none —
|
|
178
|
+
#: in which case :attr:`Command.published` is what a default project would be sent.
|
|
179
|
+
source: str | None = None
|
|
180
|
+
|
|
181
|
+
def under(self, path: str) -> tuple[Command, ...]:
|
|
182
|
+
"""One command's own children, for a listing that groups the way `--help` does."""
|
|
183
|
+
return tuple(
|
|
184
|
+
one
|
|
185
|
+
for one in self.commands
|
|
186
|
+
if one.path.startswith(f"{path} ") and one.depth == path.count(" ") + 1
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
def top(self) -> tuple[Command, ...]:
|
|
190
|
+
return tuple(one for one in self.commands if one.depth == 0)
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def _takes(action: argparse.Action) -> str:
|
|
194
|
+
"""What one argument's value is called, or `""` where it takes none.
|
|
195
|
+
|
|
196
|
+
argparse's own two conventions, kept rather than unified: an optional's value is the
|
|
197
|
+
metavar or the dest upper-cased, a positional's is the metavar or the dest as written.
|
|
198
|
+
Printing a third spelling here would name an argument something `--help` never calls it.
|
|
199
|
+
"""
|
|
200
|
+
if action.nargs == 0:
|
|
201
|
+
return ""
|
|
202
|
+
if action.metavar:
|
|
203
|
+
return action.metavar if isinstance(action.metavar, str) else action.metavar[0]
|
|
204
|
+
return action.dest if not action.option_strings else action.dest.upper()
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def _repeatable(action: argparse.Action) -> bool:
|
|
208
|
+
"""Whether it may be given more than once, however the parser declares it."""
|
|
209
|
+
if isinstance(action, argparse._AppendAction | argparse._AppendConstAction): # noqa: SLF001
|
|
210
|
+
return True
|
|
211
|
+
return action.nargs in {"*", "+"} or isinstance(action.nargs, int) and action.nargs > 1
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def _required(action: argparse.Action) -> bool:
|
|
215
|
+
"""Whether omitting it is refused — which argparse states one way for each kind."""
|
|
216
|
+
if action.option_strings:
|
|
217
|
+
return bool(action.required)
|
|
218
|
+
return action.nargs not in {"?", "*"}
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def _arguments(
|
|
222
|
+
parser: argparse.ArgumentParser, exposed: Sequence[str], always: Sequence[str]
|
|
223
|
+
) -> tuple[Argument, ...]:
|
|
224
|
+
"""Every argument one verb declares, in its own declaration order.
|
|
225
|
+
|
|
226
|
+
A subparser action is not one of these: it is how the next verb is reached, and naming it
|
|
227
|
+
here would offer a command as a value — `_positionals`' rule in :mod:`roadkeep.cli`, for
|
|
228
|
+
its reason.
|
|
229
|
+
"""
|
|
230
|
+
out: list[Argument] = []
|
|
231
|
+
for action in parser._actions: # noqa: SLF001 - argparse exposes no public reader
|
|
232
|
+
if action.dest in _UNASKED or isinstance(action, argparse._SubParsersAction): # noqa: SLF001
|
|
233
|
+
continue
|
|
234
|
+
default = action.default
|
|
235
|
+
out.append(
|
|
236
|
+
Argument(
|
|
237
|
+
spelling=tuple(action.option_strings) or (_takes(action),),
|
|
238
|
+
dest=action.dest,
|
|
239
|
+
positional=not action.option_strings,
|
|
240
|
+
takes=_takes(action),
|
|
241
|
+
repeatable=_repeatable(action),
|
|
242
|
+
required=_required(action),
|
|
243
|
+
# `SUPPRESS` is argparse saying the attribute is not set at all, which is a
|
|
244
|
+
# different fact from a default of nothing and is published as the absence.
|
|
245
|
+
default=(
|
|
246
|
+
None
|
|
247
|
+
if default is None or default is argparse.SUPPRESS
|
|
248
|
+
else _rendered(default)
|
|
249
|
+
),
|
|
250
|
+
choices=tuple(str(one) for one in action.choices or ()),
|
|
251
|
+
help=action.help or "",
|
|
252
|
+
exposed=action.dest in exposed,
|
|
253
|
+
always=action.dest in always,
|
|
254
|
+
)
|
|
255
|
+
)
|
|
256
|
+
return tuple(out)
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def _serving(config: Config) -> Mapping[str, tuple[list[str], list[str], list[str], bool, str]]:
|
|
260
|
+
"""The served surface indexed by command path: names, exposed dests, always, published.
|
|
261
|
+
|
|
262
|
+
Read off :data:`~roadkeep.serving.TOOLS` and never listed again, which is the same trade
|
|
263
|
+
:attr:`~roadkeep.serving.Tool.writes` makes: exposure is a decision that surface already
|
|
264
|
+
states, and a second table here would answer about a surface that has moved.
|
|
265
|
+
|
|
266
|
+
A path may carry several tools, so every field accumulates: `brief` is two of them over
|
|
267
|
+
one command (RK150), and reporting the first would say the query is read-only while the
|
|
268
|
+
argument that writes is exposed.
|
|
269
|
+
"""
|
|
270
|
+
from roadkeep.serving import TOOLS # noqa: PLC0415 - RK260
|
|
271
|
+
|
|
272
|
+
out: dict[str, tuple[list[str], list[str], list[str], bool, str]] = {}
|
|
273
|
+
for tool in TOOLS:
|
|
274
|
+
names, exposed, always, published, needs = out.setdefault(
|
|
275
|
+
tool.command, ([], [], [], False, tool.needs)
|
|
276
|
+
)
|
|
277
|
+
names.append(tool.name)
|
|
278
|
+
exposed.extend(tool.exposed(config))
|
|
279
|
+
always.extend(tool.always)
|
|
280
|
+
# Published where **any** tool over this command is: the two halves of `brief` are one
|
|
281
|
+
# verb, and a path a project is sent under either name is one it has.
|
|
282
|
+
out[tool.command] = (
|
|
283
|
+
names,
|
|
284
|
+
exposed,
|
|
285
|
+
always,
|
|
286
|
+
published or tool.published(config),
|
|
287
|
+
needs,
|
|
288
|
+
)
|
|
289
|
+
return out
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def commands(config: Config, verb: str | None = None) -> Listing:
|
|
293
|
+
"""Every verb this build declares, with what this project is served (RK1401).
|
|
294
|
+
|
|
295
|
+
``verb`` narrows to one path, spelled as the answer spells it (`"section add"`). A name
|
|
296
|
+
this build does not have is refused rather than answered empty, that answer being read as
|
|
297
|
+
evidence that the verb was removed — which is the one conclusion a reader on an older copy
|
|
298
|
+
must not draw.
|
|
299
|
+
"""
|
|
300
|
+
from roadkeep import __version__ # noqa: PLC0415 - RK260
|
|
301
|
+
from roadkeep.serving import _parsers # noqa: PLC0415 - RK260
|
|
302
|
+
from roadkeep.verbs.declaring import writes_when # noqa: PLC0415 - RK1171
|
|
303
|
+
|
|
304
|
+
parsers = _parsers()
|
|
305
|
+
if verb is not None and verb not in parsers:
|
|
306
|
+
known = ", ".join(repr(one) for one in sorted(parsers) if " " not in one)
|
|
307
|
+
raise KeyError(
|
|
308
|
+
f"no command {verb!r} in roadkeep {__version__}: this build declares {known} — "
|
|
309
|
+
f"a nested one is spelled as its path, e.g. 'section add'"
|
|
310
|
+
)
|
|
311
|
+
served = _serving(config)
|
|
312
|
+
out: list[Command] = []
|
|
313
|
+
for path, parser in parsers.items():
|
|
314
|
+
if verb is not None and path != verb:
|
|
315
|
+
continue
|
|
316
|
+
names, exposed, always, published, needs = served.get(path, ([], [], [], False, ""))
|
|
317
|
+
# A group reaches no handler, so `reads_only` is absent on it — and absent is what
|
|
318
|
+
# every writing verb also looks like. The two are told apart by the handler, which is
|
|
319
|
+
# the only thing that makes a path runnable.
|
|
320
|
+
runs = parser.get_default("handler") is not None
|
|
321
|
+
out.append(
|
|
322
|
+
Command(
|
|
323
|
+
path=path,
|
|
324
|
+
help=_help_of(parsers, path),
|
|
325
|
+
description=parser.description or "",
|
|
326
|
+
arguments=_arguments(parser, exposed, always),
|
|
327
|
+
writes=runs and not parser.get_default("reads_only"),
|
|
328
|
+
turns_on=writes_when(parser),
|
|
329
|
+
runs=runs,
|
|
330
|
+
tools=tuple(names),
|
|
331
|
+
published=published,
|
|
332
|
+
needs=needs,
|
|
333
|
+
family=_family(parsers, path),
|
|
334
|
+
)
|
|
335
|
+
)
|
|
336
|
+
return Listing(
|
|
337
|
+
commands=tuple(out),
|
|
338
|
+
version=__version__,
|
|
339
|
+
source=None if config.source is None else config.relative(config.source),
|
|
340
|
+
)
|
|
341
|
+
|
|
342
|
+
|
|
343
|
+
def _family(parsers: Mapping[str, argparse.ArgumentParser], path: str) -> str:
|
|
344
|
+
"""Which module under `verbs/` declares this command (RK1402).
|
|
345
|
+
|
|
346
|
+
Read off the handler's own module rather than declared beside the parser: `agents.md`
|
|
347
|
+
already says this package is a module per verb family and `build_parser` calls them in
|
|
348
|
+
order, so a second statement here would be that layout restated — and stale the first time
|
|
349
|
+
a verb moves. What comes back is the module's last component, `querying` and not
|
|
350
|
+
`roadkeep.verbs.querying`, because the package path is not a fact a reader of the reference
|
|
351
|
+
needs.
|
|
352
|
+
|
|
353
|
+
A group's family is what its children share. `section` reaches no handler, and taking the
|
|
354
|
+
first child's answer would be a guess where two disagreed — so a split group answers with
|
|
355
|
+
nothing rather than with one of two families, which is the same rule `Key.set` follows
|
|
356
|
+
where several addresses declared a value.
|
|
357
|
+
"""
|
|
358
|
+
handler = parsers[path].get_default("handler")
|
|
359
|
+
if handler is not None:
|
|
360
|
+
return getattr(handler, "__module__", "").rpartition(".")[2]
|
|
361
|
+
under = {
|
|
362
|
+
_family(parsers, one)
|
|
363
|
+
for one in parsers
|
|
364
|
+
if one.startswith(f"{path} ") and one.count(" ") == path.count(" ") + 1
|
|
365
|
+
}
|
|
366
|
+
return under.pop() if len(under) == 1 else ""
|
|
367
|
+
|
|
368
|
+
|
|
369
|
+
def _help_of(parsers: Mapping[str, argparse.ArgumentParser], path: str) -> str:
|
|
370
|
+
"""The one-line sentence a verb is listed under, which its **parent** holds.
|
|
371
|
+
|
|
372
|
+
argparse keeps `help=` on the subparsers action that created the child and never on the
|
|
373
|
+
child itself, so a verb asked for its own help string answers with nothing. Read back off
|
|
374
|
+
the parent's choices rather than restated here, for this module's whole rule: the sentence
|
|
375
|
+
is the one its author wrote at the `add_parser` call.
|
|
376
|
+
"""
|
|
377
|
+
from roadkeep.serving import _root # noqa: PLC0415 - RK260
|
|
378
|
+
|
|
379
|
+
parent, _, leaf = path.rpartition(" ")
|
|
380
|
+
# The root is cached for the life of the process (RK202) and is the same object the index
|
|
381
|
+
# was walked from, so reaching it here is a lookup and not a second build.
|
|
382
|
+
holder = parsers.get(parent) if parent else _root()
|
|
383
|
+
if holder is None:
|
|
384
|
+
return ""
|
|
385
|
+
for action in holder._actions: # noqa: SLF001 - argparse exposes no public reader
|
|
386
|
+
if isinstance(action, argparse._SubParsersAction): # noqa: SLF001
|
|
387
|
+
for choice in action._choices_actions: # noqa: SLF001
|
|
388
|
+
if choice.dest == leaf:
|
|
389
|
+
return choice.help or ""
|
|
390
|
+
return ""
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
def stated(found: Listing) -> str:
|
|
394
|
+
"""The surface as a reader is told it: one block per verb, nested under its group."""
|
|
395
|
+
rows = [
|
|
396
|
+
f"{len(found.commands)} command(s) this build declares",
|
|
397
|
+
f" build roadkeep {found.version} — what is listed is what *this* copy takes, "
|
|
398
|
+
f"which is how a flag it predates is told from a typo",
|
|
399
|
+
]
|
|
400
|
+
for one in found.commands:
|
|
401
|
+
rows.extend(_block(one))
|
|
402
|
+
return "\n".join(rows)
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
def _block(one: Command) -> list[str]:
|
|
406
|
+
"""One verb as a reader is told it, indented by how deep its path is."""
|
|
407
|
+
pad = " " * one.depth
|
|
408
|
+
kind = "group" if not one.runs else ("writes" if one.writes else "reads")
|
|
409
|
+
rows = [f"{pad}{one.path:<22} {kind:<7} {one.help}"]
|
|
410
|
+
if one.turns_on:
|
|
411
|
+
turns = ", ".join(f"--{dest.replace('_', '-')}" for dest in one.turns_on)
|
|
412
|
+
rows.append(f"{pad} writes when {turns} is given")
|
|
413
|
+
if one.tools:
|
|
414
|
+
# Named, and said as withheld where the project has not declared the role: an absence
|
|
415
|
+
# a reader cannot explain is what sends them to the source (RK1360).
|
|
416
|
+
where = "served" if one.published else f"withheld until `declare {one.needs}`"
|
|
417
|
+
rows.append(f"{pad} {where} as {', '.join(one.tools)}")
|
|
418
|
+
for argument in one.arguments:
|
|
419
|
+
rows.append(f"{pad} {_argument_row(argument)}")
|
|
420
|
+
return rows
|
|
421
|
+
|
|
422
|
+
|
|
423
|
+
def _argument_row(one: Argument) -> str:
|
|
424
|
+
"""One argument on one line — what it is spelled, what it takes, and what it costs."""
|
|
425
|
+
spelled = ", ".join(one.spelling)
|
|
426
|
+
value = f" {one.takes}" if one.takes and not one.positional else ""
|
|
427
|
+
notes = []
|
|
428
|
+
if one.required:
|
|
429
|
+
notes.append("required")
|
|
430
|
+
if one.repeatable:
|
|
431
|
+
notes.append("repeatable")
|
|
432
|
+
if one.default is not None and not one.required:
|
|
433
|
+
notes.append(f"default {one.default}")
|
|
434
|
+
if one.choices:
|
|
435
|
+
notes.append("one of " + ", ".join(one.choices))
|
|
436
|
+
if one.always:
|
|
437
|
+
notes.append("always passed by the served tool")
|
|
438
|
+
elif one.exposed:
|
|
439
|
+
notes.append("exposed")
|
|
440
|
+
marked = f"({'; '.join(notes)})" if notes else ""
|
|
441
|
+
head = f"{spelled + value:<34}{marked}".rstrip()
|
|
442
|
+
return f"{head}\n {one.help}".rstrip() if one.help else head
|
|
443
|
+
|
|
444
|
+
|
|
445
|
+
def payload(found: Listing) -> dict[str, object]:
|
|
446
|
+
"""The same answer as data — what a reference page and a completion list read."""
|
|
447
|
+
return {
|
|
448
|
+
"version": found.version,
|
|
449
|
+
"source": found.source,
|
|
450
|
+
"commands": [
|
|
451
|
+
{
|
|
452
|
+
"command": one.path,
|
|
453
|
+
# Which module under `verbs/` declares it (RK1402) — what a reference page is
|
|
454
|
+
# one of, so the generator groups by this rather than by a list it keeps.
|
|
455
|
+
"family": one.family,
|
|
456
|
+
"help": one.help,
|
|
457
|
+
"description": one.description,
|
|
458
|
+
"writes": one.writes,
|
|
459
|
+
# The dests that make a read a write (RK167). `[]` and never omitted: a
|
|
460
|
+
# consumer reading a missing key cannot tell "never" from "this build is
|
|
461
|
+
# older than the answer".
|
|
462
|
+
"writes_when": list(one.turns_on),
|
|
463
|
+
"runs": one.runs,
|
|
464
|
+
"tools": list(one.tools),
|
|
465
|
+
"published": one.published,
|
|
466
|
+
"needs": one.needs,
|
|
467
|
+
"arguments": [
|
|
468
|
+
{
|
|
469
|
+
"dest": argument.dest,
|
|
470
|
+
"spelling": list(argument.spelling),
|
|
471
|
+
"primary": argument.primary,
|
|
472
|
+
"positional": argument.positional,
|
|
473
|
+
"takes": argument.takes,
|
|
474
|
+
"repeatable": argument.repeatable,
|
|
475
|
+
"required": argument.required,
|
|
476
|
+
"default": argument.default,
|
|
477
|
+
"choices": list(argument.choices),
|
|
478
|
+
"help": argument.help,
|
|
479
|
+
"exposed": argument.exposed,
|
|
480
|
+
"always": argument.always,
|
|
481
|
+
}
|
|
482
|
+
for argument in one.arguments
|
|
483
|
+
],
|
|
484
|
+
}
|
|
485
|
+
for one in found.commands
|
|
486
|
+
],
|
|
487
|
+
}
|