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.auditreports 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 |
spec_from |
The spec a surface describes: the shape the records and the index hold. |
platforms_phrase |
|
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 ¶
The full text of stubs/<tool>.pyi for spec.
Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
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
platforms_phrase ¶
Linux, Windows and macOS: the platforms a stub's header names.
Source code in packages/toolroom-store/src/livery/toolroom/store/_stub.py
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. |