livery.extensions.python._backend¶
livery.extensions.python._backend ¶
Build, version, publish and test a python distribution: the python extension's code.
The python extension's answers and steps call the functions here, so a package whose set holds python builds, stamps, publishes and runs its tests through them. The suites of every package a run judges run in one pytest call.
Functions:
| Name | Description |
|---|---|
public_modules |
The modules that declare package's public API. |
module_for |
The package's importable module, read from its src tree. |
current_version |
The version the package's |
stamp_version |
Where a Python package's version lives, ready to stamp. |
stamp |
Write version and raise package's floors in its manifests; the files changed. |
raise_floors |
Raise each requirement on a member released with package; the files changed. |
test |
Run package's tests: its suite, or the files in selection alone. |
examples_of |
The example files package ships under |
run_examples |
Run package's documentation examples, one test per file; arguments to pytest. |
runner_shaped |
env with the runner's variables set, as the check legs see the suite. |
run_test |
Run the suites of packages in one pytest call, pytest_args unchanged. |
speed_lines |
Each package's summed test time; on a check leg, beside its mark there. |
module_roots |
The import prefixes package owns. |
root_marks |
The files that mark an importable root under src, shallowest first. |
scripts |
The scripts package's |
run_script |
Start the script name from the workspace's environment; its exit code. |
plugin_hosts |
Each module package names in a plugin group, to the programs that load it. |
plugin_reaches |
Each changed path pytest loads as a plugin, to why, and every member pytest runs. |
plugin_modules |
The modules package declares as footman task entry points. |
references |
What each python source of package references, one record per file. |
declared_requirements |
The package's declared dependencies, name to constraint text. |
declared_test_requirements |
The package's |
declare_requirement |
Add |
declare_test_requirement |
Write |
module_docs_dir |
Where package's wheel-embedded |
materialise_module_docs |
Copy the package's |
module_docs |
The wheel-embedded |
build |
Build package's wheel and sdist into its |
publish_artifact |
Upload |
publish_wheels |
Upload |
isolated_test |
Test package's built wheel in a fresh venv at resolution; what it got. |
verify |
Install package's released version alone and run its tests at tree. |
run_isolated_test |
Install the built wheel into a fresh venv and test the installed copy. |
Attributes:
| Name | Type | Description |
|---|---|---|
EXTENSION |
|
|
PURE_TAG |
|
|
RUNNER_VARIABLES |
|
|
COVERAGE_CONFIG |
|
|
METER |
|
|
PREVIEW |
Query[Callable[[Path, tuple[Package, ...]], None] | None]
|
|
RUNNER_DISTRIBUTION |
|
|
PLUGIN_GROUPS |
Mapping[str, str]
|
|
PYTEST |
|
|
PYTEST_STEPS |
|
|
TEST_EXTRA |
|
|
RESOLUTIONS |
dict[str, tuple[str, bool]]
|
|
PREVIEW
module-attribute
¶
PLUGIN_GROUPS
module-attribute
¶
PLUGIN_GROUPS: Mapping[str, str] = {'footman.tasks': RUNNER_DISTRIBUTION, 'footman.builtin': RUNNER_DISTRIBUTION, 'pytest11': 'pytest'}
RESOLUTIONS
module-attribute
¶
RESOLUTIONS: dict[str, tuple[str, bool]] = {'floor': ('lowest-direct', False), 'latest': ('highest', False), 'head': ('highest', True)}
public_modules ¶
The modules that declare package's public API.
A root that is a regular package, or a single module, is its own
declaration. A public package beneath a root keeps its own import
path and is declared in the root's __init__ as well, imported
for the checkers alone and listed in __all__: the verifier
follows the declaration into it, reading the py.typed at the
distribution's root. A namespace root, one with no __init__,
declares nothing; a package with no src tree is its distribution
name's module.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
module_for ¶
The package's importable module, read from its src tree.
The single-directory chain under src/ down to the first
directory carrying python files is the module
(src/livery/forge is livery.forge). Deriving it from the
distribution name guessed wrong the moment a member's own name
carried a hyphen: loop-echo under a workspace prefix became
loop.echo, a module that does not exist. A package without a
src tree, or whose src/ holds no single directory to start the
chain, falls back to the dist-name spelling, underscores for
hyphens beyond the namespace dot.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
current_version ¶
The version the package's pyproject.toml declares.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
stamp ¶
Write version and raise package's floors in its manifests; the files changed.
The version goes into pyproject.toml and every __version__
(stamp_version), and each requirement on one of floors, the
members released with package, takes that member's version
(raise_floors). Each file once, relative to the package's
directory.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
raise_floors ¶
Raise each requirement on a member released with package; the files changed.
floors names each such member by its path, to the version it
releases at. A requirement on its distribution in
pyproject.toml, "<name>>=<floor>" wherever the file
declares it (its dependencies, its extras, its groups), takes that
version. Empty for no floors, and for a pyproject that names none of
them.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
test ¶
test(package: Package, root: Path, *, selection: tuple[str, ...] = (), arguments: tuple[str, ...] = ()) -> None
Run package's tests: its suite, or the files in selection alone.
arguments go to pytest after the workshop's own.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
examples_of ¶
The example files package ships under docs/examples/, sorted.
A conftest.py there is the package's setup around them, never
an example.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
run_examples ¶
run_examples(package: Package, root: Path, files: tuple[str, ...] = (), arguments: tuple[str, ...] = ()) -> None
Run package's documentation examples, one test per file; arguments to pytest.
Pytest over the package's docs/examples/ directory, or over
files alone when every one of them is an example, whose files
the workshop's examples plugin collects
(livery.workshop.is_example), from the workspace root so
the workspace's pytest configuration applies. A named file that is
no example, the examples' conftest.py, is every example's
setup, so the whole directory runs. Captured and printed on a red
exit, so a runner's log carries the failing example's file and
line; a package without examples says so and passes.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
runner_shaped ¶
env with the runner's variables set, as the check legs see the suite.
run_test ¶
run_test(*pytest_args: str, packages: tuple[Package, ...], root: Path, selection: Mapping[str, tuple[str, ...]] | None = None, point: str = '', measured: bool = False) -> None
Run the suites of packages in one pytest call, pytest_args unchanged.
The call collects each package's own test directory, the
workspace's own tests when their unit is among packages, and
nothing else, so a package a run leaves out is never collected;
selection names, per package path, the test files that stand for
the package's directory. point selects that CI point's tests,
through the workshop's points plugin. A measured run measures
coverage over the namespace the configuration names: inside CI the
tests run metered for the gate job's union, and on a machine the
run prints the preview a listed extension answers
python.test.preview with
(livery.extensions.python._backend.PREVIEW), the coverage
extension's figure beside each floor, or none. A run that is not
measured runs no meter and prints no preview. A machine's run sets
the runner's variables (RUNNER_VARIABLES), so the suite is judged
the way the legs judge it. With no test directory among the
packages no pytest starts, since one handed no path would collect
the whole configuration.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 | |
speed_lines ¶
Each package's summed test time; on a check leg, beside its mark there.
sums is the file the speed plugin wrote; no file means the plugin did not run. With leg the run is a check leg's, and each line carries the package's mark on that leg or says there is none; an unreadable store says so once and the times still print. Without leg the run is a machine's: the times print alone, since the marks are judged on the CI legs and a machine's clock is not one of them, and nothing here reads the store.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
module_roots ¶
The import prefixes package owns.
The build backend's module-name where the manifest declares
one, since that is what the wheel ships. Otherwise each topmost
directory under src holding an __init__.py on its branch,
which finds nothing under a namespace root, one with no public
names. Never derived
from the distribution name: three distributions share the
livery.toolroom namespace, so a transformed name would
attribute two of them to the third. A package with no python
source owns nothing.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
root_marks ¶
The files that mark an importable root under src, shallowest first.
A root carries an __init__.py; the topmost on a branch is that
branch's root. A namespace, one with no __init__.py, marks
nothing.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
scripts ¶
The scripts package's pyproject.toml names under [project.scripts].
Each by the name its installation puts on PATH, in the file's order; empty for a package without the file or the table.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
run_script ¶
Start the script name from the workspace's environment; its exit code.
The script is the one fm sync installs into the .venv at
root, started with arguments and the console shared.
Raises:
| Type | Description |
|---|---|
Failed
|
when the environment holds no script of that name, naming the directory and the verb that installs it. |
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
plugin_hosts ¶
Each module package names in a plugin group, to the programs that load it.
Read from the [project.entry-points] tables of the package's
pyproject.toml, for the groups PLUGIN_GROUPS names, each
program by its distribution. A module under one of these modules
is loaded with it. Empty for a package that names none.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
plugin_reaches ¶
Each changed path pytest loads as a plugin, to why, and every member pytest runs.
pytest loads every module a member's pyproject.toml names in a
group PLUGIN_GROUPS gives it into every session it starts, so a
change to one reaches every member a step of PYTEST_STEPS runs
pytest over. A changed path widens when it is such a module, or a
file under such a package, as the working tree names them; when
the change removed it and changes' earlier tree named it; and
when it is a member's pyproject.toml whose plugins for pytest
differ from the earlier tree's. Empty when no changed path widens.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
plugin_modules ¶
The modules package declares as footman task entry points.
A module the runner loads as a plugin has the runner present by construction, and whatever the extension stack mounts with it, so its imports of either are not dependencies of the distribution. The fact lives in the package's own metadata; nothing here needs to be told a second time.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
references ¶
references(package: Package) -> tuple[SourceReferences, ...]
What each python source of package references, one record per file.
Every .py file under src, then under tests, in path
order, read through the layering phase's one parse, so a file
another rule also reads is parsed once per gate; a file that does
not parse is left out, since the syntax gate names it. A source
under src is referenced by its dotted path, and a test by
nothing. Two of python's conventions account for a name: each
name a module the package declares as a footman task entry point
references, since the runner that loads the module brings what it
imports, and each name of a sibling one of its optional extras
names, since an extra is a declaration of its own.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
declared_requirements ¶
The package's declared dependencies, name to constraint text.
Read from [project.dependencies]; the layering lint compares
these against the contract's build and runtime edges.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
declared_test_requirements ¶
The package's test extra, name to constraint text.
Read from [project.optional-dependencies] test; the layering
lint compares these against the contract's test edges. Empty for a
package that declares no such extra.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
declare_requirement ¶
Add <dependency>>=<floor> to the project's dependencies; the files changed.
The python extension's requirement writer, its answer to the
requirement-writers query. It takes a sibling whose set holds
python, which the pyproject names as a distribution, and returns
None for any other sibling, which it leaves to another writer of
the package's set. A text edit that keeps the manifest's
formatting: the entry joins the existing list, one per line, or
opens the list when the project declares none. Already declared,
whatever the constraint, means nothing to write. A manifest without
a [project] table refuses naming it.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
declare_test_requirement ¶
Write <dependency>>=<floor> into the test extra; the files changed.
The python extension's writer of a test requirement, its answer to
the test-requirement-writers query. It takes a sibling whose set
holds python, and returns None for any other sibling. The line
carries the edge's floor: one that names the sibling at another
constraint is replaced, and one that carries the floor already
means nothing to write. An empty floor writes the name alone. A
text edit that keeps the manifest's formatting and comments: the
line joins the extra, kept on one line while it fits in 88 columns
and one requirement to a line beyond; the extra opens, after a
comment saying what it holds, at the end of
[project.optional-dependencies]; and that table opens after the
[project] table when the project declares none.
Raises:
| Type | Description |
|---|---|
Failed
|
when the manifest has no |
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
module_docs_dir ¶
Where package's wheel-embedded _docs lives; None without a module.
In the shallowest of the package's module roots (module_roots)
whose directory exists under src, the importable package the
wheel ships. Of two roots with as many parts, the one answered
first.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
materialise_module_docs ¶
Copy the package's docs/ into its wheel-embedded _docs, whole.
The copy is rebuilt from scratch, so the wheel never carries docs
older than the tree it is built from, and a package without
docs/ loses its old copy instead of shipping it.
Returns:
| Type | Description |
|---|---|
Path | None
|
The copy's path; None when the package has no module to carry |
Path | None
|
it, or no |
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
module_docs ¶
The wheel-embedded _docs, in the source tree for one build alone.
On entry the package's docs/ is copied whole to _docs in
the shallowest of its module roots, the importable package its
wheel ships, replacing any older copy. On exit the copy is
removed, after a failed build too. A copy left behind puts the
docs' example files under the package's source, where every
checker that walks the tree judges them as the package's own code.
Yields:
| Type | Description |
|---|---|
Generator[Path | None]
|
The copy's path; None when the package has no module to carry |
Generator[Path | None]
|
it, or no |
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
build ¶
Build package's wheel and sdist into its dist/; the dist dir.
Always from a clean dist/: reusing an artifact from an
earlier build installs stale code under current tests, a silent
footgun bought off for seconds of build. epoch (a commit's
timestamp) rides SOURCE_DATE_EPOCH so a pure-Python rebuild
at the same ref is byte-identical.
Raises:
| Type | Description |
|---|---|
Failed
|
when |
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
publish_artifact ¶
publish_artifact(package: Package, root: Path, *, version: str, target: RegistryTarget) -> bool
Upload dist/* to the python index: python's publish step calls it.
uv publish, to the target's upload endpoint with its
credential. version and root are what another ecosystem's
publisher reads: the wheels in dist/ already carry their
versions, and the index needs nothing from the workspace.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
publish_wheels ¶
Upload dist/*; False when everything was already published.
uv publish, with the already-published duplicate the one
tolerated failure: a re-run must walk past what an earlier
attempt landed. Anything else, a rejected credential, an
unreachable index, surfaces verbatim.
The upload address is required: without --publish-url uv
silently defaults to PyPI, and an undeclared endpoint must
refuse rather than surprise. A deliberate PyPI publish arrives
here as the ecosystem rung's explicit URL.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
isolated_test ¶
isolated_test(package: Package, root: Path, *, release_dirs: tuple[Path, ...], resolution: str) -> dict[str, str]
Test package's built wheel in a fresh venv at resolution; what it got.
livery.extensions.python.run_isolated_test runs it.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
verify ¶
Install package's released version alone and run its tests at tree.
The exit code; livery.extensions.python._verify.verify runs it.
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
run_isolated_test ¶
run_isolated_test(package: Package, root: Path, *, release_dirs: tuple[Path, ...] = (), resolution: str = 'latest', wheels_dir: Path | None = None) -> dict[str, str]
Install the built wheel into a fresh venv and test the installed copy.
One leg of the release's isolated test, at resolution: floor
puts every direct dependency at its declared floor, so a floor
lying about compatibility fails here; latest resolves the
newest, the world a fresh consumer gets; head installs at the
versions the workspace lock pins, read as it stands, and refuses
in a workspace without a lock.
--find-links is limited to release_dirs, the co-released
set's dist/ directories: a leftover wheel from a non-released
package must never mask that the release needs an unpublished
dependency version. Everything else resolves from the repo's
configured indexes, like a real consumer.
Each distribution those directories carry is refreshed in uv's
cache, so a member rebuilt at the same version installs the wheel
just built and never an earlier build of the same filename.
The toolchain installs after the wheel, at the lock's dev-group pins where a lock exists (bare pytest otherwise), and a probe then re-reads the package's own direct dependencies: the second install is pip-shaped and moves versions without erroring, so a toolchain pin that overlaps a floored dependency would silently undo the starvation. Movement is a taught refusal.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
package
|
Package
|
The member whose wheel is installed and tested. |
required |
root
|
Path
|
The workspace root, whose lock and indexes the install reads. |
required |
release_dirs
|
tuple[Path, ...]
|
The co-released set's |
()
|
resolution
|
str
|
|
'latest'
|
wheels_dir
|
Path | None
|
Where the wheel to install is, for a leg that built
one outside the collected |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
The resolved version per distribution, the report's raw |
dict[str, str]
|
material ("floor leg: livery-forge 0.1.0"). |
Raises:
| Type | Description |
|---|---|
Failed
|
when resolution is none of the three, when no wheel is there to install, when the head leg finds no lock, when an install fails, when the toolchain install moves a direct dependency the leg resolved, and when the tests fail. |
Source code in packages/extensions/python/src/livery/extensions/python/_backend.py
1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 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 | |