Skip to content

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

TEMPLATE_VERBS module-attribute

TEMPLATE_VERBS = 'new.package'

VERB module-attribute

VERB = 'verb'

TEMPLATE module-attribute

TEMPLATE = 'template'

TEMPLATE_OPTION module-attribute

TEMPLATE_OPTION = 'template option'

KEY module-attribute

KEY = 'key'

OPTION module-attribute

OPTION = 'option'

SWITCH module-attribute

SWITCH = 'switch'

Verb dataclass

Verb(address: str, help: str = '')

One verb of a composed task tree.

Attributes:

Name Type Description
address str

How it is run: docs.build for fm docs.build.

help str

The first line of its help; empty for none.

address instance-attribute

address: str

help class-attribute instance-attribute

help: str = ''

Item dataclass

Item(kind: str, name: str, where: str = '', detail: str = '', doc: str = '')

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: verb, template, template option, key, option or switch.

name str

How a reader writes it: docs.build, python-library, python-library --command, [coverage] floor, [phases.test.pytest] parallel.

where str

The contract it is written in, root or package; empty for a verb, a template and a template's option.

detail str

An option's type or choices and its default, bool, default true; empty for every other kind.

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.

kind instance-attribute

kind: str

name instance-attribute

name: str

where class-attribute instance-attribute

where: str = ''

detail class-attribute instance-attribute

detail: str = ''

doc class-attribute instance-attribute

doc: str = ''

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 [extension] description.

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 [for.<target>] tables apply to, in composition order.

leaves_out tuple[str, ...]

The targets its root entry names in without.

extension instance-attribute

extension: str

description class-attribute instance-attribute

description: str = ''

installed class-attribute instance-attribute

installed: bool = True

items class-attribute instance-attribute

items: tuple[Item, ...] = ()

contributes class-attribute instance-attribute

contributes: tuple[str, ...] = ()

leaves_out class-attribute instance-attribute

leaves_out: tuple[str, ...] = ()

verbs_by_provider

verbs_by_provider(tree: Mapping[str, Any]) -> dict[str, list[Verb]]

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
def verbs_by_provider(tree: Mapping[str, Any]) -> dict[str, list[Verb]]:
    """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.
    """
    found: dict[str, list[Verb]] = {}
    _collect(tree, "", REPOSITORY, found)
    return found

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
def 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.
    """
    from livery.workshop._extensions import (
        SELF,
        installed_declaration,
        installed_set,
        left_out,
        resolved_targets,
    )

    names = installed_set(root)
    targets = resolved_targets(root)
    off = left_out(root)
    declared = {name: installed_declaration(name) for name in names}
    steps = {
        name: _active_steps(found, targets.get(name, ()))
        for name, found in declared.items()
        if found is not None
    }
    owners = _step_owners(steps)
    templated = {
        f"{TEMPLATE_VERBS}.{template}"
        for found in declared.values()
        if found is not None
        for template in found.templates
    }
    rest = {provider: list(found) for provider, found in verbs.items()}
    taken: dict[str, list[Verb]] = {}
    kept: list[Verb] = []
    for verb in rest.get(SELF, []):
        if verb.address in templated:
            continue
        owner = owners.get(verb.address)
        if owner is None:
            kept.append(verb)
        else:
            taken.setdefault(owner, []).append(verb)
    if SELF in rest:
        rest[SELF] = kept
    found_blocks: list[Block] = []
    for name in names:
        found = declared[name]
        contributes = tuple(
            target for target in targets.get(name, ()) if target != name
        )
        leaves = off.get(name, ())
        if found is None:
            found_blocks.append(
                Block(name, "", False, (), contributes=contributes, leaves_out=leaves)
            )
            continue
        own = [*taken.get(name, ())]
        if found.plugin:
            own += rest.pop(found.plugin, [])
        items = [
            Item(VERB, verb.address, doc=verb.help)
            for verb in sorted(own, key=lambda verb: verb.address)
        ]
        items += _items(found, steps[name])
        found_blocks.append(
            Block(
                name,
                found.description,
                True,
                tuple(items),
                contributes=contributes,
                leaves_out=leaves,
            )
        )
    return found_blocks, {provider: found for provider, found in rest.items() if found}

render_block

render_block(block: Block, audience: str | None) -> list[str]

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.

Source code in packages/workshop/src/livery/workshop/_capabilities.py
def render_block(block: Block, audience: str | None) -> list[str]:
    """*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.
    """
    prog = footman.prog()
    lines = [f"## {block.extension}", ""]
    if not block.installed:
        lines += [
            f"No installed distribution declares it yet; `{prog} sync` installs it.",
            "",
        ]
    elif block.description:
        lines += [block.description, ""]
    if audience == HUMAN:
        if block.items:
            lines += ["| item | kind | what it does |", "| --- | --- | --- |"]
            lines += [
                f"| `{_written(item, prog)}` | {_cell(_kind(item))}"
                f" | {_cell(item.doc)} |"
                for item in block.items
            ]
            lines.append("")
        if block.contributes:
            lines += [f"Contributes to {_spoken(block.contributes)}.", ""]
        if block.leaves_out:
            lines += [
                f"Its root entry leaves out {_spoken(block.leaves_out)} with"
                " `without`.",
                "",
            ]
        return lines
    listed = [f"- {_agent_line(item, prog)}" for item in block.items]
    if block.contributes:
        listed.append(f"- contributes to {', '.join(block.contributes)}")
    if block.leaves_out:
        listed.append(
            f"- leaves out {', '.join(block.leaves_out)}, named in `without` in"
            " its root entry"
        )
    return [*lines, *listed, ""] if listed else lines