Skip to content

livery.toolroom.bench._toolspec

livery.toolroom.bench._toolspec

What a command-line tool says about itself — extracted, not transcribed.

The tools.* bridge translates keyword arguments mechanically, which is what keeps it from going stale the way hand-written wrappers do. But two things about a tool cannot be derived from the call: what its options mean, and how it spells a negation.

The second one is a bug, not a nicety. off emits --no-<name>, which is right for most tools and wrong for enough to matter: mkdocs build --no-clean is rejected outright — the flag is --dirty — and five of mkdocs' eight negatable options disagree with the convention. Only the tool knows, so footman asks it.

Extraction, richest first:

  • click — Command.params carries opts, secondary_opts (the true negation), the default, the help text, and the type, as data. No parsing, no guessing.
  • argparse / optparse — walk the parser's actions (to come).
  • --help text — for the Rust and Go tools, whose output is regular and which often spell the negation in prose (clap: "Use --no-unsafe-fixes to disable"). To come.

Nothing here runs on the completion hot path, and nothing here is imported by tools.py at call time: the extracted facts are recorded, and the extractor only runs when a reading is taken. The data classes it fills, livery.toolroom.store.ToolSpec and its parts, live in the store, which renders them; this module is the reading side.

Functions:

Name Description
from_click

A ToolSpec from a click Group or Command.

from_click

from_click(command: Any, *, name: str = '', version: str = '') -> ToolSpec

A ToolSpec from a click Group or Command.

click models a negatable flag as one parameter with opts and secondary_opts — --clean / --dirty — which is exactly the fact off needs and cannot infer.

Source code in packages/toolroom-bench/src/livery/toolroom/bench/_toolspec.py
def from_click(command: Any, *, name: str = "", version: str = "") -> ToolSpec:
    """A `ToolSpec` from a click `Group` or `Command`.

    click models a negatable flag as one parameter with `opts` and
    `secondary_opts` — `--clean` / `--dirty` — which is exactly the fact
    `off` needs and cannot infer.
    """
    from livery.toolroom.store import ToolSpec

    tool = name or getattr(command, "name", "") or ""
    commands = getattr(command, "commands", None)
    if commands:
        verbs = tuple(
            _verb_from_click(verb_name, sub)
            for verb_name, sub in sorted(commands.items())
        )
    else:  # a single-command tool: its options hang off the root
        verbs = (_verb_from_click("", command),)
    return ToolSpec(
        name=tool,
        help=_first_line(getattr(command, "help", "") or ""),
        version=version,
        verbs=verbs,
        in_process=True,  # a click tool always has a console_scripts entry
    )