livery.toolroom.store._spec¶
livery.toolroom.store._spec ¶
What a command-line tool accepts, as data: the spec a stub is rendered from.
An livery.toolroom.store.Option is one option of one verb as the tool describes it, a livery.toolroom.store.Verb a subcommand with its options and positional shape, and a livery.toolroom.store.ToolSpec the tool whole. The bench extracts these from the tools themselves and records them; a consumer rebuilds them from a record or from the index with livery.toolroom.store.spec_from and renders a stub with livery.toolroom.store.render. Nothing here runs a tool.
Classes:
| Name | Description |
|---|---|
Option |
One option of one tool verb, as the tool describes it. |
Verb |
A subcommand: |
ToolSpec |
Everything footman knows about one tool, from the tool itself. |
Option
dataclass
¶
Option(name: str, flags: tuple[str, ...] = (), negation: str = '', help: str = '', type_name: str = 'str', default: Any = None, choices: tuple[str, ...] = (), since: str = '', until: str = '', not_on: tuple[str, ...] = ())
One option of one tool verb, as the tool describes it.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The Python keyword a task writes: |
flags |
tuple[str, ...]
|
What the tool accepts, longest first: |
negation |
str
|
How this tool spells "off": |
help |
str
|
The tool's own one-line description, for the stub's docstring. |
type_name |
str
|
The Python type the stub declares: bool, str, int, list[str]. |
default |
Any
|
The tool's default, when it states one. |
choices |
tuple[str, ...]
|
The closed set of values the tool accepts, when it names one. The |
since |
str
|
The release this option first appears in, when the history knows. |
until |
str
|
The release this option stopped appearing in, when it has gone. A |
not_on |
tuple[str, ...]
|
The platforms observed to lack this, when any have been. Empty means |
flags
class-attribute
instance-attribute
¶
What the tool accepts, longest first: ("--use-directory-urls",).
negation
class-attribute
instance-attribute
¶
negation: str = ''
How this tool spells "off": --dirty, not always --no-<name>.
Empty when the option is not a negatable flag.
help
class-attribute
instance-attribute
¶
help: str = ''
The tool's own one-line description, for the stub's docstring.
type_name
class-attribute
instance-attribute
¶
type_name: str = 'str'
The Python type the stub declares: bool, str, int, list[str].
default
class-attribute
instance-attribute
¶
default: Any = None
The tool's default, when it states one.
choices
class-attribute
instance-attribute
¶
The closed set of values the tool accepts, when it names one. The
stub declares these as a Literal, so an IDE offers them.
since
class-attribute
instance-attribute
¶
since: str = ''
The release this option first appears in, when the history knows.
Empty when it was already there at the oldest release read: the file
must not claim a since it never looked back far enough to see. Derived
from the history at render time, never stored per release.
until
class-attribute
instance-attribute
¶
until: str = ''
The release this option stopped appearing in, when it has gone. A removed option stays in the stub, since completion should work against any version the reader might be running, and this is what says so.
not_on
class-attribute
instance-attribute
¶
The platforms observed to lack this, when any have been. Empty means
nothing contradicts it: either every platform that looked found it, or
only one ever looked. Derived from the history at render time like
since/until: the store records what each platform saw at the release
it read, and the standing claim is whatever its newest verdict says.
Verb
dataclass
¶
Verb(name: str, help: str = '', options: tuple[Option, ...] = (), not_on: tuple[str, ...] = (), wraps: bool = False, positional: str = 'any', lead: str = '')
A subcommand: mkdocs build, ruff check.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
help |
str
|
|
options |
tuple[Option, ...]
|
|
not_on |
tuple[str, ...]
|
The platforms observed to lack this whole subcommand. Said once here |
wraps |
bool
|
Whether the verb runs another command: |
positional |
str
|
What positionals the verb takes, read from its usage line. The stub |
lead |
str
|
The name of the required leading positional, when |
not_on
class-attribute
instance-attribute
¶
The platforms observed to lack this whole subcommand. Said once here rather than on each of its options, which is both smaller and what a reader wants: the command is missing, not forty flags.
wraps
class-attribute
instance-attribute
¶
wraps: bool = False
Whether the verb runs another command: uv run, docker exec,
coverage run. Its usage trails a [COMMAND] [ARG...] (or "program
options"), and everything after the verb's own arguments belongs to the
wrapped program. The bridge must place this call's flags before those
arguments, or they leak past the tool into the child.
positional
class-attribute
instance-attribute
¶
positional: str = 'any'
What positionals the verb takes, read from its usage line. The stub
renders this with / and *:
"any": zero or more (ruff check [FILES]...), or unknown. The conservative default:*args, forbids nothing."none": the tool declares only options (mkdocs build [OPTIONS]), so the stub is keyword-only and a stray positional is a type error."required": a required leading positional (docker run IMAGE …), named bylead; the stub makes it positional-only.
ToolSpec
dataclass
¶
ToolSpec(name: str, help: str = '', version: str = '', verbs: tuple[Verb, ...] = tuple(), in_process: bool = False)
Everything footman knows about one tool, from the tool itself.
Methods:
| Name | Description |
|---|---|
negations |
Map each option to its negation where it is not |
wrappers |
The dotted verb paths that wrap a command. |
color_flags |
The colour switch this tool exposes, per verb. |
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
help |
str
|
|
version |
str
|
The version this was extracted from, what an audit compares. |
verbs |
tuple[Verb, ...]
|
|
in_process |
bool
|
Whether the tool can run inside footman's process (it publishes a |
version
class-attribute
instance-attribute
¶
version: str = ''
The version this was extracted from, what an audit compares.
in_process
class-attribute
instance-attribute
¶
in_process: bool = False
Whether the tool can run inside footman's process (it publishes a
[console_scripts] entry point).
negations ¶
Map each option to its negation where it is not --no-<name>.
Only the exceptions: a table of things that already work would be noise, and would have to be regenerated far more often.
Source code in packages/toolroom-store/src/livery/toolroom/store/_spec.py
wrappers ¶
The dotted verb paths that wrap a command.
The bridge places a wrapper's flags before the child's argv instead of passing them into the child.
Source code in packages/toolroom-store/src/livery/toolroom/store/_spec.py
color_flags ¶
The colour switch this tool exposes, per verb.
The value is {verb: (flag, on, off)}.
A verb with a --color/--colour/--colors option taking a closed set
that includes always/never: the spelling footman would force to
make the tool colour past its own non-tty check (or stay quiet past an
ignored NO_COLOR). Both directions fall out of the one choices list,
so detecting the off form costs nothing. Empty when the tool has no
such switch, in which case it is assumed to obey FORCE_COLOR/NO_COLOR.
This informs the curated _COLOR table (via fm toolroom.color);
it is not applied automatically: a flag is only added for a tool proven
to ignore the environment.