feat: add getPackageAvailableVersions to public API and bump API to 1.1.0 by edvilme · Pull Request #1682 · microsoft/vscode-python-environments

Eduardo Villalpando Mello (edvilme) · 2026-07-30T17:51:05Z

Summary

add PythonPackageGetterApi.getPackageAvailableVersions to the public API so consumers can query a package's available versions
bump @vscode/python-environments from 1.0.0 to 1.1.0
synchronize both API lockfile version fields
document the public API changes since the latest npm release

API changes

add PythonPackageGetterApi.getPackageAvailableVersions(environment, packageName): Promise<Pep440Version[] | undefined> — exposes a package's available versions (newest-first) to API consumers, delegating to the environment's package manager and resolving to undefined when version listing is unsupported
re-export Pep440Version for package manager version APIs
add PackageInfo.isTransitive and GetPackagesOptions.skipCache
add optional package manager hooks for watch targets, direct dependencies, tool versions, available package versions, and install-spec formatting
add the optional GetPackagesOptions parameter to PackageManager.getPackages and PythonPackageGetterApi.getPackages
update PackageManager.refresh and PythonPackageGetterApi.refreshPackages to return the refreshed package list when available

Validation

npm run lint
npm run compile-tests
npm run unittest (1494 passing, 5 pending)
git diff --check

Add PythonPackageGetterApi.getPackageAvailableVersions so API consumers can query a package's available versions (newest-first), delegating to the environment's package manager and resolving to undefined when unsupported. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3f16397e-0917-4efb-8d75-566c71ebf9ba

Eduardo Villalpando Mello (edvilme) · 2026-07-31T22:26:31Z

Adding "skip tests" label since this functionality already exists but is now being exposed to the public API

Eleanor Boyd (eleanorjboyd) · 2026-08-04T17:30:02Z

+### Changed
+
+- Added the optional `options?: GetPackagesOptions` parameter to `PackageManager.getPackages(environment, options?)` and `PythonPackageGetterApi.getPackages(environment, options?)`. Consumers can set `options.skipCache` to request fresh package data.
+- Changed `PackageManager.refresh(environment)` from `Promise<void>` to `Promise<Package[] | undefined>`, allowing implementations to return the refreshed package list.


this is a big change here- we would need to go to 2.0 if we want to change the return value of this method. Any other ways we could maybe do that?

I can look into having it return nothing for now, and then maybe discuss later on when reviewing the API

Eleanor Boyd (eleanorjboyd) · 2026-08-04T17:31:04Z

 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [1.1.0]


The published 1.0 package has top-level main and types; api/package.json now has only conditional exports. This accumulated unpublished change is not mentioned in the changelog.

preserve top-level main and types alongside exports, and test packed ESM and legacy CommonJS consumers.

The api file and types are generated inline by the pipelines (#1619). I can update the changelog to mention that as well

Eleanor Boyd (eleanorjboyd) · 2026-08-04T17:31:51Z

+- Added the optional `options?: GetPackagesOptions` parameter to `PackageManager.getPackages(environment, options?)` and `PythonPackageGetterApi.getPackages(environment, options?)`. Consumers can set `options.skipCache` to request fresh package data.
+- Changed `PackageManager.refresh(environment)` from `Promise<void>` to `Promise<Package[] | undefined>`, allowing implementations to return the refreshed package list.
+- Changed `PythonPackageGetterApi.refreshPackages(environment)` from `Promise<void>` to `Promise<Package[] | undefined>`, exposing the refreshed package list to API consumers.
+


would also want to packed-package contract tests before publishing

Eleanor Boyd (eleanorjboyd)

see two items about refresh and the exported top level items

Stella Huang (StellaHuang95) · 2026-08-06T22:05:51Z

🔒 Automated review in progress — Stella Huang (@StellaHuang95) is auto-reviewing this PR.

Stella Huang (StellaHuang95) · 2026-08-06T22:20:32Z

    "name": "@vscode/python-environments",
    "description": "An API facade for the Python Environments extension in VS Code",
-    "version": "1.0.0",
+    "version": "1.1.0",


Warning · Non-blocking recommendation

Please confirm the published npm version history before releasing 1.1.0. The changelog contains a 1.37.0 entry, so publishing 1.1.0 would be a downgrade if 1.37.0 was ever published; reconcile the changelog or select a version above the published latest.

Stella Huang (StellaHuang95) · 2026-08-06T22:20:34Z

+
+- Added the optional `options?: GetPackagesOptions` parameter to `PackageManager.getPackages(environment, options?)` and `PythonPackageGetterApi.getPackages(environment, options?)`. Consumers can set `options.skipCache` to request fresh package data.
+- Changed `PackageManager.refresh(environment)` from `Promise<void>` to `Promise<Package[] | undefined>`, allowing implementations to return the refreshed package list.
+- Changed `PythonPackageGetterApi.refreshPackages(environment)` from `Promise<void>` to `Promise<Package[] | undefined>`, exposing the refreshed package list to API consumers.


Warning · Non-blocking recommendation

Changing PackageManager.refresh from Promise<void> to Promise<Package[] | undefined> breaks external PackageManager implementations that return Promise<void>. Please confirm that external implementations are unsupported or document why this implementer-facing breaking change is appropriate for a minor release.

Stella Huang (StellaHuang95) · 2026-08-06T22:20:37Z

@@ -319,6 +320,17 @@ export class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
        }


Warning · Non-blocking recommendation

Please add coverage for both manager behaviors: returning available versions when supported and resolving undefined when the underlying manager omits the optional hook. The latter relies on the internal wrapper's guard and is the documented fallback contract for this new public method.

Stella Huang (StellaHuang95)

Approved via Review Center.

Eduardo Villalpando Mello (edvilme) added the debt Code quality issues label Jul 30, 2026

chore: bump API package version to 1.1.0

540d41d

Eduardo Villalpando Mello (edvilme) force-pushed the api-version-bump branch from 4f563d7 to 540d41d Compare July 30, 2026 18:01

Eduardo Villalpando Mello (edvilme) changed the title ~~chore: bump API package version to 2.0.0~~ chore: bump API package version to 1.1.0 Jul 30, 2026

Merge branch 'main' into api-version-bump

7c33fa6

Eduardo Villalpando Mello (edvilme) enabled auto-merge (squash) July 31, 2026 21:59

Eduardo Villalpando Mello (edvilme) disabled auto-merge July 31, 2026 22:15

Eduardo Villalpando Mello (edvilme) changed the title ~~chore: bump API package version to 1.1.0~~ feat: add getPackageAvailableVersions to public API and bump API to 1.1.0 Jul 31, 2026

Eduardo Villalpando Mello (edvilme) added the skip tests label Jul 31, 2026

Stella Huang (StellaHuang95) approved these changes Jul 31, 2026

View reviewed changes

Eduardo Villalpando Mello (edvilme) enabled auto-merge (squash) August 3, 2026 16:58

Eduardo Villalpando Mello (edvilme) requested a review from Eleanor Boyd (eleanorjboyd) August 4, 2026 17:04

Eleanor Boyd (eleanorjboyd) reviewed Aug 4, 2026

View reviewed changes

Eleanor Boyd (eleanorjboyd) requested changes Aug 4, 2026

View reviewed changes

Stella Huang (StellaHuang95) reviewed Aug 6, 2026

View reviewed changes

Stella Huang (StellaHuang95) approved these changes Aug 6, 2026

View reviewed changes

Stella Huang (StellaHuang95) added the review-auto:approved Automated review: no blocking findings (approval posted). label Aug 6, 2026

Navigation Menu

Uh oh!

feat: add getPackageAvailableVersions to public API and bump API to 1.1.0 - #1682

feat: add getPackageAvailableVersions to public API and bump API to 1.1.0#1682
Eduardo Villalpando Mello (edvilme) wants to merge 3 commits into
mainfrom
api-version-bump

Eduardo Villalpando Mello (edvilme) commented Jul 30, 2026 •

edited

Loading

Uh oh!

Eduardo Villalpando Mello (edvilme) commented Jul 31, 2026

Uh oh!

Eleanor Boyd (eleanorjboyd) Aug 4, 2026

Uh oh!

Eduardo Villalpando Mello (edvilme) Aug 5, 2026

Uh oh!

Eleanor Boyd (eleanorjboyd) Aug 4, 2026

Uh oh!

Eleanor Boyd (eleanorjboyd) Aug 4, 2026

Uh oh!

Eduardo Villalpando Mello (edvilme) Aug 5, 2026

Uh oh!

Eleanor Boyd (eleanorjboyd) Aug 4, 2026

Uh oh!

Eleanor Boyd (eleanorjboyd) left a comment

Uh oh!

Stella Huang (StellaHuang95) commented Aug 6, 2026

Uh oh!

Stella Huang (StellaHuang95) Aug 6, 2026

Uh oh!

Stella Huang (StellaHuang95) Aug 6, 2026

Uh oh!

Stella Huang (StellaHuang95) Aug 6, 2026

Uh oh!

Stella Huang (StellaHuang95) left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -319,6 +320,17 @@ export class PythonEnvironmentApiImpl implements PythonEnvironmentApi {
		}

Uh oh!

Conversation

Eduardo Villalpando Mello (edvilme) commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

API changes

Validation

Uh oh!

Eduardo Villalpando Mello (edvilme) commented Jul 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Eleanor Boyd (eleanorjboyd) left a comment

Choose a reason for hiding this comment

Uh oh!

Stella Huang (StellaHuang95) commented Aug 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Stella Huang (StellaHuang95) left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Eduardo Villalpando Mello (edvilme) commented Jul 30, 2026 •

edited

Loading