livery.workshop._capabilities¶
livery.workshop._capabilities ¶
What each extension of the installed set provides, read from its declaration.
The verbs fragment, verbs.extensions.md, gives each extension of
the installed set a block of its own, in composition order: what the
extension does, its verbs with the first line of each one's help, the
templates it declares, each with its verb fm new.package.<template>
and its creation options, the contract keys
it reads and the step options a package may set, each with its doc and
where it is written, the steps it declares off with the switch that
turns each on, and the installed extensions it contributes to and
those its root entry leaves out with without. Every line is data
the extension's extension.toml and its plugin's docstrings hold
already, so a workspace that lists an extension needs no other step
for a reader to learn it.
verbs_by_provider reads the verbs from a composed task tree, blocks
reads every block of a workspace, and render_block writes one for a
reader.
Classes:
| Name | Description |
|---|---|
Verb |
One verb of a composed task tree. |
Item |
One line of a block: a verb, a template, a key, an option or a switch. |
Block |
What one extension of the installed set provides. |
Functions:
| Name | Description |
|---|---|
verbs_by_provider |
Every visible verb of tree by the plugin that mounted it. |
blocks |
Each extension of root's installed set as a block, and the verbs left over. |
render_block |
block's markdown lines for audience, ending in an empty line. |
Attributes:
| Name | Type | Description |
|---|---|---|
TEMPLATE_VERBS |
|
|
VERB |
|
|
TEMPLATE |
|
|
TEMPLATE_OPTION |
|
|
KEY |
|
|
OPTION |
|
|
SWITCH |
|
Verb
dataclass
¶
Item
dataclass
¶
One line of a block: a verb, a template, a key, an option or a switch.
Attributes:
| Name | Type | Description |
|---|---|---|
kind |
str
|
What it is: |
name |
str
|
How a reader writes it: |
where |
str
|
The contract it is written in, |
detail |
str
|
An option's type or choices and its default, |
doc |
str
|
Its doc line: a verb's first line of help, the doc of a template, a key or an option, what a switch does. |
Block
dataclass
¶
Block(extension: str, description: str = '', installed: bool = True, items: tuple[Item, ...] = (), contributes: tuple[str, ...] = (), leaves_out: tuple[str, ...] = ())
What one extension of the installed set provides.
Attributes:
| Name | Type | Description |
|---|---|---|
extension |
str
|
The name it is listed by. |
description |
str
|
What it does, from |
installed |
bool
|
Whether an installed distribution declares it; a listed extension the sync has not installed yet is named alone. |
items |
tuple[Item, ...]
|
Its verbs, templates, keys, options and switches, in that order. |
contributes |
tuple[str, ...]
|
The installed extensions its |
leaves_out |
tuple[str, ...]
|
The targets its root entry names in |
verbs_by_provider ¶
Every visible verb of tree by the plugin that mounted it.
tree is a composed task tree as --json --list reports it. A
group's default task is the group's own address, the way it is
run. A task the repository's own tasks file defines comes under the
empty provider. Hidden tasks and the tasks of hidden groups are left
out.
Source code in packages/workshop/src/livery/workshop/_capabilities.py
blocks ¶
blocks(root: Path, verbs: Mapping[str, Sequence[Verb]]) -> tuple[list[Block], dict[str, list[Verb]]]
Each extension of root's installed set as a block, and the verbs left over.
verbs are the composed tree's, by provider
(verbs_by_provider). An extension's block takes every verb its
plugin mounts, and each verb the base generates for a step the
extension declares: lint.ruff is ruff's. The verb the base
generates for a template the extension declares,
new.package.python-library, is its template's line. The verbs
no block takes come back by provider, the base's and those of the
plugins no extension of the set carries, a provider with none left
out. The blocks come in composition order.
Source code in packages/workshop/src/livery/workshop/_capabilities.py
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 | |
render_block ¶
block's markdown lines for audience, ending in an empty line.
A heading naming the extension and its description, then one line per item: a list for the agent, a table for a reader of the site. The extensions it contributes to and those its root entry leaves out close it.