ci(python): the version updater flags a job its update would empty (#1747)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

Closes #1747. Since #1746, pypcap-parity holds only supported legs. Once 3.11 reaches end of life its matrix is empty, but required-checks still needs it. Under the owner's ruling, the updater retires nothing itself; it flags the job instead.

• Detection: emptied_jobs() finds every matrix job the script reads that goes from at least one leg to none, KTLO twins and experimental.yml included. It emits a manual note naming the job, the version moves that empty it, and the jobs that needs: it. Example: "pypcap-parity would have no leg left once 3.11 moves to KTLO; retire or remove the job (and its needs: in required-checks) before merging this update."
• Where the note shows: first in the PR body, in bold before the ruleset edit. The run also annotates it as a warning and records it in plan.json.
• What the updater writes: the tiers exactly as computed. The fingerprint stays tiers-only, so retiring the job on main does not re-propose the update and recreate the branch.
• Docs: the "Python Versions" paragraph of workflows.rst is updated.
• Tests: a new test_python_versions_empty_job_1747.py (5 tests, all failing on main). The 1660, 1738, queue and doc-claims suites pass.

[JarryShaw]

Verdict: GOOD TO GO at fb36baaad. A Sonnet cross-review checked it (author: Opus).

• Scenarios: the reviewer built its own, calling emptied_jobs directly and running a real update --out and body. With 3.11 leaving the supported tier there is one note, for pypcap-parity, naming required-checks. A KTLO twin emptying is flagged on its own. A job dropping to one leg gets no note.
• Scope: only util/update_python_versions.py, the two tests and workflows.rst change. No workflow file and nothing under pcapkit/**.
• Tests: the new tests fail on main and pass here.
• My own re-run in the PR's tree: 1747 (5 passed), update_1660 (57) and unit_tests_queue (38).

[github-actions]

Coverage: 89.57% (unit tier, Python 3.15, fb36baaad, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	3	20	3	95.16%
pcapkit/const	18860	954	2368	868	91.06%
pcapkit/corekit	2457	69	780	35	96.54%
pcapkit/dumpkit	276	3	100	3	98.40%
pcapkit/foundation	2906	164	1016	34	93.57%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17174	225	4588	190	98.07%
pcapkit/toolkit	864	182	298	9	76.33%
pcapkit/utilities	512	2	158	4	99.10%
pcapkit/vendor	4417	2342	1010	157	43.38%

Per-file detail: the coverage-html artifact of this run.