Skip to content

Commit d747327

Browse files
StellaHuang95StellaHuang95
authored
Add @vscode/python-environments npm package (#1317)
Our team owns multiple VS Code extensions consuming the Python Environments API. Rather than each extension maintaining its own local copy of the type definitions, which leads to duplication, version drift, and silent breakage, this PR publishes the API as `@vscode/python-environments` on npm, matching the pattern already established by `@vscode/python-extension`. The PR includes following changes: 1. The `pythonEnvironmentsApi` self-contained npm package contains: `src/main.ts`: public API types + PythonEnvironments.api() helper `package.json`, `tsconfig.json`, `.npmignore`, `README.md`, `LICENSE.md`, `SECURITY.md`, basically the same structure as the VS Code Python Extension. 2. The CI pipeline `azure-pipeline.npm.yml` + `test/pack templates`, use `microsoft/vscode-engineering` shared `npm-package` template. Tests on Linux/macOS/Windows. Publish gated behind manual parameter (default: off). Next steps: - Register pipeline in Azure DevOps - Dry-run pipeline (publishPythonEnvsApi: false) and verify everything is working as expected.
1 parent 3fda1e6 commit d747327

File tree

13 files changed

+1580
-1
lines changed

13 files changed

+1580
-1
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ dist
33
node_modules
44
.vscode-test/
55
*.vsix
6+
*.tsbuildinfo
67
.nox/
78
.venv/
89
**/__pycache__/

‎build/azure-pipeline.npm.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: $(Date:yyyyMMdd)$(Rev:.r)
2+
3+
trigger: none
4+
pr: none
5+
6+
resources:
7+
repositories:
8+
- repository: templates
9+
type: github
10+
name: microsoft/vscode-engineering
11+
ref: main
12+
endpoint: Monaco
13+
14+
parameters:
15+
- name: quality
16+
displayName: Quality
17+
type: string
18+
default: latest
19+
values:
20+
- latest
21+
- next
22+
- name: publishPythonEnvsApi
23+
displayName: 🚀 Publish @vscode/python-environments
24+
type: boolean
25+
default: false
26+
27+
extends:
28+
template: azure-pipelines/npm-package/pipeline.yml@templates
29+
parameters:
30+
npmPackages:
31+
- name: pythonEnvironmentsApi
32+
testPlatforms:
33+
- name: Linux
34+
nodeVersions:
35+
- 22.21.1
36+
- name: MacOS
37+
nodeVersions:
38+
- 22.21.1
39+
- name: Windows
40+
nodeVersions:
41+
- 22.21.1
42+
testSteps:
43+
- template: /build/templates/test-steps.yml@self
44+
parameters:
45+
package: pythonEnvironmentsApi
46+
buildSteps:
47+
- template: /build/templates/pack-steps.yml@self
48+
parameters:
49+
package: pythonEnvironmentsApi
50+
ghTagPrefix: release/pythonEnvironmentsApi/
51+
tag: ${{ parameters.quality }}
52+
publishPackage: ${{ parameters.publishPythonEnvsApi }}
53+
workingDirectory: $(Build.SourcesDirectory)/pythonEnvironmentsApi

‎build/templates/pack-steps.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
parameters:
2+
- name: package
3+
4+
steps:
5+
- script: npm install
6+
workingDirectory: $(Build.SourcesDirectory)/${{ parameters.package }}
7+
displayName: Install package dependencies

‎build/templates/test-steps.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
parameters:
2+
- name: package
3+
type: string
4+
- name: script
5+
type: string
6+
default: 'all:publish'
7+
8+
steps:
9+
- script: npm install
10+
workingDirectory: $(Build.SourcesDirectory)/${{ parameters.package }}
11+
displayName: Install package dependencies
12+
- bash: |
13+
/usr/bin/Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
14+
echo ">>> Started xvfb"
15+
displayName: Start xvfb
16+
condition: eq(variables['Agent.OS'], 'Linux')
17+
- script: npm run ${{ parameters.script }}
18+
workingDirectory: $(Build.SourcesDirectory)/${{ parameters.package }}
19+
displayName: Verify package

‎pythonEnvironmentsApi/.npmignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
node_modules/
2+
src/
3+
out/**/*.map
4+
*.tsbuildinfo
5+
tsconfig*.json

‎pythonEnvironmentsApi/LICENSE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Copyright (c) Microsoft Corporation. All rights reserved.
2+
3+
MIT License
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED _AS IS_, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎pythonEnvironmentsApi/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# @vscode/python-environments
2+
3+
This package provides type declarations and a helper to access the API exposed by the [Python Environments](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-python-envs) extension for VS Code.
4+
5+
## Usage
6+
7+
1. Install the package and add an `extensionDependencies` entry in your extension's `package.json`:
8+
9+
```jsonc
10+
// package.json
11+
{
12+
"extensionDependencies": ["ms-python.vscode-python-envs"]
13+
}
14+
```
15+
16+
2. Install the npm package:
17+
18+
```
19+
npm install @vscode/python-environments
20+
```
21+
22+
3. Import and use the API in your extension:
23+
24+
```typescript
25+
import { PythonEnvironments } from '@vscode/python-environments';
26+
27+
export async function activate() {
28+
const api = await PythonEnvironments.api();
29+
30+
// Get all discovered environments
31+
const envs = await api.getEnvironments('all');
32+
for (const env of envs) {
33+
console.log(env.displayName, env.version);
34+
}
35+
}
36+
```
37+

‎pythonEnvironmentsApi/SECURITY.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<!-- BEGIN MICROSOFT SECURITY.MD V0.0.3 BLOCK -->
2+
3+
## Security
4+
5+
Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
6+
7+
If you believe you have found a security vulnerability in any Microsoft-owned repository that meets Microsoft's [Microsoft's definition of a security vulnerability](<https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)>) of a security vulnerability, please report it to us as described below.
8+
9+
## Reporting Security Issues
10+
11+
**Please do not report security vulnerabilities through public GitHub issues.**
12+
13+
Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report).
14+
15+
If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc).
16+
17+
You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc).
18+
19+
Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
20+
21+
- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
22+
- Full paths of source file(s) related to the manifestation of the issue
23+
- The location of the affected source code (tag/branch/commit or direct URL)
24+
- Any special configuration required to reproduce the issue
25+
- Step-by-step instructions to reproduce the issue
26+
- Proof-of-concept or exploit code (if possible)
27+
- Impact of the issue, including how an attacker might exploit the issue
28+
29+
This information will help us triage your report more quickly.
30+
31+
If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://microsoft.com/msrc/bounty) page for more details about our active programs.
32+
33+
## Preferred Languages
34+
35+
We prefer all communications to be in English.
36+
37+
## Policy
38+
39+
Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd).
40+
41+
<!-- END MICROSOFT SECURITY.MD BLOCK -->

‎pythonEnvironmentsApi/package-lock.json‎

Lines changed: 42 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pythonEnvironmentsApi/package.json‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
{
2+
"name": "@vscode/python-environments",
3+
"description": "An API facade for the Python Environments extension in VS Code",
4+
"version": "1.0.0",
5+
"author": {
6+
"name": "Microsoft Corporation"
7+
},
8+
"keywords": [
9+
"Python",
10+
"VSCode",
11+
"API",
12+
"Environments"
13+
],
14+
"main": "./out/main.js",
15+
"types": "./out/main.d.ts",
16+
"engines": {
17+
"node": ">=22.21.1",
18+
"vscode": "^1.110.0"
19+
},
20+
"license": "MIT",
21+
"homepage": "https://github.com/microsoft/vscode-python-environments/tree/main/pythonEnvironmentsApi",
22+
"repository": {
23+
"type": "git",
24+
"url": "https://github.com/microsoft/vscode-python-environments"
25+
},
26+
"bugs": {
27+
"url": "https://github.com/microsoft/vscode-python-environments/issues"
28+
},
29+
"scripts": {
30+
"prepublishOnly": "echo \"⛔ Can only publish from a secure pipeline ⛔\" && node -e \"process.exitCode = 1\"",
31+
"prepack": "npm run all:publish",
32+
"all:publish": "git clean -xfd . && npm install && npm run compile",
33+
"compile": "tsc -b ./tsconfig.json",
34+
"clean": "node -e \"const fs = require('fs'); fs.rmSync('./out', { recursive: true, force: true });\""
35+
},
36+
"devDependencies": {
37+
"@types/vscode": "^1.99.0",
38+
"typescript": "^5.1.3"
39+
}
40+
}

0 commit comments

Comments
 (0)