livery.workshop._extensions¶
livery.workshop._extensions ¶
The extension walk: the lists in the contracts, every channel.
Every extension is one kind, and two lists name them: the root
workshop.toml's [workspace] extensions and each package's
workshop.toml, the extensions it is composed of. The root's list
takes any extension, and a package's list one whose declarations
show it composes something in a package. A list's set is
the list and every extension it requires. The installed set is the
root's set and every package's set: a sync installs it, and mounting
reads it, the base first, then the installed set in composition
order: each extension after the ones it requires, ties alphabetical.
No list's order decides anything: each list is written in its
canonical form, the minimal one in composition order. So a package
installed by accident never changes a repository: discovery is the
lists and nothing else.
Functions:
| Name | Description |
|---|---|
workspace_root |
The nearest ancestor carrying the workspace's contract, or None. |
installed_extensions |
The names installed distributions declare extensions under, sorted. |
shipping_distribution |
The installed distribution whose |
normal_name |
name as a distribution or an extra is compared: lower case, one hyphen per run. |
declaration |
extension's declaration file, read and judged; None when none is installed. |
ships_declaration |
Whether an installed distribution declares extension and ships its file. |
ships_elsewhere |
Whether a wheel other than distribution ships the extension target. |
distribution_of |
The distribution that ships extension: its entry point's, else by convention. |
missing_list |
Why root's contract cannot mount for want of its list; empty with one. |
listing |
An entry of an |
enabled_steps |
The steps the root contract turns on, each |
workspace_entries |
Each entry of |
workspace_names |
The extensions |
installed_declaration |
name's declaration where one is installed; None otherwise. |
composes_per_package |
Whether extension composes something in a package whose set holds it. |
installed_record |
The step name as an installed extension declares it; None when none does. |
why_inert |
What extension does instead of composing a package; empty when it composes. |
root_set |
The root's set: |
installed_set |
The extensions the workspace installs and mounts, in composition order. |
where_listed |
Each extension of the installed set to the list that brings it, as notes say it. |
extension_entries |
Every extension of the installed set as |
stack_entries |
The base, then every listed extension in mount order, as name and distribution. |
stack_names |
The base, then every listed extension: whose content a sync delivers. |
extension_package |
The dotted package extension ships from: the one its entry point names. |
extension_provider |
The member package whose sources ship extension, by its path; empty if none. |
extension_names |
The extensions the workspace installs and mounts, in mount order. |
extension_content |
The installed extension's |
base_directory |
The directory this process imported the base from. |
shipped_content |
Each extension of the workspace's stack with its |
left_out |
Each root entry's |
snapshot |
What the mount recorded, for livery.workshop._extensions.restore to put back. |
restore |
Put the mount's records back to state. |
mount_git_plugin |
Mount the git plugin; the reason it could not, printed as a note, or empty. |
mount_extensions |
Mount the plugin of every extension of the installed set, in mount order. |
stale_declarations |
The listed extensions the mount found installed from before this checkout. |
unmounted |
The listed extensions the mount found no installed distribution declaring. |
declared_now |
Of names, the extensions an installed distribution declares now. |
install_places |
Where each of names, the base or an extension, is installed, as read here. |
check_phase_declarers |
Refuse a step of extension into a phase of an extension it does not require. |
check_replacements |
Refuse a step of extension that replaces or deletes one it cannot reach. |
register_declared |
Register what additions declares for extension; whether it declares a step. |
register_jobs |
Add each of jobs to its builtin point, its entries' source extension. |
check_api_version |
Refuse an extension whose declared API version is not this workshop's. |
extension_dependencies |
Each listed extension's |
extension_tools |
Each listed extension's |
notes_tools |
Each listed extension that writes release notes, to its |
declared_targets |
Each listed extension's |
resolved_targets |
Each extension of the installed set to its active targets, in composition order. |
contributions_for |
What the installed extensions declare for target, by extension. |
contributing |
Each listed extension to the listed targets its |
dormancy |
Each listed extension that is dormant now, to what it waits for. |
describe_extensions |
The lines |
enabled_problems |
Each root |
closure_problems |
Why the contracts' lists are not valid compositions in their canonical form. |
root_list_problems |
Why |
composition_problems |
Why each package's list is not a valid composition in its canonical form. |
listing_problems |
Each |
entry_problems |
Each listed name nothing installed declares, and each package entry with options. |
requirers |
Each listed extension to the listed extensions that depend on it. |
write_extensions |
Write each package's list and the root's in its canonical form. |
list_in_root |
Add names to root's |
available_extensions |
Installed extensions the contract does not list, as (name, distribution). |
Attributes:
| Name | Type | Description |
|---|---|---|
SELF |
|
|
BASE_DISTRIBUTION |
|
|
GROUP |
|
|
MOUNTED |
bool
|
|
UNDECLARED |
tuple[str, ...]
|
|
STALE |
tuple[str, ...]
|
|
Entry |
|
workspace_root ¶
The nearest ancestor carrying the workspace's contract, or None.
The workspace contract is the marker; a checkout without one is
not a workspace and gets no extensions. A package's own
workshop.toml, under packages/<name>/ or
packages/<group>/<name>/ of a workspace whose root holds a
contract, is passed over, so a verb run inside a package resolves
the workspace it belongs to. Without start, the search starts at
the running task's directory, the process's outside a run: a task
never reads the process's own, which a parallel run shares.
Source code in packages/workshop/src/livery/workshop/_extensions.py
installed_extensions ¶
shipping_distribution ¶
shipping_distribution(package: str) -> Distribution | None
The installed distribution whose workshop.extensions entry names package.
None when no installed distribution declares an extension shipped from package.
Source code in packages/workshop/src/livery/workshop/_extensions.py
normal_name ¶
name as a distribution or an extra is compared: lower case, one hyphen per run.
The packaging standards' normal form: ., _ and - in any
run become one -.
Source code in packages/workshop/src/livery/workshop/_extensions.py
declaration ¶
declaration(extension: str) -> Declaration | None
extension's declaration file, read and judged; None when none is installed.
Read without importing anything of the extension: footman's
plugin() stays a plugin's first importer, and a step's code
is imported when the step runs.
Raises:
| Type | Description |
|---|---|
DeclarationError
|
when the package the entry point names ships no declaration file, as a release written for another workshop does, or the file says something this workshop cannot take. |
Source code in packages/workshop/src/livery/workshop/_extensions.py
ships_declaration ¶
Whether an installed distribution declares extension and ships its file.
False for an extension no installed distribution declares, and for one whose entry point names a package without a declaration file, as an install whose files moved away leaves behind.
Source code in packages/workshop/src/livery/workshop/_extensions.py
ships_elsewhere ¶
Whether a wheel other than distribution ships the extension target.
A relation to an extension of the same wheel needs no dependency and no extra: one wheel has one version, so the two cannot drift apart.
Source code in packages/workshop/src/livery/workshop/_extensions.py
distribution_of ¶
The distribution that ships extension: its entry point's, else by convention.
An extension no installed distribution declares, a newborn's list
written before its environment exists, say, is taken at the
convention: an import path names its distribution with its dots as
hyphens, and a short name is one of the base's own family,
<namespace>-extensions-<name>, never the index's package of
that bare name. An entry point whose distribution's metadata is
gone, moved by an install after the scan, has no name to give and
is taken at the convention the same way.
Source code in packages/workshop/src/livery/workshop/_extensions.py
missing_list ¶
Why root's contract cannot mount for want of its list; empty with one.
Source code in packages/workshop/src/livery/workshop/_extensions.py
listing ¶
An entry of an extensions list, as the requirement grammar reads it.
An entry is a name. A spelling the grammar does not read is taken
whole as a name: no distribution declares it, so the mount names
it, and layering.graph refuses the spelling. One it reads with
brackets, a version or a scope is read as its name, and
layering.graph refuses the spelling too
(livery.workshop._extensions.listing_problems).
Source code in packages/workshop/src/livery/workshop/_extensions.py
enabled_steps ¶
The steps the root contract turns on, each <phase>.<step>; empty without.
A step its extension declares enabled = false registers only
while the root contract sets [phases.<phase>.<step>] enabled =
true. Read raw, as the list is, since the mount reads it before
any verb judges the contract.
Source code in packages/workshop/src/livery/workshop/_extensions.py
workspace_entries ¶
Each entry of [workspace] extensions as (name, distribution), in order.
An entry is a name, or a table { name = "...", without = [...] }.
Empty outside a workspace and when the contract has no list: the
mount refuses that, and a reader has nothing to read.
Source code in packages/workshop/src/livery/workshop/_extensions.py
workspace_names ¶
The extensions [workspace] extensions lists, in its order.
installed_declaration ¶
installed_declaration(name: str) -> Declaration | None
name's declaration where one is installed; None otherwise.
The lookup livery.workshop._composition reads the installed extensions through.
Source code in packages/workshop/src/livery/workshop/_extensions.py
composes_per_package ¶
Whether extension composes something in a package whose set holds it.
The proof reads the installed declarations alone. extension
composes when it, or an extension it requires transitively,
declares at its top level or in a [for.<target>] table a step
in a phase whose level is package, an answer to a query whose
level is package, or [categories]; or when a step of any
installed extension, or a step's per-package fragment, names it in
extensions. Workspace-level steps and answers, contract keys,
tools, shipped files, CI jobs, verbs, templates and requires
itself compose nothing in a package. An extension whose code alone
reads a package's set is not seen: the declarations define what
composes, so a package's list refuses such an extension. An
installed declaration that cannot be read names nothing.
Source code in packages/workshop/src/livery/workshop/_extensions.py
installed_record ¶
installed_record(name: str) -> StepRecord | None
The step name as an installed extension declares it; None when none does.
name is <phase>.<step>. The installed extensions are read in
name order, each one's top-level tables and its [for.<target>]
tables alike, and the first that declares the step answers, its
record naming it. A declaration that cannot be read declares
nothing here: the mount and layering.graph name it.
Source code in packages/workshop/src/livery/workshop/_extensions.py
why_inert ¶
What extension does instead of composing a package; empty when it composes.
The proof is composes_per_package's. For an extension that
composes nothing, the words say what its own steps
judge: every package that holds one of the extensions they name,
the workspace as a whole when they name none, or that it declares
no step. A refusal of the extension in a package's list, or in a
template's, reads them after composes nothing in a package:.
Source code in packages/workshop/src/livery/workshop/_extensions.py
root_set ¶
The root's set: [workspace] extensions and what it requires.
In composition order, whatever the list's order and whether an
implied extension is written in it. A name no installed
distribution declares stays in the set and requires nothing. A
declared order with no start falls back to alphabetical, and
layering.graph names the cycle. Empty outside a workspace.
Source code in packages/workshop/src/livery/workshop/_extensions.py
installed_set ¶
The extensions the workspace installs and mounts, in composition order.
The root's set and every package's set, each a list and every
extension it requires, whatever that extension declares, in
composition order (livery.workshop._composition.order): each
extension after the ones it requires, ties alphabetical. Neither
list's order changes it. A name no installed distribution declares
stays in the set: the mount names it, and fm sync installs it.
A declared order with no start falls back to alphabetical here, so
a sync still runs, and layering.graph names the cycle. Empty
outside a workspace.
Source code in packages/workshop/src/livery/workshop/_extensions.py
where_listed ¶
Each extension of the installed set to the list that brings it, as notes say it.
listed in [workspace] extensions, listed in the `extensions`
of packages/<name> naming each package that lists it, or, for an
extension no list names, required by <name> naming the first
listed extension whose set holds it. Empty outside a workspace.
Source code in packages/workshop/src/livery/workshop/_extensions.py
extension_entries ¶
Every extension of the installed set as (name, distribution), in mount order.
The set livery.workshop._extensions.installed_set composes, each with the distribution that ships it (livery.workshop._extensions.distribution_of). Empty outside a workspace.
Source code in packages/workshop/src/livery/workshop/_extensions.py
stack_entries ¶
The base, then every listed extension in mount order, as name and distribution.
What a reader of the whole stack walks: the base ships the template tree the extensions overlay, and composition follows the mount's order. Empty outside a workspace.
Source code in packages/workshop/src/livery/workshop/_extensions.py
stack_names ¶
The base, then every listed extension: whose content a sync delivers.
extension_package ¶
The dotted package extension ships from: the one its entry point names.
The base is its own; an extension no installed distribution declares is taken at its name, which a member mid-birth may be.
Source code in packages/workshop/src/livery/workshop/_extensions.py
extension_provider ¶
The member package whose sources ship extension, by its path; empty if none.
extension is the name it is listed by, which is no module: the package its entry point names is looked up instead. An extension installed from an index has no member.
Source code in packages/workshop/src/livery/workshop/_extensions.py
extension_names ¶
The extensions the workspace installs and mounts, in mount order.
The root's set and every package's set, in composition order
(livery.workshop._extensions.installed_set).
workspace_names reads the workspace list alone, and
root_set the root's set.
Source code in packages/workshop/src/livery/workshop/_extensions.py
extension_content ¶
The installed extension's content/ directory, or None.
Beside the extension's declaration file, or the base's own for the base. In the monorepo the "wheel" is the editable source tree, which is what lets the materialised links point back into the repository. None for an extension that is not installed or ships no content.
Source code in packages/workshop/src/livery/workshop/_extensions.py
base_directory ¶
base_directory() -> Path
The directory this process imported the base from.
The base's own files, its content/ among them, are read from
here.
shipped_content ¶
Each extension of the workspace's stack with its content/ directory.
The base first, then the installed set in mount order, each with the directory its shipped files live in; an extension that ships no content, or that no installed distribution declares, is left out.
Source code in packages/workshop/src/livery/workshop/_extensions.py
left_out ¶
Each root entry's without: the targets its extension contributes nothing to.
Cooperation is greedy: an extension contributes to every target of
the installed set it declares a [for.<target>] table for, a
target listed later included. A table entry's without = [...]
is the workspace's opt-out, naming the targets that get nothing
from it. An entry with no without leaves out nothing, and the
fix of layering.graph writes a table entry that leaves out
nothing as the name alone.
Source code in packages/workshop/src/livery/workshop/_extensions.py
snapshot ¶
What the mount recorded, for livery.workshop._extensions.restore to put back.
Whether a mount ran, and the listed extensions it found undeclared and stale. With initial, the record a process starts with instead: no mount, and nothing found.
Source code in packages/workshop/src/livery/workshop/_extensions.py
restore ¶
Put the mount's records back to state.
mount_git_plugin ¶
mount_git_plugin() -> str
Mount the git plugin; the reason it could not, printed as a note, or empty.
The environment every git spawn runs with: one ssh connection per
host, the tools' identity, an editor that never opens. The mount
runs on every command, fm sync among them, which is what
installs the entry point a checkout that just moved past the
plugin's arrival lacks, so a refusal here would stop the command
that repairs it.
Source code in packages/workshop/src/livery/workshop/_extensions.py
mount_extensions ¶
Mount the plugin of every extension of the installed set, in mount order.
Returns the names mounted. The installed set mounts in composition
order (livery.workshop._extensions.installed_set), so an
extension finds every extension it requires already registered,
whatever either list's order. Any extension mounts from either
list. Refuses an extension declared for another workshop API
version, one whose declaration file says something this workshop
cannot take, a step into a phase of an extension it does not
require (check_phase_declarers), and a step that replaces or
deletes a step of an extension it does not require
(check_replacements).
A contract without [workspace] extensions, an extension no
installed distribution declares, and one whose installed package
ships no declaration file are named on stderr, the first of these
with the list that brings it, and skipped, never refused:
the mount runs on every command, fm sync among them, which is
what installs a missing declaration, so a refusal here would stop
the command that repairs it. An entry with brackets is named the
same way and read as its name alone. The gate's layering.graph and
fm extensions refuse the same problems. An extension
whose declaration names no plugin registers what it declares
and mounts no verbs, and one that declares nothing but answers to
queries, at its top level or in a [for.<target>] table, is
mounted all the same, since the listed extensions' answers are read
while they are listed. A plugin a branded App already mounts as a
builtin is not mounted again, since claiming its tasks again puts
the same task in one rung twice; what its declaration adds
registers as any other extension's does. A dormant extension
(livery.workshop._extensions.dormancy) registers no step and no
job, at its top level or in its [for.<target>] tables, and its
plugin mounts all the same, so its verbs stay.
Each template the base or a mounted extension's declaration declares
becomes a verb, fm new.package.<template>
(livery.workshop._templates.generate_template_verbs), read from
the declarations this walk read already: a template the installed
set's extensions declare is offered, and no other file is read.
Source code in packages/workshop/src/livery/workshop/_extensions.py
692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 | |
stale_declarations ¶
The listed extensions the mount found installed from before this checkout.
Each has an entry point whose package ships no declaration file, so
the environment's metadata is older than the source: uv sync
brings it current.
Source code in packages/workshop/src/livery/workshop/_extensions.py
unmounted ¶
The listed extensions the mount found no installed distribution declaring.
An extension the contract no longer lists is not counted.
Source code in packages/workshop/src/livery/workshop/_extensions.py
declared_now ¶
Of names, the extensions an installed distribution declares now.
Reads the installed entry points again, since the process scanned
them once at its start, and imports nothing: a distribution
installed after the interpreter started may not be importable in
it, as an editable install's path joins sys.path only when a
process starts.
Source code in packages/workshop/src/livery/workshop/_extensions.py
install_places ¶
Where each of names, the base or an extension, is installed, as read here.
Each place is three parts: the package the extension's entry point
names, the declaration file this process reads for it, and the
origin the installer recorded in the distribution's
direct_url.json, which is empty for a distribution from an
index. The file is empty when the directory this process found the
package in no longer holds one, and every part is empty for an
extension no installed distribution declares. The base, named by
SELF, has the same three parts: its package, the directory this
process imported it from (empty once that directory holds no
__init__.py), and the origin of BASE_DISTRIBUTION; every
part is empty when no distribution of that name is installed.
Read before an install and again after it, a place that differs
names an extension this process cannot read where the environment
installs it now. The directory a package was found in is kept for
the process, and an editable install's path joins sys.path only
when a process starts. The origin tells an editable install's tree
that is still on disk from the tree the environment installs.
Imports nothing.
Source code in packages/workshop/src/livery/workshop/_extensions.py
check_phase_declarers ¶
check_phase_declarers(extension: str, found: Declaration) -> None
Refuse a step of extension into a phase of an extension it does not require.
A phase is declared by the base or by an extension. A step of
extension's top-level tables goes into a phase the base,
extension itself or an extension it requires declares; a step of
a [for.<target>] table also into one target declares. Judged
from the declarations alone, every [for] table whether it
applies or not, so the verdict follows no list and no list's order.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the extension, the phase and its declarer, with the two ways to write the step. |
Source code in packages/workshop/src/livery/workshop/_extensions.py
check_replacements ¶
check_replacements(extension: str, found: Declaration) -> None
Refuse a step of extension that replaces or deletes one it cannot reach.
A step names each step it replaces or deletes as
<owner>:<phase>.<step>. In extension's top-level tables the
owner is the base or an extension extension requires, so the
owner's step registers first in every set that holds both; in a
[for.<target>] table it may also be target. Judged from the
declarations alone, whatever the lists hold or their order.
Raises:
| Type | Description |
|---|---|
Failed
|
naming the step, the one it replaces or deletes, and the two ways to write it. |
Source code in packages/workshop/src/livery/workshop/_extensions.py
register_declared ¶
register_declared(extension: str, additions: Additions, *, enabled: frozenset[str] = frozenset()) -> bool
Register what additions declares for extension; whether it declares a step.
Each step registers under the extension's listed name, since the
list is what decides which extension a step belongs to, and each
job joins its point under the same name. A step declared
enabled = false registers only when
enabled, the steps the root contract turns on
(livery.workshop._extensions.enabled_steps), names it.
Source code in packages/workshop/src/livery/workshop/_extensions.py
register_jobs ¶
register_jobs(extension: str, jobs: tuple[JobContribution, ...]) -> None
Add each of jobs to its builtin point, its entries' source extension.
Raises:
| Type | Description |
|---|---|
Failed
|
when another extension contributed a job of the same name to the same point. |
Source code in packages/workshop/src/livery/workshop/_extensions.py
check_api_version ¶
check_api_version(extension: str, found: Declaration) -> None
Refuse an extension whose declared API version is not this workshop's.
An extension declares [extension] api-version in its declaration
file; one that declares none is taken at the current version.
Source code in packages/workshop/src/livery/workshop/_extensions.py
extension_dependencies ¶
Each listed extension's [extension] requires, name to names.
The base declares none here, and an extension no installed distribution declares has none to read: the mount teaches the install.
Source code in packages/workshop/src/livery/workshop/_extensions.py
extension_tools ¶
Each listed extension's [toolroom] requires, name to requirement strings.
The tools the extension runs, such as cmake's cmake and
ninja or a verb's docker>=27, then the tools each of its
[for.<target>] tables requires while the table applies, as
livery.workshop.contributions_for decides it: a measurer's tool
is required while the workspace lists what it measures for, and
never otherwise. An extension no installed distribution declares
declares none here, and the base declares its own in its contract
file, which the tool requirements read at a site of its own.
Source code in packages/workshop/src/livery/workshop/_extensions.py
notes_tools ¶
Each listed extension that writes release notes, to its [toolroom] requires.
A release's entries must not depend on the machine that wrote them, so no host allowance reaches these tools (livery.workshop._tools.host_allowed).
Source code in packages/workshop/src/livery/workshop/_extensions.py
declared_targets ¶
Each listed extension's [for.<target>] tables, owner to target to tables.
Source code in packages/workshop/src/livery/workshop/_extensions.py
resolved_targets ¶
Each extension of the installed set to its active targets, in composition order.
Every target of the installed set the extension declares a
[for.<target>] table for, except those its root entry's
without names: cooperation is greedy, and an opt-out names what
is off (left_out).
Source code in packages/workshop/src/livery/workshop/_extensions.py
contributions_for ¶
What the installed extensions declare for target, by extension.
The extensions come in composition order. An extension contributes
its [for.<target>] table while target is listed and the
extension's listing contributes to it (every listed target it
declares a table for, except those its root entry's without
names), the rule the mount grafts by; an extension that requires
target contributes its top-level tables. The tables come as the
declaration file holds them, and an extension that declares nothing
for target is left out, as is every extension when target is
not listed. start is a directory in the workspace, the working
directory when absent.
Source code in packages/workshop/src/livery/workshop/_extensions.py
contributing ¶
Each listed extension to the listed targets its [for] tables apply to now.
A target is listed, the owner declares a [for.<target>] table for
it, and the owner's root entry does not name it in without. An
extension that contributes to nothing is left out. The rule the
mount grafts by, which livery.workshop.contributions_for, the
delivery of a table's files and dormancy read through.
Source code in packages/workshop/src/livery/workshop/_extensions.py
dormancy ¶
Each listed extension that is dormant now, to what it waits for.
An extension whose [extension] dormant-until names what another
does for it, measures for coverage, is dormant while no listed
extension contributes a [for.<it>] table to it
(livery.workshop._extensions.contributing): it registers no step
and no job, and its plugin still mounts. The text says what it waits
for and names the installed extensions whose declarations carry such
a table, which would wake it: nothing listed measures; cmake and
pytest would. A listing kept for a contributor still to come is a
statement of intent, so dormancy is named, never refused.
Source code in packages/workshop/src/livery/workshop/_extensions.py
describe_extensions ¶
The lines fm extensions prints: each extension with what it declares.
The base, then each extension of the installed set in mount order; under each, who requires it, the packages whose sets hold it, its tools, the targets it contributes to, the targets its root entry leaves out, whether it is dormant and what would wake it, and the steps it declares off, each with whether it is on.
Source code in packages/workshop/src/livery/workshop/_extensions.py
enabled_problems ¶
Each root [phases.<phase>.<step>] table turning on no step declared off.
The root contract turns on a step a listed extension declares
enabled = false; a table naming any other step, one no listed
extension declares or one that is on already, is refused naming
the steps declared off.
Source code in packages/workshop/src/livery/workshop/_extensions.py
closure_problems ¶
Why the contracts' lists are not valid compositions in their canonical form.
Empty when every target a root entry's without names is in the
installed set and its extension declares a contribution for it;
when every listed extension is installed and every entry is a name
alone (entry_problems); when every step the root contract turns
on is one a listed extension declares off (enabled_problems);
when the root's list is its canonical one (root_list_problems);
and when every package's list is a valid composition in its
canonical form, each of its entries composing something in a
package (composition_problems). The gate's --fix writes
each list in its canonical form and moves a package's entry that
composes nothing to the root's list (write_extensions).
Source code in packages/workshop/src/livery/workshop/_extensions.py
root_list_problems ¶
Why [workspace] extensions is not its canonical list; empty when it is.
The canonical list holds each extension once, in composition order.
It leaves out an entry another listed extension requires unless the
entry carries a without, and writes a table entry whose
without is empty or absent as the name alone. No other order
means anything, so the list is written in this one, which the
gate's --fix writes. A list whose set's declared order has no
start names the cycle. An entry that is not an installed
extension's name is named by entry_problems and
listing_problems, and the list is judged once they pass.
Source code in packages/workshop/src/livery/workshop/_extensions.py
composition_problems ¶
Why each package's list is not a valid composition in its canonical form.
Judged for each package whose entries are names installed
distributions declare: every extension its set requires is
installed, each lifecycle phase can run as the set's extensions
declare it (livery.workshop._phases.phase_problems), each entry
no other entry requires composes something in a package, itself or
through what it requires (why_inert), the set's declared order
has a start, and the list is the canonical one
(livery.workshop._composition.canonical). The gate's --fix
writes the canonical list and moves an entry that composes nothing
to [workspace] extensions (write_extensions). A requirement
joins the set whatever it declares, so no other list needs to name
it. A cycle of requirements shows in every package whose set holds
one of its members, since a set is closed under requires.
Source code in packages/workshop/src/livery/workshop/_extensions.py
1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 | |
listing_problems ¶
Each [workspace] extensions entry spelled as more than a name.
An entry is a name. It takes no brackets, version, ? or scope:
an extension's version comes from its wheel's metadata, and the
lock pins it. An extension no installed distribution declares is
livery.workshop._extensions.entry_problems's to name.
Source code in packages/workshop/src/livery/workshop/_extensions.py
entry_problems ¶
Each listed name nothing installed declares, and each package entry with options.
Every extension is one kind, which either list names. A package's entry is the extension's name alone, with no options.
Source code in packages/workshop/src/livery/workshop/_extensions.py
requirers ¶
Each listed extension to the listed extensions that depend on it.
Source code in packages/workshop/src/livery/workshop/_extensions.py
write_extensions ¶
Write each package's list and the root's in its canonical form.
Returns the lines written, one per list changed.
Each package's list becomes its canonical one
(livery.workshop._composition.canonical) without the entries
that compose nothing in a package (why_inert), which move to the
root's list, and the root's list then becomes its canonical one
(root_list_problems). Each entry keeps the comment lines above
it and the comment after it on its line. A moved entry takes them
to the root's list when that list does not hold it yet, and an
entry left out takes its comments with it. A list the judge refuses
for another reason, one whose order has no start, and one whose
array this does not read are left for a person, and the judge names
each; no entry moves while the root's array is not read.
Idempotent. A root without a contract lists no extensions, so
nothing is written.
Source code in packages/workshop/src/livery/workshop/_extensions.py
1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 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 | |
list_in_root ¶
Add names to root's [workspace] extensions, as its canonical list.
Each name the list does not hold yet joins it as an entry of its
own, and the list is then written in its canonical form, as the
gate's --fix writes it (write_extensions): each entry keeps
its comments, and an entry another listed extension requires
leaves the list. A list naming an extension no installed
distribution declares keeps the order it is given, and the gate
names it. Returns what write_extensions returns: a line for each
list it wrote.
Raises:
| Type | Description |
|---|---|
Failed
|
when the contract has no |
Source code in packages/workshop/src/livery/workshop/_extensions.py
available_extensions ¶
available_extensions(listed: tuple[str, ...], advertised: list[tuple[str, str]] | None = None) -> list[tuple[str, str]]
Installed extensions the contract does not list, as (name, distribution).
advertised is every workshop.extensions entry point as
(name, distribution); read from the installed metadata when None.
A footman plugin that declares no extension is not one, and is
never offered. Listing is the only activation channel, so these
do nothing until the contract names them, and the doctor says so.