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).
Need: API consumers calling
getPackageAvailableVersionscannot 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 toundefined, 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:
PackageVersionLookupNotSupportedError(with a stablecodediscriminator) plus anisPackageVersionLookupNotSupportedErrortype guard that works across extension bundle boundaries (whereinstanceofis unreliable).PythonPackageGetterApi.getPackageAvailableVersionsso that:undefined.Acceptance Criteria:
PackageVersionLookupNotSupportedErrorandisPackageVersionLookupNotSupportedErrorare exported from the public API (src/api.ts) and the@vscode/python-environmentspackage.codeeven when the error object was created by a different bundle copy of the class.PackageVersionLookupNotSupportedError.undefined).3.13.14.final.0) resolve correctly for Pip's--python-versionflag.3.13.14.final.0version string.Follow-up to #1717 (which added the internal-only error and cross-platform integration coverage).