Repository navigation
Description
🤖 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.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 atuv tool install rsconnect-python. - 1.34.0: require Python 3.11+ for the CLI Python. Remove the compatibility code and conditional pins, drop the
typing-extensionsdependency, 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
- 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 --upgradedoesn't move me forward. - 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. - 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.
- As a user on a supported interpreter, I want the existing upgrade hint unchanged, so that nothing about my experience regresses.
- 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. - 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.
- 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.
- 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.
- As a user on Python 3.11+, I want to install and run rsconnect-python 1.34.0 with fewer dependencies (no
toml, notyping-extensions), so that my environment is leaner. - 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.
- As a user, I want the manifest to record the content Python's version, not the CLI Python's, when I pass
--pythonor use a project environment, so that Connect builds the right runtime. - As a user, I want
requirements.txtgenerated from the content Python's packages even when that interpreter is older than the CLI Python, so that Connect restores the right dependencies. - As a user reading the README, I want
uv tool installpresented 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. - 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".
- 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.
- As a maintainer, I want the compatibility branches gone, so that the code has one path per behaviour.
- 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.
- 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.
- 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.
- As a maintainer, I want
AGENTS.mdto state the new floor and stop recommendingtyping_extensions, so that agents don't reintroduce compatibility code. - 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.versionandinfo.requires_pythonfrom the PyPI project JSON it already fetches. No new requests. - The on-disk cache stores
requires_pythonalongside the latest version. A cache entry withoutrequires_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 unparseablerequires_pythoncounts 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, anduv tool install rsconnect-pythonas 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 withuv 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
mainand contains only this fix (there have been no commits onmainsince 1.33.1). CHANGELOG: "Fixed" entry.
1.34.0: require Python 3.11+
- Packaging:
requires-python = ">=3.11". Remove thetomldependency, collapse thepyjwtandsnowflake-climarker pairs to their>=3.10arms (pyjwt>=2.15.0,snowflake-cli>=3.23.0), and droptyping-extensions. Regenerate the lockfile. - Code: remove every
sys.version_infocompatibility branch. Usetomllibdirectly in both the pyproject reader and the environment inspector. ImportNotRequired,Never,ParamSpec,ConcatenateandTypedDictfromtyping. - 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
justfileversion 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 installfirst 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--pythonor 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 thetyping_extensionsguidance.- 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
deploycommand through Click'sCliRunner, with the config directory pointed at a temporary directory so the real cache is used and PyPI's JSON faked withhttpretty. Cases: latest is compatible → existing hint. Latest excludes the running interpreter → notice, and nopip install --upgradehint. A legacy cache withoutrequires_python→ no crash, and a refresh happens.RSCONNECT_DISABLE_VERSION_CHECK→ no output. Already up to date → no output. Prior art:TestCLIIntegrationin 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>throughCliRunner, and assert the manifest's Python version matches the content Python,package_manageris set, andrequirements.txtcontains 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 apitests 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
UPrules attarget-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-versionsjob 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 --upgradewill resolve them to 1.33.2, which carries the fix.
Activity
docs: add Python support policy ADR and glossary (#954)