livery-extensions-python¶
Python distributions: each package's version stamped, its wheel and
sdist built, published to a python index and verified, its suite run
against the installed wheel for a release, and the layering rules over
the python sources. A package turns it on by listing the extension in
its own workshop.toml:
The package's pyproject.toml is its manifest: it declares the
version, the requirements and the scripts. fm new.project lists
python at the root, since the workspace's own tests and tasks.py are
python. A workspace that does not list it has no python steps, no
python-library template, and no way to create a workshop-extension
package, whose template extends python-library. The nanobind
extension requires python, since its packages are python
distributions, and its distribution requires this one.
A new package¶
fm new.package.python-library <name> creates a python package while
the workspace lists python: a typed module under src/, its tests, and
a pyproject.toml uv builds. --command=<script> adds the script
<script> to [project.scripts], which runs main() in the package's
__main__.py, and a test of it; without it the package has no script.
A workspace that does not list python has no such verb: list the
extension in [workspace] extensions and run fm sync, which installs
livery-extensions-python, and the verb exists. Until then
fm new.package.workshop-extension refuses, naming python and its
distribution.
A package's files¶
python gives the paths of each package whose set holds it these categories:
| Category | Patterns |
|---|---|
test |
tests/**/test_*.py, tests/**/*_test.py |
test-support |
tests/** |
source |
src/** |
The most specific pattern wins, so a test module under tests/ is a
test and every other file there, conftest.py among them, supports
the tests.
A release¶
python adds a step to each phase of a python package's release:
stamp.pythonwrites the version intopyproject.tomland into each__init__.pyundersrc/that carries__version__, and raises each requirement on a member released with the package,"<name>>=<floor>"wherever the pyproject declares it, to that member's version; a member released alone moves no floor. The entry module serves the same work as livery.extensions.python.stamp, which nanobind's stamp step calls.build.pythonbuilds the wheel and the sdist withuv buildinto the package'sdist/, from an emptydist/each time. The wheel carries the package'sdocs/as the module's_docs, copied for the build and removed after it. The build refuses a wheel tagged for a platform: python's build ships a pure wheel, taggednone-any, so a package with compiled code lists the extension that builds its platform wheels, such as nanobind.test.pythoninstalls the built wheel into a fresh environment and runs the package's tests against the installed copy, once per resolution the release proves:floorinstalls every direct dependency at its declared floor,latestthe newest, andheadthe versions the workspace lock pins. The wheel resolves from the co-released set'sdist/directories and the workspace's indexes alone, and installs with itstestextra when the package declares one. The test toolchain installs after the wheel, at the lock's pins, and a toolchain install that moves a direct dependency the leg resolved refuses, naming it.publish.pythonuploads the wheel and the sdist withuv publishto the registry target the release resolves. An empty upload address refuses, since uv's own default is PyPI. An emptyUV_PUBLISH_TOKENnever reaches uv, so trusted publishing still runs, and a version the index already holds is walked past.verify.python, whichfm release.verifyruns, installs the released version alone into a plain environment and runs the package's tests at the released tree against it.
The release train probes the python index the registry ladder resolves for the package, through the simple API, before it uploads.
fm run¶
python answers executables with the scripts a package's
pyproject.toml names under [project.scripts]. fm run starts the
one it names from the workspace's environment, which fm sync
installs, with the words after the dashes, and exits with its code. A
script the environment lacks refuses, naming fm sync.
The layering rules¶
python answers the references query for python sources from one
parse per gate, memoised by the file's path, size and modification
time. Its three steps of the layering phase read the same parse, over
the files a narrowed run reaches or every source:
private-reaches: no package's source reaches another distribution's private name, apart from the reaches the root contract's[[python.private-reaches]]allows, each with its reason. An entry no source uses any more refuses.runner-terminal: a module that imports the runner askslivery.footman.attended()whether a person is there, never the terminal (sys.stdin.isatty()and its relatives), since the terminal knows nothing of--no-inputor--dry-run. The runner's own sources, and a module that never imports the runner, are exempt. The step judges the root'stasks.pywith the packages' sources.declared-imports: at import time, a module under a package'ssrcimports the standard library, the workspace's own members, and the distributions itspyproject.tomldeclares in[project.dependencies]. Inside a function it may also import a distribution an optional extra declares. An import underTYPE_CHECKING, or in atrythat handlesImportError, is not judged. A module a program loads as a plugin, named under thefootman.tasksorfootman.builtinentry points for the runner orpytest11for pytest, may also import what that program brings: its distribution and the distributions it requires. A refusal names the source, the module, the distribution and thepyproject.tomlto declare it in.
An allowed reach is a table of the root contract:
[[python.private-reaches]]
from = "acme-tools"
reaches = "acme.core._registry.purge"
reason = "the loop deletes published versions until the admin protocol exists"
Requirements¶
python's requirement writers take a sibling that holds python alone. A
build or runtime edge writes the sibling's requirement into the
package's [project.dependencies] at the edge's floor; a test edge
writes it into the test extra of [project.optional-dependencies],
which is python's answer to test-requirements, and which the
release's isolated test installs the wheel with. A manifest with no
[project] table refuses, and so does a test extra in a form the
edit does not take, naming the line to write by hand.
What a change to a pytest plugin reaches¶
pytest loads every module a member's pyproject.toml names under the
pytest11 entry points into every session it starts. While pytest is
listed, python answers the base's reaches query, so a change to such
a module runs every member pytest runs over, not only its own package
and that package's dependents. A changed path widens when:
- it is a module a member names under
pytest11, or a file under such a package; - the change removed it, and the tree the change is measured from named it there;
- it is a member's
pyproject.tomlwhosepytest11table differs from that tree's.
The members pytest runs over are those whose set holds an extension
pytest's test or examples step names, unless the member turned both
steps off. fm graph.affected and the gate print one line for each
path that widens, with why. A module a plugin imports, and does not
name, reaches only its own package's dependents.
The queries it declares¶
python.test.runnerandpython.examples.runner: who runs the python packages' suites, several in one call, and one package's documentation examples. python answers both while pytest is listed, and pytest's test and examples steps ask them.python.test.preview: who prints a machine's coverage preview after its suites ran. The coverage extension answers it while python is listed.
Its public names¶
livery.extensions.python serves the names an extension that builds a
python package's wheels with a tool of its own reads, as nanobind
does:
module_docs(package)copies the package'sdocs/into its source tree as the wheel's embedded_docsfor one build, and removes the copy after it.run_isolated_test(package, root, ...)installs a built wheel into a fresh environment and runs the package's tests against the installed copy.