livery.workshop._shipped_files¶
livery.workshop._shipped_files ¶
Deliver the files the listed extensions ship, through the fragment engine.
An extension ships a workspace file as a template in its wheel, under
content/root/<path> for a file at the workspace root and
content/package/<path> for that file in every package listing the
extension; a .jinja suffix on the source is dropped for the
target. Under content/for/<target>/root/ and
content/for/<target>/package/ it ships the files it adds to another
extension, delivered while its [for.<target>] table applies
(livery.workshop._extensions.contributing). fm sync composes them with
livery.workshop._fragment_engine.plan and writes them with
livery.workshop._fragment_engine.apply; the gate's drift.check
judges them with livery.workshop._fragment_engine.drift.
An extension takes the place of a shipped file of the base or of an
extension it requires by declaring it in its extension.toml:
[replaces] "<owner>:<name>" = "<reason>", where its own file of the
same name is the replacement, or [deletes] with the same shape to
remove it. Each applies after what it requires, so the replacement
follows no list's order. The same declarations govern seeds
(livery.workshop._seeds.create).
An extension also writes files from its own code: each
[fragments."<target>"] table in its extension.toml names a render
the engine calls with the workspace root, for one file or, with a
target ending in /, a directory of them
(livery.workshop._shipped_files.computed_outputs), and a
[for.<target>.fragments] table does the same while it applies. An
extension's files are written while the installed set holds it, the
root's set or a package's, and withdrawn when no list holds it any
more (livery.workshop._shipped_files.delivery_order).
Functions:
| Name | Description |
|---|---|
delivery_order |
The owners whose files a sync delivers to root, in the order they apply. |
shipped |
Every listed extension's shipped files as fragments, and the order they apply. |
declared |
fragments with each listed extension's |
outputs |
The shipped files as the listed extensions render them for root. |
deliver |
Write the shipped files into root; one line per file that changed. |
deliver_project_file |
Write the workspace's project file alone, as the installed set renders it now. |
shipped_drift |
One line per shipped file whose committed bytes are not its render. |
relocate |
Move what a composed JSON file has and its render lacks into its region. |
settle_package |
Compose the per-package files of a package holding extensions, at member. |
judge_package |
The drift lines for the per-package files of a package holding extensions. |
computed_outputs |
The files the listed extensions' code writes, in order. |
Attributes:
| Name | Type | Description |
|---|---|---|
ROOT_CONTENT |
The |
|
PACKAGE_CONTENT |
The |
|
FOR_CONTENT |
The |
|
TEMPLATE |
The suffix a shipped template may carry, dropped for its target: a |
|
PROJECT_FILE |
The workspace's project file, which renders from the contract's identity. |
ROOT_CONTENT
module-attribute
¶
The content/ subdirectory whose files land at the workspace root.
PACKAGE_CONTENT
module-attribute
¶
The content/ subdirectory whose files land in each package.
FOR_CONTENT
module-attribute
¶
The content/ subdirectory holding, per target, the files an extension
adds to another: for/<target>/root/ and for/<target>/package/.
TEMPLATE
module-attribute
¶
The suffix a shipped template may carry, dropped for its target: a
template named like a tool's configuration file (pyproject.toml) would
otherwise be read as one by the tool that searches the tree for it.
PROJECT_FILE
module-attribute
¶
The workspace's project file, which renders from the contract's identity.
delivery_order ¶
The owners whose files a sync delivers to root, in the order they apply.
The stack (livery.workshop._extensions.stack_names): the base, then every extension of the installed set in composition order, which holds every extension a package's set holds.
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
shipped ¶
Every listed extension's shipped files as fragments, and the order they apply.
The order is the delivery's
(livery.workshop._shipped_files.delivery_order). A file under
content/for/<target>/ comes while the extension's [for.<target>]
table applies, named for/<target>/<path> among the extension's
fragments, after its own.
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
declared ¶
fragments with each listed extension's [replaces] and [deletes] applied.
A replacement marks the declaring extension's own fragment of the
lower one's name; a deletion adds a fragment that only deletes. The
lower fragment is the base's or that of an extension the declaring
one requires, transitively, so it applies first in order, which is
composition order. The engine's resolution then checks that the
lower fragment exists. Seed declarations (names under seeds/)
apply with seeds set, every other one without.
Raises:
| Type | Description |
|---|---|
Failed
|
for a replacement whose extension ships no file of that name, and for a replacement or a deletion of a file of an extension the declaring one does not require. |
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
outputs ¶
The shipped files as the listed extensions render them for root.
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
deliver ¶
Write the shipped files into root; one line per file that changed.
A pass that changed anything is followed by one more: a rendered
fragment may read a file the same pass wrote (the verbs fragment
reads tasks.py), and the second pass renders it from what is now
on disk, so a sync leaves a tree the next sync finds settled.
local_only writes only the local outputs git does not track
(livery.workshop._fragment_engine.apply_untracked): what a
commit holds is judged by the drift check, never rewritten.
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
deliver_project_file ¶
Write the workspace's project file alone, as the installed set renders it now.
The dev group the file renders names the distribution of each
extension of the installed set, one no installed distribution
declares yet among them, so a uv sync after this write locks
and installs that distribution through the file's
[tool.uv.sources] and indexes. No other file is written or
withdrawn: a whole delivery while a listed extension is not
installed would withdraw that extension's files. A file edited
here is kept and named, as a delivery keeps it, and a workspace
whose contract names no project renders no project file.
Returns:
| Type | Description |
|---|---|
list[str]
|
The line for the file when it changed or was kept; empty when |
list[str]
|
it already held the render or none renders. |
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
shipped_drift ¶
One line per shipped file whose committed bytes are not its render.
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
relocate ¶
Move what a composed JSON file has and its render lacks into its region.
VS Code writes a setting changed through its UI into settings.json
just before the closing brace, and a recommendation into the list,
both outside the repository's region. A top-level key the render does
not produce, or an item a list holds that the render's list does not,
is the repository's: it moves into the file's first region, and the
file is written as the render with that region. A key the render does
produce, set here to another value, is an override of an extension's
or a step's setting; it refuses, naming the key and both values,
since which one should stand is a person's call.
Returns:
| Type | Description |
|---|---|
list[str]
|
One line per key or item moved. |
Raises:
| Type | Description |
|---|---|
Failed
|
for a key the render owns that is set to another value. |
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
settle_package ¶
Compose the per-package files of a package holding extensions, at member.
What a sync does for one package, without a workspace around it: the conformance kit and a birth's probe settle a package directory this way. extensions is the set the package holds, its list completed.
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
judge_package ¶
The drift lines for the per-package files of a package holding extensions.
Source code in packages/workshop/src/livery/workshop/_shipped_files.py
computed_outputs ¶
The files the listed extensions' code writes, in order.
order is the delivery's
(livery.workshop._shipped_files.delivery_order), so an
extension's files are written while the installed set holds it and
withdrawn when no list holds it any more.
Each [fragments."<target>"] table names a render the engine
calls with root, and so does each [for.<target>.fragments]
table while its [for.<target>] table applies. For a file target
the render answers the text, or nothing for no file; for a target
ending in / it answers each file's path under the target, to its
text or to the shipped file or directory the file links to. Every
file is owned <extension>:<target>, and a local table's files
belong to this checkout alone.
Raises:
| Type | Description |
|---|---|
Failed
|
for a path two writers claim: another extension's render, or a file taken names by its owner. |