Skip to content

Spec: Drop support for EOL Python (require 3.11+) #944

Open
3 of 6 issues completed
Open

Description

@tdstein

🤖 Spec for #942. Policy recorded in ADR-0001 (docs/adr/0001-support-only-non-eol-python.md). Terms follow GLOSSARY.md: the CLI Python runs rsconnect-python; the content Python is what the deployed content targets.

Problem Statement

rsconnect-python still requires only Python 3.8+, so maintainers carry compatibility code (a toml fallback, typing_extensions imports, sys.version_info branches, marker-conditional dependency pins) and a CI matrix for interpreters that have all reached end-of-life (3.8, 3.9, 3.10). Since #920, the CLI Python no longer has to match the content Python: the CLI can be installed with uv tool install and only shells out to the content Python for its version and installed packages. Nothing requires the CLI itself to run on EOL Python anymore.

Dropping old interpreters has to be done without stranding users. Anyone left on an EOL interpreter will resolve to the last compatible release, but today's upgrade check compares only against PyPI's latest version and ignores requires_python, so it would keep telling them to upgrade to a release they cannot install.

Solution

Ship in two releases:

  1. 1.33.2 (last release supporting Python 3.8+): the deploy-time upgrade check becomes aware of requires_python. When the latest release on PyPI can't run on the user's interpreter, it replaces the upgrade hint with a notice that explains why and points at uv tool install rsconnect-python.
  2. 1.34.0: require Python 3.11+ for the CLI Python. Remove the compatibility code and conditional pins, drop the typing-extensions dependency, update CI, and update our docs to stop implying the CLI must live in the content Python's environment. Add a test array proving a 3.11 CLI Python can still write manifests for every content Python that uv provides (3.8 → current).

Users deploying content that targets old Python versions are unaffected: the content Python can still be any interpreter, on a best-effort basis.

User Stories

  1. As a user on Python 3.9 running rsconnect-python 1.33.2, I want the deploy-time version check to tell me that a newer release exists but requires Python >=3.11, so that I understand why pip install --upgrade doesn't move me forward.
  2. As a user on an EOL interpreter, I want the notice to suggest uv tool install rsconnect-python, so that I learn how to run a current CLI without changing my project's Python.
  3. As a user on an EOL interpreter, I want the plain "upgrade available" hint suppressed when the latest release excludes my interpreter, so that I'm not told to run a command that won't work.
  4. As a user on a supported interpreter, I want the existing upgrade hint unchanged, so that nothing about my experience regresses.
  5. As a user who set RSCONNECT_DISABLE_VERSION_CHECK, I want neither the hint nor the new notice to appear, so that my opt-out still holds.
  6. As a user upgrading from 1.33.1, I want a version-check cache written by the older release to be handled gracefully, so that I don't get a crash or a stale, wrong hint.
  7. As a user, I want the new notice to follow the same rules as the existing hint (deploy commands only, written to stderr, at most one PyPI request per day, printed even when the deploy fails), so that it is no noisier than today.
  8. As a user on Python 3.8–3.10 installing with pip or uv, I want resolution to land on 1.33.2 automatically, so that my installation keeps working without pinning.
  9. As a user on Python 3.11+, I want to install and run rsconnect-python 1.34.0 with fewer dependencies (no toml, no typing-extensions), so that my environment is leaner.
  10. As a user whose CLI Python is 3.11+, I want to deploy content whose content Python is 3.8, 3.9 or 3.10, so that I can keep publishing older projects.
  11. As a user, I want the manifest to record the content Python's version, not the CLI Python's, when I pass --python or use a project environment, so that Connect builds the right runtime.
  12. As a user, I want requirements.txt generated from the content Python's packages even when that interpreter is older than the CLI Python, so that Connect restores the right dependencies.
  13. As a user reading the README, I want uv tool install presented as the recommended install, and the "into your project" option to state that it requires the project to use Python 3.11+, so that I pick an install method that works.
  14. As a user reading the deployment docs, I want them to explain that the CLI Python and the content Python can differ and how rsconnect-python selects the content Python, so that I'm not misled by "use the same Python that you use to run your code".
  15. As a user reading the CHANGELOG, I want a "Removed" entry for Python 3.8–3.10 support in 1.34.0 and a "Fixed" entry for the version check in 1.33.2, so that the change is clearly announced.
  16. As a maintainer, I want the compatibility branches gone, so that the code has one path per behaviour.
  17. As a maintainer, I want the CI matrix to cover only supported CLI Pythons (3.11–current), so that CI time goes to versions we ship for.
  18. As a maintainer, I want a CI job that fails if any content Python in the test array is unavailable, so that the array can't silently skip its way to green.
  19. As a maintainer, I want the content Python array derived from what uv can provide, so that new Python releases join it without edits and versions uv drops leave it without an ADR change.
  20. As a maintainer, I want AGENTS.md to state the new floor and stop recommending typing_extensions, so that agents don't reintroduce compatibility code.
  21. As a maintainer of a downstream package that imports rsconnect-python (posit-cli), I want an issue opened when 1.34.0 is ready, so that I can raise my own floor deliberately.

Implementation Decisions

1.33.2: version check aware of requires_python

  • The version-check module reads both info.version and info.requires_python from the PyPI project JSON it already fetches. No new requests.
  • The on-disk cache stores requires_python alongside the latest version. A cache entry without requires_python (written by an earlier release) is treated as stale: it triggers the normal refresh, and in the meantime is treated as compatible so behaviour matches today.
  • Compatibility is evaluated with packaging's specifier set against the running interpreter's version. A missing or unparseable requires_python counts as compatible.
  • If the latest version is newer and compatible: the existing upgrade hint, unchanged.
  • If the latest version is newer and incompatible: a notice replaces the hint, naming the latest version, its requires_python, the running interpreter's version, and uv tool install rsconnect-python as the way to get it. For example: "rsconnect-python 1.34.0 requires Python >=3.11 (you are running 3.9.18). Install it in its own environment with uv tool install rsconnect-python."
  • All existing gating stays: deploy commands only, stderr, RSCONNECT_DISABLE_VERSION_CHECK, dev versions skipped, 24-hour TTL, background refresh, a short blocking wait on a cold cache.
  • 1.33.2 is cut from main and contains only this fix (there have been no commits on main since 1.33.1). CHANGELOG: "Fixed" entry.

1.34.0: require Python 3.11+

  • Packaging: requires-python = ">=3.11". Remove the toml dependency, collapse the pyjwt and snowflake-cli marker pairs to their >=3.10 arms (pyjwt>=2.15.0, snowflake-cli>=3.23.0), and drop typing-extensions. Regenerate the lockfile.
  • Code: remove every sys.version_info compatibility branch. Use tomllib directly in both the pyproject reader and the environment inspector. Import NotRequired, Never, ParamSpec, Concatenate and TypedDict from typing.
  • The environment inspector keeps running under the CLI Python and only shells out to the content Python (version probe, pip/uv pip freeze). That contract is what makes the drop safe and must not change.
  • CI: the test matrix becomes 3.11–current. The coverage step moves off 3.8 to 3.11. The justfile version list matches. Add a dedicated job that runs the content Python array with a 3.11 CLI Python, installs every content Python uv offers, and fails on any skip.
  • Docs: the README keeps uv tool install first and changes "into your project" to say it requires the project's Python to be 3.11+. The deployment docs explain that the CLI Python and the content Python can differ, that --python or a project environment selects the content Python, and that the CLI Python is only a fallback. Reword "use the same Python that you use to run your code" so it refers to the content Python, not the interpreter running rsconnect.
  • AGENTS.md: "Support Python 3.11+ (see ADR-0001)". Remove the typing_extensions guidance.
  • CHANGELOG: "Removed" entry for Python 3.8, 3.9 and 3.10 as CLI Pythons, noting that content can still target them and that 1.33.2 is the last compatible release.
  • After release: open an issue on posit-dev/posit-cli suggesting it raise its floor. This does not block the release.

Testing Decisions

Good tests here exercise the CLI from the outside: invoke a command and assert what the user sees (stderr) or what the command writes (manifest, requirements.txt). They don't patch private helpers of the module under test.

  • Version check (1.33.2): invoke a deploy command through Click's CliRunner, with the config directory pointed at a temporary directory so the real cache is used and PyPI's JSON faked with httpretty. Cases: latest is compatible → existing hint. Latest excludes the running interpreter → notice, and no pip install --upgrade hint. A legacy cache without requires_python → no crash, and a refresh happens. RSCONNECT_DISABLE_VERSION_CHECK → no output. Already up to date → no output. Prior art: TestCLIIntegration in the version-check tests, which uses the same deploy no-op commands but patches internals. The new tests should fake at the network boundary instead.
  • Content Python array (1.34.0): parametrize over every content Python uv can provide (3.8 → current). For each version, locate the interpreter, create a minimal API project with one installed package in a virtual environment for that interpreter, run rsconnect write-manifest api <dir> --python <interpreter> through CliRunner, and assert the manifest's Python version matches the content Python, package_manager is set, and requirements.txt contains the pinned package. Skip a version that isn't available locally. In the dedicated CI job, a flag turns skips into failures. Prior art: write-manifest api tests in the main CLI tests (including --override-python-version), and the environment tests that pass explicit interpreters.
  • No bundle building in the array: bundling runs entirely under the CLI Python and doesn't depend on the content Python.
  • No dedicated test for the 3.11 floor: the CI matrix and the locked-lockfile check cover it.

Out of Scope

  • Posit Connect's own publishing guide (handled separately by the maintainer).
  • Syntax modernization (ruff UP rules at target-version = py311, X | None, builtin generics). This goes in a separate follow-up issue.
  • Python 3.7 or older as a content Python in tests (uv can't provide them; support is best-effort per ADR-0001).
  • Live deployments to Connect across content Pythons. The existing test-connect-versions job keeps running with a 3.13 CLI Python.
  • Changes to posit-cli or vetiver.

Further Notes

  • Follows ADR-0001: the CLI supports only non-EOL Python, each version is dropped in the next minor release after its EOL, and old content Python support is best-effort.
  • Precedent: Python 3.5/3.6 were dropped in 1.14.0 and 3.7 in 1.23.0, both as minor releases with a "Removed" CHANGELOG entry.
  • Users on 1.33.1 or older will still see the old hint pointing at 1.34.0. pip install --upgrade will resolve them to 1.33.2, which carries the fix.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified, ready for an autonomous coding agent

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions