repomatic.metadata.matrix module

Job-matrix construction of Metadata.

Builds the Nuitka build matrix and the test matrices from the other concerns’ facts, and applies the repository’s [tool.repomatic] test-matrix configuration to them.

class repomatic.metadata.matrix.MatrixMetadata

Bases: object

The Nuitka build matrix and the test matrices.

A concern mixin of Metadata: never instantiated on its own, and reads sibling concerns through self.

property nuitka_matrix: Matrix | None

Pre-compute a matrix for Nuitka compilation workflows.

Crosses three axes:

• one commit per release commit (during a release) or per new commit (otherwise)

• every [project.scripts] entry point

• every build target of NUITKA_BUILD_TARGETS (runner, platform, architecture, binary extension, and the glibc floor or minimum-OS version that target enforces), narrowed to the [tool.repomatic] nuitka.dev-targets canary subset on an ordinary push (see dev_targets); release commits, schedule and workflow_dispatch runs keep the full roster

Each axis contributes an include entry carrying the extra parameters the compile job needs, keyed on the axis value that selects it: the target’s runner and floors, the entry point’s module and callable, and the commit’s short SHA and version. A final pass adds one include entry per (os, entry_point, commit) triple naming the bin_name the compiled artifact takes, since that name depends on all three at once.

The matrix closes with {"state": "stable"}, which the release workflow reads to decide whether a failing job blocks the release.

Note

Every value comes from NUITKA_BUILD_TARGETS and the project’s own pyproject.toml, so no literal is repeated here: run repomatic show-metadata nuitka_matrix against a project to see the matrix it computes, or repomatic show-test-matrix for the test one.

Note

Each entry point compiles through Nuitka’s --main-entry-point, which needs Nuitka 4.3. Earlier releases crashed on the option (Nuitka#3879), or built a binary that failed at startup when the entry point carried the name of its package (Nuitka#4024).

property test_matrix: Matrix

Full test matrix for non-PR events.

Combines all runner OS images and Python versions, excluding known incompatible combinations. Marks development Python versions as unstable so CI can use continue-on-error, and adds released build flavors (free-threaded) as stable single-runner smoke tests. Per-project config from [tool.repomatic.test-matrix] is applied last.

When [tool.repomatic.test-matrix] full-include rows are configured, the matrix is emitted as a flat job list ({"include": [...]}) so each row is a standalone combination GitHub runs verbatim, rather than one that augments a base combo sharing its os and python-version.

property test_matrix_pr: Matrix

Reduced test matrix for pull requests.

Skips experimental Python versions and redundant architecture variants to reduce CI load on PRs. Per-project config excludes and includes from [tool.repomatic.test-matrix] are applied, but variations are not (to keep the PR matrix small).

property runner_arch: dict[str, str]

Architecture of every runner image the full test matrix can land on.

A repository whose suite asserts on the architecture it detects needs to know which of its cells are ARM. Reading it from here rather than restating it locally is what keeps that knowledge from going stale when TEST_RUNNERS_FULL moves to a newer image: a hard-coded runner list keeps matching the images it was written for, and the new one quietly takes whichever branch the test left as its default.

Covers the include directives as well as the os axis, so the single-runner build-flavor cells (see SINGLE_RUNNER_PYTHON_VERSIONS) are described too, and the per-project variations.os images along with them. Architectures are emitted as Extra Platforms ids (aarch64, x86_64), matching the arch field of FLAT_BUILD_TARGETS.

Returns:

Runner label to architecture id, sorted by label.

property stale_test_matrix_excludes: list[tuple[dict[str, str], dict[str, str]]]

User test-matrix.exclude entries matching no full-matrix axis value.

An exclude naming a value absent from every axis (like a renamed runner) can never match a combination, so Matrix.prune() drops it silently and its exclusion intent is lost. This drift is common after an upstream runner rename (such as macos-15-intel becoming macos-26-intel). The lint-repo check surfaces these so the drift fails loudly instead of silently.

The axes come from _test_matrix_base, never from the emitted test_matrix: a full-include matrix emits as a flat job list whose all_variations() is empty, which would misreport every key of an entry as stale. Carrying the absent values in the result is what keeps the lint check from re-deriving them against the wrong matrix.

Returns:

(entry, absent_values) pairs in config order: each offending exclude with the key/value pairs no axis carries.