livery.workshop._variables¶
livery.workshop._variables ¶
Set the environment variables the workspace's extensions declare.
An extension declares each environment variable it needs in an
[env.<NAME>] table of its extension.toml: the value,
always when that value beats one the environment already carries,
and doc, what the variable is for. The value takes the placeholder
grammar of a step in words, {name} with lower-case words joined by
dashes, and answers one placeholder, {place}: a directory of the
variable's own. Every other brace form refuses when the declaration is
read, so a placeholder added later changes the meaning of no declared
value.
Each place that sets the variables reads the declarations of the
extensions of the workspace's installed set, and names the directory
{place} stands for:
- every
fmrun, through the cascade's hook: on a CI job, the job's own directory (job_place), where the job's environment carries none yet; on a desk, none; - the entry script,
setup.sh, for the steps beforefm: the same directory on a CI job, and none off one; fm env.emit --github, which persists the variables for a job's later steps: the runner's temporary directory;- a pass of the loop: the directory of the development environment it runs on;
- the scale fixture: the fixture's directory.
A value naming {place} is not set where nothing names a directory.
A variable the environment already carries keeps its value, as the
cascade's variables do, with one exception. Where an environment is
formed for what runs inside it, a declaration's always makes its
value beat the one the environment carries: a CI job's, in the entry
script and fm env.emit --github, where the value to beat is one the
runner sets for every job it takes; and a loop pass's or the scale
fixture's, for the processes they start. Everywhere else, every fm
run among them, the environment wins, so a job's later runs keep the
value its entry placed and a nested run keeps the one its parent set.
Functions:
| Name | Description |
|---|---|
unanswered |
Each brace form in value other than |
declared_variables |
The variables the installed declarations of extensions declare, in their order. |
workspace_variables |
The variables the extensions of root's installed set declare. |
placed |
The value each of variables takes against environ, by name. |
job_place |
The directory a CI job's variables take for |
declarers |
Who declares variables, for a message: |
Attributes:
| Name | Type | Description |
|---|---|---|
PLACE_WORD |
|
|
NAME |
|
|
JOB_DIRECTORIES |
dict[str, tuple[str, str]]
|
|
JOB_DIRECTORIES
module-attribute
¶
JOB_DIRECTORIES: dict[str, tuple[str, str]] = {'github': ('RUNNER_TEMP', ''), 'gitlab': ('CI_PROJECT_DIR', '.workshop')}
unanswered ¶
Each brace form in value other than {place}, in order, once each.
declared_variables ¶
declared_variables(extensions: Iterable[str]) -> tuple[DeclaredVariable, ...]
The variables the installed declarations of extensions declare, in their order.
An extension no installed distribution declares declares none.
Raises:
| Type | Description |
|---|---|
Failed
|
when two of the extensions declare one variable, naming both, since the two values would race for it. |
Source code in packages/workshop/src/livery/workshop/_variables.py
workspace_variables ¶
workspace_variables(root: Path) -> tuple[DeclaredVariable, ...]
The variables the extensions of root's installed set declare.
Raises:
| Type | Description |
|---|---|
Failed
|
when two of them declare one variable, naming both. |
Source code in packages/workshop/src/livery/workshop/_variables.py
placed ¶
placed(variables: Iterable[DeclaredVariable], place: str | None, environ: Mapping[str, str], *, forming: bool = False) -> dict[str, str]
The value each of variables takes against environ, by name.
A value naming {place} takes place there, and is left out
when place is None. A variable environ already carries keeps
that value. forming says the caller forms an environment for what
runs inside it, a CI job's, a loop pass's or the scale fixture's:
there an always variable takes the declared value whatever
environ carries. An empty value counts as none, as in the cascade.
Source code in packages/workshop/src/livery/workshop/_variables.py
job_place ¶
The directory a CI job's variables take for {place}; None off a CI job.
A GitHub or Gitea job, which sets GITHUB_ACTIONS, takes its
temporary directory, RUNNER_TEMP. A GitLab job, which sets
GITLAB_CI, takes .workshop under its checkout,
CI_PROJECT_DIR (JOB_DIRECTORIES). None as well when the runner
names no such directory, or one that does not exist: the entry
script refuses that job before any fm runs.
Source code in packages/workshop/src/livery/workshop/_variables.py
declarers ¶
declarers(variables: Iterable[DeclaredVariable]) -> str
Who declares variables, for a message: acme declares ACME_HOME.