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 metadata nuitka_matrix against a project to see the matrix it computes, or repomatic show-test-matrix for the test one.

Todo

Drop the per-entry-point --python-flag=-m workaround computed below, and compile a __main__.py entry point through Nuitka’s own --main-entry-point, once Nuitka#3879 ships.

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 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.