Skip to content

Public typed error for unsupported package version lookup #1727

Description

Need: API consumers calling getPackageAvailableVersions cannot tell the difference between a package manager that genuinely does not support version lookup (an unsupported capability) and an operational failure (a failed command, network error, malformed output, or parsing miss). Today both cases collapse to undefined, so consumers cannot decide whether to fall back to manual version entry or surface a real error. The reference work in #1717 introduced this distinction only as an internal error; it should be part of the public API contract so downstream extensions can react to it reliably across bundle boundaries.

Proposal:

  • Add a public, exported PackageVersionLookupNotSupportedError (with a stable code discriminator) plus an isPackageVersionLookupNotSupportedError type guard that works across extension bundle boundaries (where instanceof is unreliable).
  • Update PythonPackageGetterApi.getPackageAvailableVersions so that:
    • Unsupported capability (default/missing manager, Poetry, Pip older than 21.2) rejects with the typed error.
    • Operational failures (Pip/Conda command, network, malformed-output, parsing) propagate as their original errors instead of becoming undefined.
  • Bump the public API package version and document the change in the API changelog.
  • Update consumers so that only the typed unsupported error triggers the manual version-entry fallback; all other errors propagate for normal handling.

Acceptance Criteria:

  • PackageVersionLookupNotSupportedError and isPackageVersionLookupNotSupportedError are exported from the public API (src/api.ts) and the @vscode/python-environments package.
  • The type guard recognizes the error via its stable code even when the error object was created by a different bundle copy of the class.
  • Default adapter (no/missing manager), Poetry, and Pip < 21.2 reject with PackageVersionLookupNotSupportedError.
  • Pip/Conda command, network, malformed-output, and parsing failures reject with their original errors (not undefined).
  • Interpreter version strings with release-level/serial suffixes (e.g. 3.13.14.final.0) resolve correctly for Pip's --python-version flag.
  • The "Manage Package Version" UI falls back to manual entry only on the typed unsupported error; other errors propagate.
  • The public API package version is bumped and the API changelog documents the new error, type guard, and refined contract.
  • Focused unit tests cover the default adapter, Poetry, old Pip, supported-Pip command failures, Conda failures, cross-bundle recognition, and the 3.13.14.final.0 version string.

Follow-up to #1717 (which added the internal-only error and cross-platform integration coverage).

Metadata

Metadata

Labels

feature-requestRequest for new features or functionality

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions