livery.workshop._packages¶
livery.workshop._packages ¶
The package contracts: discovery, the graph, and the layering lint.
A directory under packages/ is a package exactly when it carries a
workshop.toml; everything the workshop knows about a package it
learns there. livery.workshop.verify_workspace is the layering lint:
contracts present, declared edges agreeing with the native manifests
in both directions, the graph acyclic, the base importing no
extension, and each reference to a sibling declared as an edge.
holds_runtime_language says whether a package holds the language the
workshop runs on, RUNTIME_LANGUAGE; a member that does is a
distribution of that language, and discovery requires its
pyproject.toml.
Classes:
| Name | Description |
|---|---|
Edge |
One declared dependency edge of a package. |
Package |
One package, as its contract declares it. |
Leftover |
A directory under |
RuleContext |
What a rule of the layering phase judges: the workspace and its sources. |
ReferencedName |
One name a source references, and how the source makes the reference. |
SourceReferences |
What one source references: one record of a package's |
Neighbours |
Who owns each name the workspace's members reference each other by. |
Functions:
| Name | Description |
|---|---|
leftover |
How git sees directory, a directory under |
is_group |
Whether directory under |
package_directories |
List every directory under |
release_tag |
The package path and version a release tag names; None for another tag. |
receipt_member |
The member a release receipt tag names, or |
member_depth |
How many leading parts of relative name a package's directory. |
member_of |
The member of members whose directory holds relative, or |
workspace_suite |
The workspace's own tests, the |
is_workspace_unit |
Whether package is the workspace's own unit rather than a member. |
holds_runtime_language |
Say whether package holds the extension of the workshop's own language. |
package_paths |
The src and tests directories the packages own, as they exist. |
discover_packages |
Every package the workspace carries, by its contract, sorted by path. |
verify_workspace |
The layering lint: check every workspace invariant, or raise. |
verify_graph |
The graph half of the layering lint: the contracts and the native manifests. |
import_problems |
Every base rule's findings over the sources in scope, each by its step's name. |
rule_problems |
What the base's layering step step finds over the sources in scope. |
graph_problems |
Every violation of the graph's invariants, verbatim; empty when they hold. |
neighbours |
Map each module root packages ship to the member that ships it. |
inherited_floor |
The floor dep already carries within reach; the highest declared. |
undeclared_references |
Sibling references no edge declares, split by what the graph reaches. |
declare_edge |
Declare package's kind edge on dependency at floor; the files written. |
write_edges |
Declare every sibling reference the graph already reaches; the lines written. |
write_test_requirements |
Write each test requirement a package's manifests lack; the lines written. |
extension_imports_in_the_base |
Each base module that imports an extension, with the extension named. |
Attributes:
| Name | Type | Description |
|---|---|---|
PACKAGES_DIR |
|
|
RESIDUE |
|
|
TRACKED |
|
|
UNTRACKED |
|
|
SECRET |
|
|
UNKNOWN |
|
|
WORKSPACE_TESTS |
|
|
RUNTIME_LANGUAGE |
|
|
Judge |
|
|
BASE_MODULE |
|
|
EXTENSIONS_NAMESPACE |
|
|
RULES |
dict[str, Judge]
|
|
RULES
module-attribute
¶
RULES: dict[str, Judge] = {'base-imports-no-extension': _base_imports_no_extension, 'sibling-references': _sibling_references}
Edge
dataclass
¶
One declared dependency edge of a package.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
str
|
The dependency's identity: its directory path from the workspace root, as the tags spell it. |
kind |
str
|
|
floor |
str
|
The released version the native manifest must require. |
Package
dataclass
¶
Package(directory: Path, path: str, name: str, depends: tuple[Edge, ...], publish: bool = True, categories: tuple[tuple[str, tuple[str, ...]], ...] = (), step_options: tuple[tuple[str, tuple[tuple[str, object], ...]], ...] = (), extensions: tuple[str, ...] = ())
One package, as its contract declares it.
Attributes:
| Name | Type | Description |
|---|---|---|
directory |
Path
|
The package directory. |
path |
str
|
The identity path from the workspace root
( |
name |
str
|
The distribution name ( |
depends |
tuple[Edge, ...]
|
The declared edges, in contract order. |
step_options |
tuple[tuple[str, tuple[tuple[str, object], ...]], ...]
|
The options the package sets on its steps, by
the table that sets them: |
categories |
tuple[tuple[str, tuple[str, ...]], ...]
|
The package's own reassignments of its paths
among the categories, |
publish |
bool
|
Whether the release train uploads the package's
artifact to its registry. |
extensions |
tuple[str, ...]
|
The extensions the package lists, in its contract's order: its canonical list, which the extensions it requires complete into its set. |
categories
class-attribute
instance-attribute
¶
step_options
class-attribute
instance-attribute
¶
step_options: tuple[tuple[str, tuple[tuple[str, object], ...]], ...] = field(default=(), hash=False)
member
property
¶
member: str
The package's path under packages/: forge, extensions/widgets.
It names the package in a release tag
(packages/<member>/v<version>) and everywhere else a
package is addressed by its place rather than its
distribution name.
root
property
¶
root: Path
The root of the workspace the package is a member of.
The package's directory with its path's parts taken off, read
from the two fields alone, without touching the disk: the root
is two directories above packages/forge, three above
packages/extensions/widgets, and one above the workspace's
own tests (livery.workshop.workspace_suite). A package whose
path is . is at the root, so its directory is the root.
Raises:
| Type | Description |
|---|---|
ValueError
|
when the directory does not end with the path, naming both. |
Leftover
dataclass
¶
A directory under packages/ with no workshop.toml, as git sees it.
Git removes a package's tracked files when a checkout moves past the package's removal and keeps the files it ignores (bytecode, built wheels, coverage pages), so the directory stays behind without its contract.
Attributes:
| Name | Type | Description |
|---|---|---|
directory |
Path
|
The directory. |
state |
str
|
|
paths |
tuple[str, ...]
|
The files that decide the state, relative to the root: the ignored files of residue, else the tracked, untracked or secret ones. |
reason |
str
|
git's own words, when it could not answer. |
RuleContext
dataclass
¶
What a rule of the layering phase judges: the workspace and its sources.
Attributes:
| Name | Type | Description |
|---|---|---|
root |
Path
|
The workspace root. |
packages |
tuple[Package, ...]
|
Every package the workspace carries. |
files |
frozenset[str] | None
|
The root-relative sources the run judges; None for every
one. A rule over the sources keeps to these, and a rule over
a package's references judges each package holding one
( |
Methods:
| Name | Description |
|---|---|
packages_in_scope |
The packages holding a source this run judges, every one without a scope. |
sources |
What each source this run judges references, one record per source. |
packages_in_scope ¶
The packages holding a source this run judges, every one without a scope.
Source code in packages/workshop/src/livery/workshop/_packages.py
sources ¶
sources() -> tuple[SourceReferences, ...]
What each source this run judges references, one record per source.
Read from the references answer of each package in scope,
in package order.
Source code in packages/workshop/src/livery/workshop/_packages.py
ReferencedName
dataclass
¶
One name a source references, and how the source makes the reference.
A record of livery.workshop.SourceReferences: an extension that
answers the references query makes one for each name a source
references, once for each way the source makes the reference.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
The dotted name, as the source spells it. |
lazy |
bool
|
Whether only a function or a method body makes the reference, so importing the source does not. |
type_checking |
bool
|
Whether only a type checker makes it, so no run of the source does. |
optional |
bool
|
Whether the source handles the name being absent, so it runs without it. |
SourceReferences
dataclass
¶
SourceReferences(path: str, module: str = '', references: tuple[ReferencedName, ...] = (), accounted: tuple[str, ...] = ())
What one source references: one record of a package's references answer.
An extension that reads a language's sources answers the
references query with one record for each source file of the
package, and the layering steps resolve each name to the member
that owns it with livery.workshop.neighbours.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
str
|
The source, relative to the workspace root, posix: a file inside the package the answer is about. |
module |
str
|
The name other code references the source by; empty for a source nothing references by name, such as a test. |
references |
tuple[ReferencedName, ...]
|
Every name the source references, in source order, once for each way the source makes the reference. |
accounted |
tuple[str, ...]
|
The names among them that the conventions of the source's language account for, so they need no dependency edge. |
Neighbours
dataclass
¶
Who owns each name the workspace's members reference each other by.
livery.workshop.neighbours makes it from the members; a rule over the sources asks it which member a referenced name belongs to.
Attributes:
| Name | Type | Description |
|---|---|---|
owners |
Mapping[str, str]
|
Each module root a member ships, to the member's path. Each member's extensions answer its roots (livery.workshop.MODULE_ROOTS), so a reference resolves the same way whichever extension made it. |
by_path |
Mapping[str, Package]
|
Every member by its path. |
Methods:
| Name | Description |
|---|---|
owner_of |
The package path owning reference, longest prefix winning. |
owner_of ¶
The package path owning reference, longest prefix winning.
Empty when no package owns it: a third-party name, or the
standard library. Longest prefix, because three distributions
share the livery.toolroom namespace and the shortest match
would attribute two of them to the third.
Source code in packages/workshop/src/livery/workshop/_packages.py
leftover ¶
How git sees directory, a directory under packages/ with no contract.
Source code in packages/workshop/src/livery/workshop/_packages.py
is_group ¶
Whether directory under packages/ groups packages rather than being one.
A group has no workshop.toml of its own and at least one
subdirectory that has one. Groups do not nest.
Source code in packages/workshop/src/livery/workshop/_packages.py
package_directories ¶
List every directory under packages/ that should hold a package.
A package lives at packages/<name>/ or, inside a group
directory, at packages/<group>/<name>/. A group is a directory
with no workshop.toml of its own and at least one subdirectory
that has one. The directories are listed whether or not they carry
a contract, and nothing in them is judged;
livery.workshop.discover_packages reads and judges the
contracts. Reach for this where a glob would assume one level.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The workspace root. |
required |
Returns:
| Type | Description |
|---|---|
Path
|
The directories, sorted by path; empty when root has no |
...
|
|
Source code in packages/workshop/src/livery/workshop/_packages.py
release_tag ¶
The package path and version a release tag names; None for another tag.
A release tag is packages/<member>/v<major>.<minor>.<patch>, and
the member may sit in a group directory:
packages/extensions/widgets/v1.2.0 names
("packages/extensions/widgets", "1.2.0"). Every reader of
release tags parses them here, so a package at any depth under
packages/ releases like any other.
Source code in packages/workshop/src/livery/workshop/_packages.py
receipt_member ¶
The member a release receipt tag names, or "" for another tag.
packages/extensions/widgets/v1.2.0 names extensions/widgets.
Source code in packages/workshop/src/livery/workshop/_packages.py
member_depth ¶
How many leading parts of relative name a package's directory.
2 for packages/forge/..., 3 for packages/<group>/<name>/...
in a group directory, 0 for a path outside packages/ or one
that is the package directory itself or above it.
Source code in packages/workshop/src/livery/workshop/_packages.py
member_of ¶
The member of members whose directory holds relative, or "".
relative is a posix path from the workspace root
(packages/extensions/widgets/src/x.py); members are package
members as livery.workshop.Package names them
(extensions/widgets). The longest match wins.
Source code in packages/workshop/src/livery/workshop/_packages.py
workspace_suite ¶
The workspace's own tests, the tests directory at its root, as a unit.
None when the workspace has none. The unit lists no extension
and holds the root's set. A test step whose extensions that set
holds runs it beside the members it judges
(livery.workshop.scoped_suite). It is no member, so no package
step judges it, and the workspace's category table answers for its
files (is_workspace_unit).
Source code in packages/workshop/src/livery/workshop/_packages.py
is_workspace_unit ¶
Whether package is the workspace's own unit rather than a member.
The workspace's tests (workspace_suite) are its unit, and a root
without them is its own unit, for the files under no package. A
member's path is under packages/, and a unit's is not.
Source code in packages/workshop/src/livery/workshop/_packages.py
holds_runtime_language ¶
Say whether package holds the extension of the workshop's own language.
That extension is python. A member holds it when it lists it,
or when an extension it lists requires it. The workspace's own
tests hold it when the root's set does. Discovery asks this of
every member, so a member that lists it is answered without
reading any extension's declaration.
Source code in packages/workshop/src/livery/workshop/_packages.py
package_paths ¶
The src and tests directories the packages own, as they exist.
The workspace's own tests, a unit whose directory is the tests themselves, contribute that directory.
Source code in packages/workshop/src/livery/workshop/_packages.py
discover_packages ¶
Every package the workspace carries, by its contract, sorted by path.
Raises ValueError, with every finding listed, when a directory
under packages/ lacks its contract, or holds the runtime's
language (holds_runtime_language) and lacks the
pyproject.toml a distribution of that language carries: a
half-present package is a wrong state, not a lesser one. A
directory holding only what a removed package left behind is
named as such, with the fm sync that removes it. A package
that lists no extension holds none, and needs no project file.
Source code in packages/workshop/src/livery/workshop/_packages.py
411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 | |
verify_workspace ¶
The layering lint: check every workspace invariant, or raise.
The graph's invariants (livery.workshop._packages.verify_graph) and the base's rules over every python source (livery.workshop._packages.import_problems) together, in one refusal. Returns the discovered packages when everything holds. Raises ValueError listing every violation verbatim otherwise:
- every
buildedge appears in the native manifest with a constraint carrying its floor, and every workspace-internal native dependency is a declared edge (agreement both ways); - the dependency graph is acyclic, so dependencies only point downward;
- the base imports no extension, and each reference a package's sources make to a sibling is a declared edge.
Source code in packages/workshop/src/livery/workshop/_packages.py
verify_graph ¶
The graph half of the layering lint: the contracts and the native manifests.
Each edge agrees with its native manifest, the graph is acyclic, the extensions a contract lists close over what they require, each contract's step options name what exists, and the root is no package. What it reads is the contracts and the manifests, so a run whose change touched none of them skips it. Returns the discovered packages; raises ValueError listing every violation otherwise.
Source code in packages/workshop/src/livery/workshop/_packages.py
import_problems ¶
import_problems(root: Path, packages: tuple[Package, ...], files: frozenset[str] | None = None) -> list[str]
Every base rule's findings over the sources in scope, each by its step's name.
Source code in packages/workshop/src/livery/workshop/_packages.py
rule_problems ¶
rule_problems(step: str, root: Path, packages: tuple[Package, ...], files: frozenset[str] | None = None) -> list[str]
What the base's layering step step finds over the sources in scope.
files names the root-relative sources a narrowed run judges; None judges every one. A rule over the sources judges the named ones, and a rule over a package's references judges each package holding one.
Source code in packages/workshop/src/livery/workshop/_packages.py
graph_problems ¶
Every violation of the graph's invariants, verbatim; empty when they hold.
Source code in packages/workshop/src/livery/workshop/_packages.py
neighbours ¶
neighbours(packages: tuple[Package, ...]) -> Neighbours
Map each module root packages ship to the member that ships it.
Each member's set answers the roots it ships (livery.workshop.MODULE_ROOTS), so the map names no language. A member whose set answers no root owns no name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
packages
|
tuple[Package, ...]
|
The workspace's members, as livery.workshop.discover_packages reads them. |
required |
Returns:
| Type | Description |
|---|---|
Neighbours
|
The roots by owner and the members by path. |
Source code in packages/workshop/src/livery/workshop/_packages.py
inherited_floor ¶
The floor dep already carries within reach; the highest declared.
Every declaration inside the reachable set is installed, so the highest of them is what resolution already guarantees. That floor claims nothing new: raising one is a decision, and the release's lowest-direct leg is what proves a floor is high enough.
Source code in packages/workshop/src/livery/workshop/_packages.py
undeclared_references ¶
undeclared_references(packages: tuple[Package, ...], *, only: set[str] | None = None) -> tuple[list[tuple[Package, Package, str, str]], list[tuple[Package, Package]]]
Sibling references no edge declares, split by what the graph reaches.
Each package's references answer says what its sources
reference and which names its language's conventions account for;
this resolves each other name to the sibling that owns it and walks
the graph over them. A reference the declared graph already
reaches can be declared without changing what the graph reaches,
so it can introduce neither a cycle nor an upward edge, and it is
returned as (package, dependency, edge kind, floor). Anything else
is a new dependency for a person to decide, returned as
(package, dependency). only judges the packages at those paths
and walks the graph over every one.
Source code in packages/workshop/src/livery/workshop/_packages.py
declare_edge ¶
Declare package's kind edge on dependency at floor; the files written.
For a build, runtime or test edge, the writers of the package's set
first write the native requirement at the same floor
(_lifecycle.declare_requirement), so layering.graph finds
the two in agreement; then the [[depends]] edge joins the
package's contract. A sibling no writer takes refuses before the
contract changes. A test edge in a set with no writer of a test
requirement, and a tool edge, write no requirement. The files are
relative to the package, the contract first.
Source code in packages/workshop/src/livery/workshop/_packages.py
write_edges ¶
Declare every sibling reference the graph already reaches; the lines written.
The fix of the layering phase's sibling-references step. For each reference
livery.workshop._packages.undeclared_references can write, the
writers of the package's set write the native requirement and the
[[depends]] edge joins the package's contract, both at the
floor the graph carries. A reference the graph does not reach is
left for the judge that follows: it is a new dependency, and a
decision. Idempotent: a second call writes nothing.
Source code in packages/workshop/src/livery/workshop/_packages.py
write_test_requirements ¶
Write each test requirement a package's manifests lack; the lines written.
The fix of layering.graph for the test edges it judges: in each
package whose set answers test-requirements, a test edge whose
requirement is missing, or carries another floor, is written at the
edge's floor by the writers of the set
(_lifecycle.declare_requirement). Idempotent: a second call
writes nothing.
Raises:
| Type | Description |
|---|---|
Failed
|
when no writer of a package's set takes a test edge's sibling, naming both sets. |
Source code in packages/workshop/src/livery/workshop/_packages.py
extension_imports_in_the_base ¶
extension_imports_in_the_base(sources: Iterable[SourceReferences]) -> list[str]
Each base module that imports an extension, with the extension named.
The base (livery.workshop) imports no extension under
livery.extensions: what an extension needs of the base it takes through
the base's seams, and the base reaches an extension only through the
registries the extension fills at mount. sources are records of the
references answers; a module that runs without the name it imports
is left alone, and one importing it lazily or for a type checker is
judged.