GeezerVisonThe World Wide Web, restored to 800 pixels of glory. |
| Home|About|Gaming cabinet|Archives|How it works|Starter sites |
GeezerVison is showing github.com — vscode-python/pythonExtensionApi/src/main.ts at main · wpbonelli/vscode-python Expand file tree/ Copy pathmain.tsMore file actions 348 lines (326 loc) · 13 KB / Copy pathmain.tsFile metadata and controls348 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 & { /** * Resource the environment changed for. */ readonly resource: Resource | 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 are visitor 01402520 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required. |