Skip to content
Navigation Menu
{{ message }}
forked from microsoft/vscode-python
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathmain.ts
More file actions
348 lines (326 loc) · 13 KB
/
Copy pathmain.ts
File metadata and controls
348 lines (326 loc) · 13 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
import { CancellationToken, Event, Uri, WorkspaceFolder, extensions } from 'vscode';
/*
* Do not introduce any breaking changes to this API.
* This is the public API for other extensions to interact with this extension.
*/
export interface PythonExtension {
/**
* Promise indicating whether all parts of the extension have completed loading or not.
*/
ready: Promise<void>;
debug: {
/**
* Generate an array of strings for commands to pass to the Python executable to launch the debugger for remote debugging.
* Users can append another array of strings of what they want to execute along with relevant arguments to Python.
* E.g `['/Users/..../pythonVSCode/python_files/lib/python/debugpy', '--listen', 'localhost:57039', '--wait-for-client']`
* @param host
* @param port
* @param waitUntilDebuggerAttaches Defaults to `true`.
*/
getRemoteLauncherCommand(host: string, port: number, waitUntilDebuggerAttaches: boolean): Promise<string[]>;
/**
* Gets the path to the debugger package used by the extension.
*/
getDebuggerPackagePath(): Promise<string | undefined>;
};
/**
* These APIs provide a way for extensions to work with by python environments available in the user's machine
* as found by the Python extension. See
* https://github.com/microsoft/vscode-python/wiki/Python-Environment-APIs for usage examples and more.
*/
readonly environments: {
/**
* Returns the environment configured by user in settings. Note that this can be an invalid environment, use
* {@link resolveEnvironment} to get full details.
* @param resource : Uri of a file or workspace folder. This is used to determine the env in a multi-root
* scenario. If `undefined`, then the API returns what ever is set for the workspace.
*/
getActiveEnvironmentPath(resource?: Resource): EnvironmentPath;
/**
* Sets the active environment path for the python extension for the resource. Configuration target will always
* be the workspace folder.
* @param environment : If string, it represents the full path to environment folder or python executable
* for the environment. Otherwise it can be {@link Environment} or {@link EnvironmentPath} itself.
* @param resource : [optional] File or workspace to scope to a particular workspace folder.
*/
updateActiveEnvironmentPath(
environment: string | EnvironmentPath | Environment,
resource?: Resource,
): Promise<void>;
/**
* This event is triggered when the active environment setting changes.
*/
readonly onDidChangeActiveEnvironmentPath: Event<ActiveEnvironmentPathChangeEvent>;
/**
* Carries environments known to the extension at the time of fetching the property. Note this may not
* contain all environments in the system as a refresh might be going on.
*
* Only reports environments in the current workspace.
*/
readonly known: readonly Environment[];
/**
* This event is triggered when the known environment list changes, like when a environment
* is found, existing environment is removed, or some details changed on an environment.
*/
readonly onDidChangeEnvironments: Event<EnvironmentsChangeEvent>;
/**
* This API will trigger environment discovery, but only if it has not already happened in this VSCode session.
* Useful for making sure env list is up-to-date when the caller needs it for the first time.
*
* To force trigger a refresh regardless of whether a refresh was already triggered, see option
* {@link RefreshOptions.forceRefresh}.
*
* Note that if there is a refresh already going on then this returns the promise for that refresh.
* @param options Additional options for refresh.
* @param token A cancellation token that indicates a refresh is no longer needed.
*/
refreshEnvironments(options?: RefreshOptions, token?: CancellationToken): Promise<void>;
/**
* Returns details for the given environment, or `undefined` if the env is invalid.
* @param environment : If string, it represents the full path to environment folder or python executable
* for the environment. Otherwise it can be {@link Environment} or {@link EnvironmentPath} itself.
*/
resolveEnvironment(
environment: Environment | EnvironmentPath | string,
): Promise<ResolvedEnvironment | undefined>;
/**
* Returns the environment variables used by the extension for a resource, which includes the custom
* variables configured by user in `.env` files.
* @param resource : Uri of a file or workspace folder. This is used to determine the env in a multi-root
* scenario. If `undefined`, then the API returns what ever is set for the workspace.
*/
getEnvironmentVariables(resource?: Resource): EnvironmentVariables;
/**
* This event is fired when the environment variables for a resource change. Note it's currently not
* possible to detect if environment variables in the system change, so this only fires if custom
* environment variables are updated in `.env` files.
*/
readonly onDidEnvironmentVariablesChange: Event<EnvironmentVariablesChangeEvent>;
};
}
export type RefreshOptions = {
/**
* When `true`, force trigger a refresh regardless of whether a refresh was already triggered. Note this can be expensive so
* it's best to only use it if user manually triggers a refresh.
*/
forceRefresh?: boolean;
};
/**
* Details about the environment. Note the environment folder, type and name never changes over time.
*/
export type Environment = EnvironmentPath & {
/**
* Carries details about python executable.
*/
readonly executable: {
/**
* Uri of the python interpreter/executable. Carries `undefined` in case an executable does not belong to
* the environment.
*/
readonly uri: Uri | undefined;
/**
* Bitness if known at this moment.
*/
readonly bitness: Bitness | undefined;
/**
* Value of `sys.prefix` in sys module if known at this moment.
*/
readonly sysPrefix: string | undefined;
};
/**
* Carries details if it is an environment, otherwise `undefined` in case of global interpreters and others.
*/
readonly environment:
| {
/**
* Type of the environment.
*/
readonly type: EnvironmentType;
/**
* Name to the environment if any.
*/
readonly name: string | undefined;
/**
* Uri of the environment folder.
*/
readonly folderUri: Uri;
/**
* Any specific workspace folder this environment is created for.
*/
readonly workspaceFolder: WorkspaceFolder | undefined;
}
| undefined;
/**
* Carries Python version information known at this moment, carries `undefined` for envs without python.
*/
readonly version:
| (VersionInfo & {
/**
* Value of `sys.version` in sys module if known at this moment.
*/
readonly sysVersion: string | undefined;
})
| undefined;
/**
* Tools/plugins which created the environment or where it came from. First value in array corresponds
* to the primary tool which manages the environment, which never changes over time.
*
* Array is empty if no tool is responsible for creating/managing the environment. Usually the case for
* global interpreters.
*/
readonly tools: readonly EnvironmentTools[];
};
/**
* Derived form of {@link Environment} where certain properties can no longer be `undefined`. Meant to represent an
* {@link Environment} with complete information.
*/
export type ResolvedEnvironment = Environment & {
/**
* Carries complete details about python executable.
*/
readonly executable: {
/**
* Uri of the python interpreter/executable. Carries `undefined` in case an executable does not belong to
* the environment.
*/
readonly uri: Uri | undefined;
/**
* Bitness of the environment.
*/
readonly bitness: Bitness;
/**
* Value of `sys.prefix` in sys module.
*/
readonly sysPrefix: string;
};
/**
* Carries complete Python version information, carries `undefined` for envs without python.
*/
readonly version:
| (ResolvedVersionInfo & {
/**
* Value of `sys.version` in sys module if known at this moment.
*/
readonly sysVersion: string;
})
| undefined;
};
export type EnvironmentsChangeEvent = {
readonly env: Environment;
/**
* * "add": New environment is added.
* * "remove": Existing environment in the list is removed.
* * "update": New information found about existing environment.
*/
readonly type: 'add' | 'remove' | 'update';
};
export type ActiveEnvironmentPathChangeEvent = EnvironmentPath & {
/**
* Workspace folder the environment changed for.
*/
readonly resource: WorkspaceFolder | undefined;
};
/**
* Uri of a file inside a workspace or workspace folder itself.
*/
export type Resource = Uri | WorkspaceFolder;
export type EnvironmentPath = {
/**
* The ID of the environment.
*/
readonly id: string;
/**
* Path to environment folder or path to python executable that uniquely identifies an environment. Environments
* lacking a python executable are identified by environment folder paths, whereas other envs can be identified
* using python executable path.
*/
readonly path: string;
};
/**
* Tool/plugin where the environment came from. It can be {@link KnownEnvironmentTools} or custom string which
* was contributed.
*/
export type EnvironmentTools = KnownEnvironmentTools | string;
/**
* Tools or plugins the Python extension currently has built-in support for. Note this list is expected to shrink
* once tools have their own separate extensions.
*/
export type KnownEnvironmentTools =
| 'Conda'
| 'Pipenv'
| 'Poetry'
| 'VirtualEnv'
| 'Venv'
| 'VirtualEnvWrapper'
| 'Pyenv'
| 'Unknown';
/**
* Type of the environment. It can be {@link KnownEnvironmentTypes} or custom string which was contributed.
*/
export type EnvironmentType = KnownEnvironmentTypes | string;
/**
* Environment types the Python extension is aware of. Note this list is expected to shrink once tools have their
* own separate extensions, in which case they're expected to provide the type themselves.
*/
export type KnownEnvironmentTypes = 'VirtualEnvironment' | 'Conda' | 'Unknown';
/**
* Carries bitness for an environment.
*/
export type Bitness = '64-bit' | '32-bit' | 'Unknown';
/**
* The possible Python release levels.
*/
export type PythonReleaseLevel = 'alpha' | 'beta' | 'candidate' | 'final';
/**
* Release information for a Python version.
*/
export type PythonVersionRelease = {
readonly level: PythonReleaseLevel;
readonly serial: number;
};
export type VersionInfo = {
readonly major: number | undefined;
readonly minor: number | undefined;
readonly micro: number | undefined;
readonly release: PythonVersionRelease | undefined;
};
export type ResolvedVersionInfo = {
readonly major: number;
readonly minor: number;
readonly micro: number;
readonly release: PythonVersionRelease;
};
/**
* A record containing readonly keys.
*/
export type EnvironmentVariables = { readonly [key: string]: string | undefined };
export type EnvironmentVariablesChangeEvent = {
/**
* Workspace folder the environment variables changed for.
*/
readonly resource: WorkspaceFolder | undefined;
/**
* Updated value of environment variables.
*/
readonly env: EnvironmentVariables;
};
export const PVSC_EXTENSION_ID = 'ms-python.python';
// eslint-disable-next-line @typescript-eslint/no-namespace
export namespace PythonExtension {
/**
* Returns the API exposed by the Python extension in VS Code.
*/
export async function api(): Promise<PythonExtension> {
const extension = extensions.getExtension(PVSC_EXTENSION_ID);
if (extension === undefined) {
throw new Error(`Python extension is not installed or is disabled`);
}
if (!extension.isActive) {
await extension.activate();
}
const pythonApi: PythonExtension = extension.exports;
return pythonApi;
}
}
You can’t perform that action at this time.