fix(update-check): skip releases with no files and do not fall back to an uninstallable version (#4560)

## Description

`_select_latest` (`headroom/update_check.py:153-193`) promises the
newest non-yanked release, but it treated a release whose file list is
empty as installable, and when no release was installable it fell back
to `info.version`, which names one of those releases. The update banner
could then advise a version `pip` cannot install. Releases with an empty
file list are now skipped like fully yanked ones, and when `releases`
lists versions but none is installable the function returns `None`; the
`info.version` fallback is kept for a payload with no `releases`. Item 3
of #4546.

Refs #4546

This PR used to carry all three items of #4546; per the
one-logical-change-per-PR rule the other two are now #4562 (null
thinking block) and #4563 (interior blank CSV rows).

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/update_check.py`: skip a release when its file list is empty
or every file is yanked; return `None` instead of the `info.version`
fallback when releases are listed but none is installable.
- `tests/test_update_check.py`:
`test_select_latest_skips_release_with_no_files`,
`test_select_latest_no_fallback_when_every_release_is_unavailable`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
# fail before (source at a2d4fe72, new tests kept)
FAILED tests/test_update_check.py::test_select_latest_skips_release_with_no_files  (assert '9.9.9' == '1.0.0')
FAILED tests/test_update_check.py::test_select_latest_no_fallback_when_every_release_is_unavailable

# pass after: tests/test_update_check.py tests/test_update_helpers.py
74 passed

# ruff check / ruff format --check: All checks passed! / 2 files already formatted
```

## Real Behavior Proof

- Environment: Ubuntu (WSL2) on Windows 11, Python 3.12.15, `headroom`
Python source at `a2d4fe72` and at this branch, offline.
- Exact command / steps: `_select_latest({"info": {"version": "1.0.0"},
"releases": {"1.0.0": [{"yanked": False}], "9.9.9": []}},
allow_pre=False)` and `_select_latest({"releases": {"9.9.9": []},
"info": {"version": "9.9.9"}}, allow_pre=False)`.
- Observed result: on `a2d4fe72`: `9.9.9` and `9.9.9`. On this branch:
`1.0.0` and `None`.
- Not tested: whether PyPI's JSON API ever lists a release with no files
(the fix follows the function's own docstring); the full suite and
`mypy`.

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A
- Stable/default behavior changed: Only for payloads where every listed
release is uninstallable; the banner then stays quiet instead of naming
an uninstallable version.
- Kill switch / disable path: `HEADROOM_UPDATE_CHECK=off` (existing).
- Unsafe override required: No
- Qualification impact: None expected
- Rollback path: revert this PR.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Produced with AI assistance (Claude Code) operated by me (HetCreep); the
reproduction was run on my machine against a clone of the repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
HetCreep
2026-11-04 23:19:58 -06:00
committed by GitHub
co-authored by Claude Opus 5.5 JD Davis
parent 8c360ca69f
commit c1dae5adae
2 changed files with 19 additions and 5 deletions
+7 -5
View File
@@ -158,11 +158,9 @@ def _select_latest(data: dict[str, Any], *, allow_pre: bool) -> str | None:
candidates: list[Version] = []
if isinstance(releases, dict):
for ver_str, files in releases.items():
# Skip releases whose every artifact is yanked.
if (
isinstance(files, list)
and files
and all(isinstance(f, dict) and f.get("yanked") for f in files)
# Skip releases with no artifacts, or whose every artifact is yanked.
if isinstance(files, list) and (
not files or all(isinstance(f, dict) and f.get("yanked") for f in files)
):
continue
try:
@@ -174,6 +172,10 @@ def _select_latest(data: dict[str, Any], *, allow_pre: bool) -> str | None:
candidates.append(ver)
if candidates:
return str(max(candidates))
if isinstance(releases, dict) and releases:
# Releases are listed but none is installable (all yanked or file-less):
# do not fall back to info.version, which names one of them.
return None
# Fallback to info.version when releases is absent/empty.
info = data.get("info")
+12
View File
@@ -69,6 +69,18 @@ def test_select_latest_skips_fully_yanked():
assert uc._select_latest(data, allow_pre=False) == "0.26.0"
def test_select_latest_skips_release_with_no_files():
data = {"releases": {"1.0.0": [{"yanked": False}], "9.9.9": []}}
assert uc._select_latest(data, allow_pre=False) == "1.0.0"
def test_select_latest_no_fallback_when_every_release_is_unavailable():
data = {"releases": {"9.9.9": []}, "info": {"version": "9.9.9"}}
assert uc._select_latest(data, allow_pre=False) is None
data = {"releases": {"9.9.9": [{"yanked": True}]}, "info": {"version": "9.9.9"}}
assert uc._select_latest(data, allow_pre=False) is None
def test_select_latest_falls_back_to_info_version():
data = {"releases": {}, "info": {"version": "0.26.0"}}
assert uc._select_latest(data, allow_pre=False) == "0.26.0"