livery.workshop._envfile¶
livery.workshop._envfile ¶
The one dotenv implementation: parsing, substitution, the cascade.
Every .repo.env in the wild is written against these rules:
- Precedence (highest first, kind-major): the pre-existing
process environment,
.repo.env.localfiles (nearest to farthest),.repo.shared.envin the runner's config directory, committed.repo.envfiles (nearest to farthest). - Values:
~expands at the start of a raw value; double quotes strip and allow substitution; single quotes strip and are literal; an unquoted value loses inline#comments and trailing whitespace. - Substitution:
$VARand${VAR}resolve from the stack first, then the pre-existing environment, else empty;\$stays a literal dollar; iterated until stable. - Provenance is tracked per key (which extension supplied the value); the display and the agent emission select on it.
Classes:
| Name | Description |
|---|---|
Source |
Where a stack value came from (lower is higher precedence). |
EnvStack |
The resolved env-file stack: values plus per-key provenance. |
Functions:
| Name | Description |
|---|---|
is_secret_name |
Whether key names a secret by the suffix convention. |
parse_env_file |
Parse an env file into |
load_extension |
Fold one file into stack; pre-existing environment wins. |
resolve_all |
Substitute every value until stable; honour literals and escapes. |
cascade_dirs |
Directories from the repo ceiling down to cwd, farthest first. |
load_cascade |
Load the multi-level env-file cascade, the one config mechanism. |
quote_value |
value spelled so the parser reads it back unchanged. |
set_value |
Set |
shared_file |
The shared rung's file: the CI rung when the runner set one. |
member_keys |
Every key the cascade's files define (membership, no values). |
Attributes:
| Name | Type | Description |
|---|---|---|
SECRET_SUFFIXES |
|
|
RUNG_PREFIX |
|
|
KEY_RE |
|
|
MAX_SUBSTITUTION_PASSES |
How many times one value may be re-substituted before it is given up. |
SECRET_SUFFIXES
module-attribute
¶
MAX_SUBSTITUTION_PASSES
module-attribute
¶
How many times one value may be re-substituted before it is given up.
Each pass resolves one level of reference, so a legitimate chain
settles in a handful. Two keys referring to each other (A=$B
beside B=$A) never settle: the value alternates, so it never
equals its own one-step predecessor and an unbounded loop runs
forever. That loop is inside the cascade every fm command loads,
so the bound is what keeps a mistyped pair from hanging the whole
toolchain.
Source ¶
Bases: IntEnum
Where a stack value came from (lower is higher precedence).
Attributes:
| Name | Type | Description |
|---|---|---|
environment |
The pre-existing process environment: always wins. |
|
local |
|
|
shared |
|
|
repo |
|
EnvStack
dataclass
¶
The resolved env-file stack: values plus per-key provenance.
Methods:
| Name | Description |
|---|---|
managed |
The keys the files supplied (everything not pre-existing). |
Attributes:
| Name | Type | Description |
|---|---|---|
values |
dict[str, str]
|
|
sources |
dict[str, Source]
|
|
is_secret_name ¶
parse_env_file ¶
Parse an env file into key -> raw value pairs.
Comments and blank lines are skipped, surrounding quotes
stripped, ${VAR} left raw. The membership-only readers use
this; full resolution goes through
livery.workshop._envfile.load_cascade. A missing file
answers an empty dict.
Source code in packages/workshop/src/livery/workshop/_envfile.py
load_extension ¶
Fold one file into stack; pre-existing environment wins.
Source code in packages/workshop/src/livery/workshop/_envfile.py
resolve_all ¶
Substitute every value until stable; honour literals and escapes.
A value that has not settled within
livery.workshop._envfile.MAX_SUBSTITUTION_PASSES keeps
its raw text, unexpanded: showing $B is the answer a reader
can act on, and half an expansion would look like a resolved
value.
Source code in packages/workshop/src/livery/workshop/_envfile.py
cascade_dirs ¶
Directories from the repo ceiling down to cwd, farthest first.
Farthest first, so folding with later-wins gives the nearest file precedence within its kind.
Source code in packages/workshop/src/livery/workshop/_envfile.py
load_cascade ¶
load_cascade(repo_root: Path, cwd: Path, *, shared_dir: Path | None = None, environ: dict[str, str] | None = None) -> EnvStack
Load the multi-level env-file cascade, the one config mechanism.
.repo.env (committed) and .repo.env.local (machine,
secrets, gitignored) at every level from the repo ceiling down
to cwd. Precedence is kind-major: real environment, then
.local files nearest to farthest, then the shared file, then
committed files nearest to farthest, so a machine override beats
committed config at any depth.
shared_dir is where .repo.shared.env lives; None means the
runner's own config directory, asked of footman. Under CI the
entry's emission points WORKSHOP_SHARED_ENV_FILE at a
runner-local file it wrote from the job's secrets, and that file
IS the shared slot: same precedence, same masking, gone with the
runner. environ
defaults to os.environ and is injectable for tests.
Source code in packages/workshop/src/livery/workshop/_envfile.py
quote_value ¶
value spelled so the parser reads it back unchanged.
An unquoted value loses everything from its first # onward
and all trailing whitespace, so a value carrying either is
written inside double quotes, which the parser strips again. A
line break cannot be spelled on one line at all, the value would
read back as several lines with the second silently discarded,
so it is refused rather than written.
Raises:
| Type | Description |
|---|---|
ValueError
|
value contains a line break. |
Source code in packages/workshop/src/livery/workshop/_envfile.py
set_value ¶
Set key=value in path, preserving the file's other content.
The stack's one write primitive: creates the file and parents
when missing, replaces the key's line in place when present,
appends with a blank separator otherwise. The value is spelled
by livery.workshop._envfile.quote_value, so what is read
back is what was set.
Source code in packages/workshop/src/livery/workshop/_envfile.py
shared_file ¶
The shared rung's file: the CI rung when the runner set one.
WORKSHOP_SHARED_ENV_FILE names a runner-local file the
entry's emission materialised from the repository's secrets; when
it is unset the rung is .repo.shared.env in shared_dir
(the runner's config directory when None).
Source code in packages/workshop/src/livery/workshop/_envfile.py
member_keys ¶
Every key the cascade's files define (membership, no values).
The one definition of which files make up the stack, for the
membership consumers (the agent emission, env.show): the
same files livery.workshop._envfile.load_cascade folds
for a run from cwd.