fix(packaging): split the testing extras and stop publishing testcontainers

[ogenstad]

Short version

Some time ago we had an option to install with pip install infrahub-sdk[tests] that has been broken for some time. Here we replace it with pip install infrahub-sdk[testing] this is to avoid confusion with the dependency groups as we also have a "tests" group for development dependency. We also move out the infrahub-testcontainers into its own group with pip install infrahub-sdk[testcontsiners]. So:

• testing: Anything needed to run our own pytest plugin for transforms etc
• testcontainers: When you need to do anything with Docker integration tests

Why

The tests extra added in #1277 bundled infrahub-testcontainers, and it should not have. That package has never been shipped to users by any release of this SDK: it has been a dev dependency since Damien added it in e4d190f1 (2024-12-24), for the SDK's own integration tests. Publishing it took the extra from the four packages it historically installed to sixty-one, including amplitude-analytics, for anyone who only wanted to test a Transform.

Worth being clear about how that happened, since it says something about the check added in the same PR. The new per-surface import test flagged infrahub_sdk/testing/docker.py importing a package nothing declared, and the resolution taken was to declare it in a user-facing extra. The correct reading was that the module is dev scaffolding which merely happens to live inside the package directory. A published API was changed to satisfy a test written minutes earlier.

Nothing has released yet, so this is free to correct. [tests] exists only on infrahub-develop.

Goal: two extras that each mean one thing to a user, with the heavy container tooling opt-in.

Non-goals: whether infrahub_sdk.testing should ship in the wheel at all. It is undocumented, and a base class in it (TestInfrahubDockerClient) looks like something a downstream consumer would inherit. That deserves a decision from whoever owns the module, not a packaging change here.

What changed

Behavioral changes:

• pip install 'infrahub-sdk[testing]' installs pytest and enables the bundled pytest-infrahub plugin. Four packages on top of a plain install.
• pip install 'infrahub-sdk[testcontainers]' additionally provides infrahub_sdk.testing.docker, which starts a real Infrahub in containers. Around sixty packages, and now only reached by asking for it by name.
• The tests extra is gone. It installed nothing at all from 1.16.0 (2025-12-01) onwards while the docs kept advertising it, so there is no working install to preserve. [testing] is the direct replacement for what [tests] gave users up to 1.15.2.
• infrahub-sdk[all] now aggregates ctl, testing and testcontainers.

Implementation notes:

• Only docker.py needs the container tooling, so EXTRA_ONLY_MODULES in the import check is now per-file rather than per-package. testing/repository.py is deliberately absent from it and held to the base install, because that is the truth: it needs nothing beyond the core dependencies, and tests/unit/sdk/test_repository.py imports it today.
• The check now follows self-referential extras. Without that, testcontainers looked as though it installed nothing, since its pytest requirement arrives via infrahub-sdk[testing]. The check caught this itself on the first run.
• tests is dropped rather than kept as an alias for testing. Two near-identical names would only invite installing the wrong one, and there is no functioning install behind the old name to keep working.

Verified behaviour, installing the built wheel into a clean environment for each:

Install	Packages	plugin	testing.docker	testing.repository
base	27	-	-	yes
[testing]	31	yes	-	yes
[testcontainers]	88	yes	yes	yes
[all]	93	yes	yes	yes

What stayed the same: no runtime code changed. Packaging metadata, the import check's surface map, docs, and changelog.

How to review

Start with pyproject.toml, then the EXTRA_ONLY_MODULES and _declared_in changes in tests/unit/test_packaging_metadata.py. Docs and changelog follow from those.

The judgement call worth scrutiny is dropping tests outright. The case for it: broken for nine months across nineteen releases, so no meaningful population depends on it resolving. The case against: it did work up to 1.15.2, and 1.15 is a maintained line, so someone upgrading from there sees a removal. That is why the changelog entry names the replacement explicitly.

How to test

uv run pytest tests/unit/test_packaging_metadata.py
uv run invoke lint-code
uv lock --locked --offline
uv run towncrier build --draft --version 1.24.0

Verified locally: ruff, ty and mypy 2.3.1 clean; unit suite 1859 passed with 2 failures that reproduce identically on the base branch (macOS-only Rich wrapping of long temp paths, in files this PR does not touch); 33 passed on both 3.10 and 3.12 for the metadata module; lock consistent; docs-validate exit 0; lint-docs unchanged at its 20 pre-existing errors.

Changelog

The fragments from #1277 are unreleased, so they were corrected rather than supplemented, to stop the 1.24 notes announcing [tests] and then retracting it:

• +tests-extra.added.md removed, replaced by +testing-extras.changed.md describing the final state and the migration from [tests]
• +dependency-lower-bounds.changed.md now attributes packaging to the testcontainers extra rather than tests
• +core-template-dependencies.fixed.md, +rich-upper-bound.changed.md and +packaging-metadata-tests.housekeeping.md re-read and left alone; all three are still accurate

Documentation Updates

• docs/docs/python-sdk/guides/installation.mdx: tests section replaced by testing and testcontainers, each explaining what it gives you. The size note added in fix(packaging): correct declared dependencies and publish the tests extra #1277 moves to testcontainers, where it is now true.
• docs/docs/python-sdk/introduction.mdx: both the uv and pip tabs updated.
• README.md: same treatment as the installation guide.

Impact & rollout

• Backward compatibility: removes an extra that has installed nothing since 1.16.0, and reshapes one that has never been released. No published install changes behaviour. Anyone on 1.15.2 or earlier using [tests] should move to [testing].
• Performance: no runtime impact.
• Config/env changes: none.
• Deployment notes: safe to merge independently. Should land before 1.24 ships, after which removing tests would need a deprecation.

Checklist

• Tests added/updated
• Changelog entry added
• External docs updated (if user-facing or ops-facing change)
• Internal .md docs updated (internal knowledge and AI code tools knowledge)

---

Summary by cubic

Splits the testing extras so infrahub-sdk[tests] no longer publishes infrahub-testcontainers (a dev dependency never meant for users). The tests extra is replaced by testing for pytest support and testcontainers for running Infrahub in containers.

• pip install 'infrahub-sdk[testing]' installs pytest and enables the bundled plugin; [testcontainers] adds the container-based infrahub_sdk.testing.docker.
• The old tests extra has installed nothing since 1.16.0, so no working install is affected.
• The import check now maps testing/docker.py to the testcontainers extra per-file and follows self-referential extras.
• Docs and changelog updated to name the new extras; anyone on 1.15.2 or earlier should use [testing].

^{Written for commit 546dc82. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	546dc82
Status:	✅  Deploy successful!
Preview URL:	https://decaff54.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://pog-testing-extras.infrahub-sdk-python.pages.dev

View logs

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@                 Coverage Diff                  @@
##           infrahub-develop    #1317      +/-   ##
====================================================
- Coverage             85.55%   85.33%   -0.22%     
====================================================
  Files                   148      148              
  Lines                 14282    14085     -197     
  Branches               1953     1936      -17     
====================================================
- Hits                  12219    12020     -199     
- Misses                 1496     1499       +3     
+ Partials                567      566       -1     

Flag	Coverage Δ
integration-tests	43.40% <ø> (-0.60%)	⬇️
python-3.10	60.17% <ø> (-0.55%)	⬇️
python-3.11	60.16% <ø> (-0.58%)	⬇️
python-3.12	60.16% <ø> (-0.58%)	⬇️
python-3.13	60.17% <ø> (-0.57%)	⬇️
python-3.14	60.17% <ø> (-0.55%)	⬇️
python-filler-3.12	21.93% <ø> (+0.30%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 3 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[cubic-dev-ai]

No issues found across 9 files

_{Re-trigger cubic}