Skip to content

livery.toolroom.store._stub

livery.toolroom.store._stub

Render a ToolSpec as the stub a type checker reads.

The bridge in tools.py translates keyword arguments mechanically and will happily pass a flag no stub has heard of. That is what keeps it from going stale. The stub is the other half: it tells an IDE what the installed tool currently accepts, so the flags complete and their help text is right there on hover, without importing the tool to find out.

Three things make a generated stub better than a hand-written one:

  • it says what the tool says, because it was read from the tool;
  • it can be regenerated, so a tool moving on is a diff rather than an archaeology exercise (fm toolroom.audit reports that diff);
  • it can carry the tool's own prose per flag, including the one fact a bridge can never infer: how this tool spells "off".

Every generated verb still ends in **flags: Any, so a stub that lags the installed tool degrades a hint and never a run.

Classes:

Name Description
NameCollision

A verb would generate a class named like one of the stub's imports.

Functions:

Name Description
render

The full text of stubs/<tool>.pyi for spec.

spec_from

The spec a surface describes: the shape the records and the index hold.

platforms_phrase

Linux, Windows and macOS: the platforms a stub's header names.

render_observation

The stub of name at one observed version, exactly as that version read.

NameCollision

Bases: ValueError

A verb would generate a class named like one of the stub's imports.

The generated names are title-cased verbs, so a verb literally called tool-base or flag would shadow the import inside its tool's class body and every annotation after it would silently mean the wrong thing. No real tool spells such a verb; refusing loudly keeps the checked-in stub (sync and restub skip, and say why) until the renderer is taught an escape hatch it has never yet needed.

render

render(spec: ToolSpec, *, platform: str = '', class_name: str = '', in_process: str = '') -> str

The full text of stubs/<tool>.pyi for spec.

Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
def render(
    spec: ToolSpec,
    *,
    platform: str = "",
    class_name: str = "",
    in_process: str = "",
) -> str:
    """The full text of `stubs/<tool>.pyi` for *spec*."""
    root = class_name or _class_name(spec.name)
    tree = _tree(spec.verbs)
    taken = _generated_names(tree, root)
    if clash := sorted(taken & _RESERVED_IMPORTS):
        raise NameCollision(
            f"verb class{'es' if len(clash) > 1 else ''} "
            f"{', '.join(clash)} would shadow a stub import"
        )
    hoisted = _hoisted(tree, taken)
    body = _classes(tree, root, hoisted=hoisted)
    aliases = _alias_block(hoisted)
    header = _HEADER.format(
        name=spec.name,
        version=spec.version or "an unpinned version",
        platform=platform or "this machine",
        in_process=in_process or ("available" if spec.in_process else "no"),
        imports=_imports(body, aliases),
    )
    between = f"\n\n{aliases}" if aliases else ""
    return f"{header}\n{_typevars(body)}{between}\n\n{body}"

spec_from

spec_from(surface: Mapping[str, Any], *, name: str, version: str = '', in_process: bool = False) -> ToolSpec

The spec a surface describes: the shape the records and the index hold.

surface carries help and verbs, each verb its options in the record's key shape; the inverse of what the bench writes.

Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
def spec_from(
    surface: Mapping[str, Any],
    *,
    name: str,
    version: str = "",
    in_process: bool = False,
) -> ToolSpec:
    """The spec a surface describes: the shape the records and the index hold.

    *surface* carries `help` and `verbs`, each verb its options in the
    record's key shape; the inverse of what the bench writes.
    """
    return ToolSpec(
        name=name,
        help=surface.get("help", ""),
        version=version,
        in_process=in_process,
        verbs=tuple(
            Verb(
                name=verb_name,
                help=verb.get("help", ""),
                wraps=verb.get("wraps", False),
                positional=verb.get("positional", "any"),
                lead=verb.get("lead", ""),
                options=tuple(
                    Option(
                        name=option_name,
                        flags=tuple(option.get("flags", ())),
                        negation=option.get("negation", ""),
                        help=option.get("help", ""),
                        type_name=option.get("type", "str"),
                        default=option.get("default"),
                        choices=tuple(option.get("choices", ())),
                    )
                    for option_name, option in verb.get("options", {}).items()
                ),
            )
            for verb_name, verb in surface.get("verbs", {}).items()
        ),
    )

platforms_phrase

platforms_phrase(platforms: Iterable[str]) -> str

Linux, Windows and macOS: the platforms a stub's header names.

Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
def platforms_phrase(platforms: Iterable[str]) -> str:
    """`Linux, Windows and macOS`: the platforms a stub's header names."""
    listed = list(platforms)
    if not listed:
        return "this machine"
    if len(listed) == 1:
        return listed[0]
    return f"{', '.join(listed[:-1])} and {listed[-1]}"

render_observation

render_observation(name: str, observation: Observation) -> str

The stub of name at one observed version, exactly as that version read.

The verbs and options are the version's own, no history folded in, which is what a workspace types against when it locks that version. The header names the version and the platforms that read it.

Raises:

Type Description
NameCollision

for a verb whose class would shadow a stub import.

Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
def render_observation(name: str, observation: Observation) -> str:
    """The stub of *name* at one observed version, exactly as that version read.

    The verbs and options are the version's own, no history folded in,
    which is what a workspace types against when it locks that version.
    The header names the version and the platforms that read it.

    Raises:
        NameCollision: for a verb whose class would shadow a stub import.
    """
    spec = spec_from(
        {"help": observation.help, "verbs": observation.verbs},
        name=name,
        version=observation.version,
    )
    return render(
        spec,
        platform=platforms_phrase(observation.platforms),
        class_name=class_name(name),
    )