livery.workshop._declaration¶
livery.workshop._declaration ¶
Read an extension's declaration file, extension.toml, without importing it.
An extension declares itself in one extension.toml, beside the
package its workshop.extensions entry point names: what it does, the
workshop API version it is written for, its plugin, the extensions it
requires, the
phases it declares and the steps it adds to a package's lifecycle
phases and to the gate's phases, the queries it declares and the ones
it answers, the tools it runs, its CI jobs, the contract keys it owns,
what it adds to another extension while that one is listed, and the
shipped files of the base and of the extensions it requires that it
replaces or deletes. The file is
a contract, read as workshop.toml is: kebab-case keys, every key
judged, every refusal naming the file. Every extension is one kind:
the root's [workspace] extensions and a package's extensions
both list any of them, so the file says nothing about where it is
listed.
A [phases.<phase>] table declares the phase when it carries
level, gated, after, verb or keys
(livery.workshop._phases.PhaseSpec), in the grammar the base's own
contract file declares its phases in; a phase no declaration names
refuses naming the declared ones. Beside those keys the table holds
the phase's steps, and nothing else.
A [queries.<name>] table declares the query when it carries
combine, level, default or values
(livery.workshop._queries.QuerySpec), in the grammar the base's own
contract file declares its queries in; a table carrying value is a
literal answer, and <name> = "module:function" under [queries]
answers by a function. An answer to a query no declaration names
refuses naming the declared ones. A [for.<target>.queries] table
answers in the same grammar, asked while the target is listed, and
declares no query. A [for.<target>.fragments] table writes its files
while the target is listed, and so are the files the extension ships
under content/for/<target>/; a directory there for a target the file
declares no [for.<target>] table for refuses, naming both. A
[for.<target>.toolroom] table's requires names the tools the
workspace requires while the table applies.
A [templates.<name>] table declares a template, which
fm new.package.<name> creates a package from: its doc, the
extensions such a package lists, extends, the template whose
files come first, its creation options under
[templates.<name>.options.<option>] (TemplateOption), and
fixes, the answers it gives options of the templates it extends
(DeclaredTemplate). The base declares its own in the same grammar,
and a [for.<target>] table declares none: a template names the
extensions it needs in its own extensions, and a workspace offers
it while its installed set holds the extension that declares it.
[extension] dormant-until names, as a verb, what another extension
does for this one by declaring a [for.<this>] table: until a listed
extension does, this one is dormant
(livery.workshop._extensions.dormancy).
An [env.<NAME>] table declares an environment variable the
extension needs (DeclaredVariable): its value, always, and
its doc. A [for.<target>] table declares none, since a variable
an extension needs does not depend on what else is listed.
A step table's deletes names the steps of other extensions that
never run for a package whose set holds this one, each
<owner>:<phase>.<step> to the reason: the base's, or those of an
extension this one requires, or, in a [for.<target>] table, the
target's, which the mount judges. A deletion naming no step an
installed extension or the base declares, one naming a step that runs
once over the workspace, and one without a reason refuse here.
A step is declared at [phases.<phase>.<step>] and reads into one
record whatever its phase's level
(livery.workshop._steps.StepRecord): a workspace-level phase's
steps register at mount, and a package-level phase's run over each
package whose set holds the extension. fm check runs the tree
side, so of a gated package-level phase, the build, a step serving
the tree side registers at mount as well, and one serving the
isolated side alone registers nothing. A step whose verdict is its
tool's exit code is its tool's words (main as a template, with
fix, safe-fix, env and matrix), which the engine runs
(livery.workshop._words.Command). Other behaviour is a reference,
"module:function", imported when it runs. The read imports
nothing. A reference whose module is not in the extension's package,
or whose module does not define the name at its top level, refuses
here, read from the module's source.
Classes:
| Name | Description |
|---|---|
DeclarationError |
An extension's declaration file says something the workshop cannot take. |
Reference |
A function a declaration names, |
CodedFix |
A step's rewrite in code with a safe mode of its own, run as the record's fix. |
Additions |
What a declaration adds while it is mounted. |
DeclaredValue |
A literal answer to a query: |
DeclaredOutput |
A file an extension's code writes: a |
DeclaredVariable |
An environment variable an extension needs: an |
Declaration |
An extension's declaration file, read and judged. |
TemplateOption |
A creation option: a |
DeclaredTemplate |
A template a declaration file declares under |
Functions:
| Name | Description |
|---|---|
directory |
Where package lives, found without importing it; None when it is absent. |
declaration_file |
package's declaration file; None when the package or its file is absent. |
read |
extension's declaration, from the file beside package; None without one. |
phase_specs_of |
The phases data's |
phase_declarations |
The phases the declaration beside package declares, for extension. |
query_specs_of |
The queries data's |
query_declarations |
The queries the declaration beside package declares, for extension. |
template_specs_of |
The templates data's |
template_declarations |
The templates the declaration beside package declares, for extension. |
installed_steps |
Every installed step, |
top_level_names |
The names path's module defines at its top level, read from its source. |
defined_tasks |
The tasks the modules under directory define, |
task_docs |
Each task the modules under directory define to its doc line, read by AST. |
contract_keys |
The contract keys the declaration beside package owns; empty without one. |
contract_keys_of |
The contract keys data's |
Attributes:
| Name | Type | Description |
|---|---|---|
FILE |
|
|
API_VERSION |
|
|
CONTRACTS |
|
|
OPTION_TYPES |
dict[str, type]
|
|
Answer |
The answer to a template's option: a string, an integer or a boolean. |
OPTION_TYPES
module-attribute
¶
Answer
module-attribute
¶
The answer to a template's option: a string, an integer or a boolean.
DeclarationError ¶
Bases: RuntimeError
An extension's declaration file says something the workshop cannot take.
The extension's own mistake, which no sync repairs: the message names the file, the key, and what it takes.
Reference
dataclass
¶
A function a declaration names, "module:function", imported when it runs.
Attributes:
| Name | Type | Description |
|---|---|---|
module |
str
|
The module that defines it, in the extension's package. |
name |
str
|
The name the module defines it under, at its top level. |
Methods:
| Name | Description |
|---|---|
resolve |
The object the reference names, its module imported now. |
__call__ |
Call the named function with args and kwargs, importing it first. |
__str__ |
The reference as the declaration spells it. |
CodedFix
dataclass
¶
A step's rewrite in code with a safe mode of its own, run as the record's fix.
Attributes:
| Name | Type | Description |
|---|---|---|
fix |
Reference
|
The function run under |
safe_fix |
Reference
|
The function run under |
Methods:
| Name | Description |
|---|---|
__call__ |
Run the mode the run asks for: the safe one under |
__str__ |
Both references, as the declaration spells them. |
__call__ ¶
__call__(ctx: PhaseContext) -> None
Run the mode the run asks for: the safe one under --safe-fix.
Additions
dataclass
¶
Additions(steps: tuple[StepRecord, ...] = (), jobs: tuple[JobContribution, ...] = ())
What a declaration adds while it is mounted.
Attributes:
| Name | Type | Description |
|---|---|---|
steps |
tuple[StepRecord, ...]
|
The steps of the |
jobs |
tuple[JobContribution, ...]
|
The CI jobs it adds to the builtin points, with their entries. |
DeclaredOutput
dataclass
¶
A file an extension's code writes: a [fragments."<target>"] table.
The file is written while the workspace's installed set holds the extension, the root's list or a package's set, and withdrawn when none does.
Attributes:
| Name | Type | Description |
|---|---|---|
target |
str
|
The file's path from the workspace root; a path ending
in |
render |
Reference
|
The function the workshop calls with the workspace root. For a file it answers the text, or nothing for no file; for a directory, each file's path under it to its text, or to the shipped file or directory the file links to. |
local |
bool
|
Whether the files belong to this checkout alone and are never committed. |
DeclaredVariable
dataclass
¶
An environment variable an extension needs: an [env.<NAME>] table.
The workshop sets it for every fm run, in a CI job's entry, in a
pass of the loop and in the scale fixture.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The variable's name. |
value |
str
|
Its value, as the file spells it. |
doc |
str
|
What the variable is for. |
always |
bool
|
Whether the value beats one the environment already carries where an environment is formed for what runs inside it: a CI job's, by its entry, a loop pass's and the scale fixture's. Everywhere else, and without it, the environment's value wins. |
extension |
str
|
The extension that declares it. |
Methods:
| Name | Description |
|---|---|
render |
The value with place where |
Declaration
dataclass
¶
Declaration(extension: str, package: str, path: Path, description: str = '', api_version: int = API_VERSION, plugin: str = '', requires: tuple[str, ...] = (), dormant_until: str = '', tools: tuple[str, ...] = (), additions: Additions = Additions(), targets: dict[str, Additions] = dict[str, Additions](), target_tables: dict[str, dict[str, Any]] = dict[str, dict[str, Any]](), tables: dict[str, Any] = dict[str, Any](), replaces: dict[str, str] = dict[str, str](), deletes: dict[str, str] = dict[str, str](), fragments: tuple[DeclaredOutput, ...] = (), target_fragments: dict[str, tuple[DeclaredOutput, ...]] = dict[str, tuple[DeclaredOutput, ...]](), target_tools: dict[str, tuple[str, ...]] = dict[str, tuple[str, ...]](), phase_specs: dict[str, PhaseSpec] = dict[str, 'PhaseSpec'](), phases: dict[str, tuple[StepRecord, ...]] = dict[str, tuple['StepRecord', ...]](), query_specs: dict[str, QuerySpec] = dict[str, 'QuerySpec'](), queries: dict[str, Reference | DeclaredValue] = dict[str, 'Reference | DeclaredValue'](), target_queries: dict[str, dict[str, Reference | DeclaredValue]] = dict[str, 'dict[str, Reference | DeclaredValue]'](), categories: tuple[tuple[str, tuple[str, ...]], ...] = (), templates: dict[str, DeclaredTemplate] = dict[str, 'DeclaredTemplate'](), env: tuple[DeclaredVariable, ...] = ())
An extension's declaration file, read and judged.
Attributes:
| Name | Type | Description |
|---|---|---|
extension |
str
|
The name the extension is listed by. |
package |
str
|
The package its entry point names, where its references live. |
path |
Path
|
The declaration file. |
description |
str
|
What the extension does, in a sentence or two, which the agent's guidance and the site's development pages open its block with; empty for none. |
api_version |
int
|
The workshop API version it is written for. |
plugin |
str
|
The footman plugin carrying its verbs; empty for none. |
requires |
tuple[str, ...]
|
The extensions it cannot work without. |
dormant_until |
str
|
What another extension does for this one by
declaring a |
tools |
tuple[str, ...]
|
The tools it runs, its verbs' and its steps', as requirement strings. |
additions |
Additions
|
What it adds whenever it is mounted. |
targets |
dict[str, Additions]
|
What it adds to each target while the target is listed. |
target_tables |
dict[str, dict[str, Any]]
|
Each |
tables |
dict[str, Any]
|
The file's top-level tables but |
replaces |
dict[str, str]
|
Each shipped file of the base or of an extension it
requires, |
deletes |
dict[str, str]
|
Each shipped file of the base or of an extension it requires that it deletes, to the reason. |
fragments |
tuple[DeclaredOutput, ...]
|
The files its code writes, by target. |
target_fragments |
dict[str, tuple[DeclaredOutput, ...]]
|
The files each |
target_tools |
dict[str, tuple[str, ...]]
|
The tools each |
phase_specs |
dict[str, PhaseSpec]
|
The phases it declares, by name. |
phases |
dict[str, tuple[StepRecord, ...]]
|
The steps its top-level |
query_specs |
dict[str, QuerySpec]
|
The queries it declares, by name. |
queries |
dict[str, Reference | DeclaredValue]
|
The queries it answers, each query's name to the function that answers it or to its literal answer. |
target_queries |
dict[str, dict[str, Reference | DeclaredValue]]
|
The queries each |
categories |
tuple[tuple[str, tuple[str, ...]], ...]
|
The categories it gives its packages' paths, each category to the patterns it takes, relative to the package. |
templates |
dict[str, DeclaredTemplate]
|
The templates it declares, by name, in the file's order. |
env |
tuple[DeclaredVariable, ...]
|
The environment variables it needs, in the file's order. |
targets
class-attribute
instance-attribute
¶
target_tables
class-attribute
instance-attribute
¶
tables
class-attribute
instance-attribute
¶
replaces
class-attribute
instance-attribute
¶
deletes
class-attribute
instance-attribute
¶
target_fragments
class-attribute
instance-attribute
¶
target_fragments: dict[str, tuple[DeclaredOutput, ...]] = field(default_factory=dict[str, tuple[DeclaredOutput, ...]])
target_tools
class-attribute
instance-attribute
¶
phase_specs
class-attribute
instance-attribute
¶
phases
class-attribute
instance-attribute
¶
phases: dict[str, tuple[StepRecord, ...]] = field(default_factory=dict[str, tuple['StepRecord', ...]])
query_specs
class-attribute
instance-attribute
¶
queries
class-attribute
instance-attribute
¶
queries: dict[str, Reference | DeclaredValue] = field(default_factory=dict[str, 'Reference | DeclaredValue'])
target_queries
class-attribute
instance-attribute
¶
target_queries: dict[str, dict[str, Reference | DeclaredValue]] = field(default_factory=dict[str, 'dict[str, Reference | DeclaredValue]'])
categories
class-attribute
instance-attribute
¶
templates
class-attribute
instance-attribute
¶
TemplateOption
dataclass
¶
A creation option: a [templates.<name>.options.<option>] table.
fm new.package.<template> <name> --<option>=<answer> answers it,
and the answer renders the template's files as the variable
variable. A template that extends this one's template takes the
option too, unless it fixes the answer under fixes.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The option's name on the command line, in kebab-case. |
doc |
str
|
One line saying what the answer decides. |
choices |
tuple[str, ...]
|
The answers it takes; empty for an option with a type. |
type |
str
|
The type of its answer, |
default |
Answer | None
|
The answer when the command line gives none; None for a required option. |
Methods:
| Name | Description |
|---|---|
refusal |
Why answer does not answer this option; empty when it does. |
variable
property
¶
variable: str
The template variable the answer renders as: the name, snake-cased.
required
property
¶
required: bool
Whether a birth needs an answer: an option without a default does.
refusal ¶
Why answer does not answer this option; empty when it does.
Source code in packages/workshop/src/livery/workshop/_declaration.py
DeclaredTemplate
dataclass
¶
DeclaredTemplate(name: str, extension: str, doc: str, extensions: tuple[str, ...], extends: str, path: Path, options: tuple[TemplateOption, ...] = (), fixes: tuple[tuple[str, Answer], ...] = ())
A template a declaration file declares under [templates.<name>].
fm new.package.<name> <package> creates a package from it: the
files of the template it extends first, then its own, which live
under content/templates/<name>/ beside the file that declares it.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The template's name, the last word of its verb. |
extension |
str
|
The extension that declares it, or the base. |
doc |
str
|
One line saying what a package born from it is. |
extensions |
tuple[str, ...]
|
The extensions a package born from it lists. |
extends |
str
|
The template whose files a birth writes first; empty for none. |
path |
Path
|
The file that declares it. |
options |
tuple[TemplateOption, ...]
|
The creation options it declares beside those of the templates it extends. |
fixes |
tuple[tuple[str, Answer], ...]
|
Each option of a template it extends to the answer it gives it, in declaration order: a birth from this template takes no answer for it. |
directory ¶
Where package lives, found without importing it; None when it is absent.
The directory that carries the declaration file when several hold the package's parts, as a namespace's portions do. Found once per import path, since a mount asks for each extension's several times; an absence is never kept, so a package installed later is found.
Source code in packages/workshop/src/livery/workshop/_declaration.py
declaration_file ¶
package's declaration file; None when the package or its file is absent.
Source code in packages/workshop/src/livery/workshop/_declaration.py
read ¶
read(extension: str, package: str) -> Declaration | None
extension's declaration, from the file beside package; None without one.
A [for.<target>] table is read while an installed distribution
ships the target's declaration, since its steps and answers name
what the target declares; until then it adds nothing. Judged once
per content and per set of targets read: the result is kept by the
file's text and those targets.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when the file does not parse, a key is unknown or of the wrong type, or a reference does not resolve. |
Source code in packages/workshop/src/livery/workshop/_declaration.py
phase_specs_of ¶
The phases data's [phases.<phase>] tables declare, judged, by name.
A table declares its phase when it carries level, gated,
after, verb or keys; one that adds steps alone declares
nothing. The same reader serves the base's contract file and an
extension's declaration file, extension naming the declarer.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when a declaration is off its shape: a level
that is not |
Source code in packages/workshop/src/livery/workshop/_declaration.py
1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 | |
phase_declarations ¶
The phases the declaration beside package declares, for extension.
Empty without a declaration file. Read without judging the rest of the file, and without importing anything, so every installed extension's phases are known before any declaration is judged.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when the file does not parse or a phase's declaration is off its shape. |
Source code in packages/workshop/src/livery/workshop/_declaration.py
query_specs_of ¶
query_specs_of(data: dict[str, Any], path: Path, *, extension: str, package: str) -> dict[str, QuerySpec]
The queries data's [queries.<name>] tables declare, judged, by name.
A table declares its query when it carries combine, level,
default or values; one carrying value answers a query
instead. The same reader serves the base's contract file and an
extension's declaration file, extension naming the declarer and
package the package a combine function lives in.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when a declaration is off its shape: a
|
Source code in packages/workshop/src/livery/workshop/_declaration.py
1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 | |
query_declarations ¶
The queries the declaration beside package declares, for extension.
Empty without a declaration file. Read without judging the rest of the file, and without importing anything, so every installed extension's queries are known before any declaration is judged.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when the file does not parse or a query's declaration is off its shape. |
Source code in packages/workshop/src/livery/workshop/_declaration.py
template_specs_of ¶
template_specs_of(data: dict[str, Any], path: Path, *, extension: str) -> dict[str, DeclaredTemplate]
The templates data's [templates.<name>] tables declare, judged, by name.
The same reader serves the base's contract file and an extension's
declaration file, extension naming the declarer. doc and
extensions are required; extends, options and fixes
are optional, and a table takes nothing else.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when a template is off its shape: a name that
is not lower-case letters, digits and hyphens, a key it does
not take, a missing |
Source code in packages/workshop/src/livery/workshop/_declaration.py
1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 | |
template_declarations ¶
template_declarations(extension: str, package: str) -> tuple[DeclaredTemplate, ...]
The templates the declaration beside package declares, for extension.
Empty without a declaration file. Read without judging the rest of the file, and without importing anything, so an installed extension's templates are known whether a workspace lists it or not.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when the file does not parse or a template is off its shape. |
Source code in packages/workshop/src/livery/workshop/_declaration.py
installed_steps ¶
Every installed step, <owner>:<phase>.<step>, to the scope it runs at.
The base's own steps, then each installed extension's
[phases.<phase>.<step>] tables, its [for.<target>] tables'
among them, read without judging the rest of the file and without
importing anything. A step of a package-level phase runs once per
package; a step of a workspace-level phase at the scope its table
names, the workspace when it names none.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when a declaration file does not parse. |
Source code in packages/workshop/src/livery/workshop/_declaration.py
top_level_names ¶
The names path's module defines at its top level, read from its source.
Its functions, classes, assignments and imports, those inside a
top-level if or try among them. Parsed once per content.
Source code in packages/workshop/src/livery/workshop/_declaration.py
defined_tasks ¶
The tasks the modules under directory define, <group>.<task>, read by AST.
The names task_docs reads, without their doc lines.
Source code in packages/workshop/src/livery/workshop/_declaration.py
task_docs ¶
Each task the modules under directory define to its doc line, read by AST.
A task is named <group>.<task>. Its doc line is the first line
of the function's docstring, which footman shows as the verb's
help; empty for a function without one. A module-level
<name> = group("<group>") defines a group, and
<name> = <parent>.group("<sub>") one beneath another. A function
decorated @<name>.task defines a task in that group, named by
the decorator's name= or else as footman names it: the
function's name, a trailing underscore dropped, underscores as
dashes. A group another module defines is followed through
from ... import. Nothing is imported.
Source code in packages/workshop/src/livery/workshop/_declaration.py
2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 | |
contract_keys ¶
The contract keys the declaration beside package owns; empty without one.
Read without judging the rest of the file, and without importing anything: the contract judge asks every installed extension.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when the file does not parse or a key's declaration is malformed. |
Source code in packages/workshop/src/livery/workshop/_declaration.py
contract_keys_of ¶
contract_keys_of(data: dict[str, Any], path: Path, *, contracts: tuple[str, ...] = CONTRACTS) -> tuple[Declared, ...]
The contract keys data's [contract] tables declare, judged.
contracts are the contracts the file may declare keys in: a
workspace's for an extension; the base's own file declares the keys
of extension.toml as well.