Skip to content

Commit a6bd637

Browse files
author
Kartik Raj
committed
Move proposed API types to a different file
1 parent c08dff2 commit a6bd637

File tree

3 files changed

+231
-122
lines changed

3 files changed

+231
-122
lines changed

‎src/client/apiTypes.ts

Lines changed: 1 addition & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,9 @@
33
// Copyright (c) Microsoft Corporation. All rights reserved.
44
// Licensed under the MIT License.
55

6-
import { Disposable, Event, Uri } from 'vscode';
6+
import { Event, Uri } from 'vscode';
77
import { Resource } from './common/types';
88
import { IDataViewerDataProvider, IJupyterUriProvider } from './jupyter/types';
9-
import { EnvPathType } from './pythonEnvironments/base/info';
10-
import {
11-
EnvironmentDetails,
12-
EnvironmentDetailsOptions,
13-
EnvironmentProviderMetadata,
14-
GetRefreshEnvironmentsOptions,
15-
IEnvironmentProvider,
16-
ProgressNotificationEvent,
17-
} from './pythonEnvironments/base/locator';
189

1910
/*
2011
* Do not introduce any breaking changes to this API.
@@ -97,109 +88,3 @@ export interface IExtensionApi {
9788
registerRemoteServerProvider(serverProvider: IJupyterUriProvider): void;
9889
};
9990
}
100-
101-
export interface EnvironmentsChangedParams {
102-
/**
103-
* Path to environment folder or path to interpreter that uniquely identifies an environment.
104-
* Environments lacking an interpreter are identified by environment folder paths,
105-
* whereas other envs can be identified using executable path.
106-
*/
107-
path?: string;
108-
type: 'add' | 'remove' | 'update' | 'clear-all';
109-
}
110-
111-
export interface ActiveEnvironmentChangedParams {
112-
/**
113-
* Path to environment folder or path to interpreter that uniquely identifies an environment.
114-
* Environments lacking an interpreter are identified by environment folder paths,
115-
* whereas other envs can be identified using executable path.
116-
*/
117-
path: string;
118-
resource?: Uri;
119-
}
120-
121-
export interface RefreshEnvironmentsOptions {
122-
clearCache?: boolean;
123-
}
124-
125-
export interface IProposedExtensionAPI {
126-
environment: {
127-
/**
128-
* This event is triggered when the active environment changes.
129-
*/
130-
onDidActiveEnvironmentChanged: Event<ActiveEnvironmentChangedParams>;
131-
/**
132-
* Returns the path to the python binary selected by the user or as in the settings.
133-
* This is just the path to the python binary, this does not provide activation or any
134-
* other activation command. The `resource` if provided will be used to determine the
135-
* python binary in a multi-root scenario. If resource is `undefined` then the API
136-
* returns what ever is set for the workspace.
137-
* @param resource : Uri of a file or workspace
138-
*/
139-
getActiveEnvironmentPath(resource?: Resource): Promise<EnvPathType | undefined>;
140-
/**
141-
* Returns details for the given interpreter. Details such as absolute interpreter path,
142-
* version, type (conda, pyenv, etc). Metadata such as `sysPrefix` can be found under
143-
* metadata field.
144-
* @param path : Full path to environment folder or interpreter whose details you need.
145-
* @param options : [optional]
146-
* * useCache : When true, cache is checked first for any data, returns even if there
147-
* is partial data.
148-
*/
149-
getEnvironmentDetails(
150-
path: string,
151-
options?: EnvironmentDetailsOptions,
152-
): Promise<EnvironmentDetails | undefined>;
153-
/**
154-
* Sets the active environment path for the python extension for the resource. Configuration target
155-
* will always be the workspace folder.
156-
* @param path : Full path to environment folder or interpreter to set.
157-
* @param resource : [optional] Uri of a file ro workspace to scope to a particular workspace
158-
* folder.
159-
*/
160-
setActiveEnvironment(path: string, resource?: Resource): Promise<void>;
161-
locator: {
162-
/**
163-
* Returns paths to environments that uniquely identifies an environment found by the extension
164-
* at the time of calling. This API will *not* trigger a refresh. If a refresh is going on it
165-
* will *not* wait for the refresh to finish. This will return what is known so far. To get
166-
* complete list `await` on promise returned by `getRefreshPromise()`.
167-
*
168-
* Environments lacking an interpreter are identified by environment folder paths,
169-
* whereas other envs can be identified using executable path.
170-
*/
171-
getEnvironmentPaths(): Promise<EnvPathType[] | undefined>;
172-
/**
173-
* This event is triggered when the known environment list changes, like when a environment
174-
* is found, existing environment is removed, or some details changed on an environment.
175-
*/
176-
onDidEnvironmentsChanged: Event<EnvironmentsChangedParams[]>;
177-
/**
178-
* This API will re-trigger environment discovery. Extensions can wait on the returned
179-
* promise to get the updated environment list. If there is a refresh already going on
180-
* then it returns the promise for that refresh.
181-
* @param options : [optional]
182-
* * clearCache : When true, this will clear the cache before environment refresh
183-
* is triggered.
184-
*/
185-
refreshEnvironments(options?: RefreshEnvironmentsOptions): Promise<EnvPathType[] | undefined>;
186-
/**
187-
* Returns a promise for the ongoing refresh. Returns `undefined` if there are no active
188-
* refreshes going on.
189-
*/
190-
getRefreshPromise(options?: GetRefreshEnvironmentsOptions): Promise<void> | undefined;
191-
/**
192-
* Tracks discovery progress for current list of known environments, i.e when it starts, finishes or any other relevant
193-
* stage. Note the progress for a particular query is currently not tracked or reported, this only indicates progress of
194-
* the entire collection.
195-
*/
196-
readonly onRefreshProgress: Event<ProgressNotificationEvent>;
197-
};
198-
// registerEnvironmentProvider(
199-
// environmentProvider: IEnvironmentProvider,
200-
// metadata: EnvironmentProviderMetadata,
201-
// ): Promise<Disposable>;
202-
// TODO: Confirm whether this should return a promise??
203-
// For eg. If we also initialize a refresh a background.
204-
};
205-
}

‎src/client/proposedApi.ts

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,18 @@
22
// Licensed under the MIT License.
33

44
import { ConfigurationTarget, EventEmitter } from 'vscode';
5-
import {
6-
ActiveEnvironmentChangedParams,
7-
EnvironmentsChangedParams,
8-
IProposedExtensionAPI,
9-
RefreshEnvironmentsOptions,
10-
} from './apiTypes';
115
import { arePathsSame } from './common/platform/fs-paths';
126
import { IInterpreterPathService, Resource } from './common/types';
137
import { IInterpreterService } from './interpreter/contracts';
148
import { IServiceContainer } from './ioc/types';
9+
import {
10+
EnvironmentsChangedParams,
11+
ActiveEnvironmentChangedParams,
12+
IProposedExtensionAPI,
13+
EnvironmentDetailsOptions,
14+
EnvironmentDetails,
15+
RefreshEnvironmentsOptions,
16+
} from './proposedApiTypes';
1517
import { PythonEnvInfo } from './pythonEnvironments/base/info';
1618
import { getEnvPath } from './pythonEnvironments/base/info/env';
1719
import { GetRefreshEnvironmentsOptions, IDiscoveryAPI } from './pythonEnvironments/base/locator';

‎src/client/proposedApiTypes.ts

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
2+
// Licensed under the MIT License.
3+
4+
/* eslint-disable @typescript-eslint/ban-types */
5+
/* eslint-disable @typescript-eslint/no-explicit-any */
6+
// Copyright (c) Microsoft Corporation. All rights reserved.
7+
// Licensed under the MIT License.
8+
9+
import { Event, Uri } from 'vscode';
10+
11+
// https://github.com/microsoft/vscode-python/wiki/Proposed-Environment-APIs
12+
13+
export interface IProposedExtensionAPI {
14+
environment: {
15+
/**
16+
* This event is triggered when the active environment changes.
17+
*/
18+
onDidActiveEnvironmentChanged: Event<ActiveEnvironmentChangedParams>;
19+
/**
20+
* Returns the path to the python binary selected by the user or as in the settings.
21+
* This is just the path to the python binary, this does not provide activation or any
22+
* other activation command. The `resource` if provided will be used to determine the
23+
* python binary in a multi-root scenario. If resource is `undefined` then the API
24+
* returns what ever is set for the workspace.
25+
* @param resource : Uri of a file or workspace
26+
*/
27+
getActiveEnvironmentPath(resource?: Resource): Promise<EnvPathType | undefined>;
28+
/**
29+
* Returns details for the given interpreter. Details such as absolute interpreter path,
30+
* version, type (conda, pyenv, etc). Metadata such as `sysPrefix` can be found under
31+
* metadata field.
32+
* @param path : Full path to environment folder or interpreter whose details you need.
33+
* @param options : [optional]
34+
* * useCache : When true, cache is checked first for any data, returns even if there
35+
* is partial data.
36+
*/
37+
getEnvironmentDetails(
38+
path: string,
39+
options?: EnvironmentDetailsOptions,
40+
): Promise<EnvironmentDetails | undefined>;
41+
/**
42+
* Sets the active environment path for the python extension for the resource. Configuration target
43+
* will always be the workspace folder.
44+
* @param path : Full path to environment folder or interpreter to set.
45+
* @param resource : [optional] Uri of a file ro workspace to scope to a particular workspace
46+
* folder.
47+
*/
48+
setActiveEnvironment(path: string, resource?: Resource): Promise<void>;
49+
locator: {
50+
/**
51+
* Returns paths to environments that uniquely identifies an environment found by the extension
52+
* at the time of calling. This API will *not* trigger a refresh. If a refresh is going on it
53+
* will *not* wait for the refresh to finish. This will return what is known so far. To get
54+
* complete list `await` on promise returned by `getRefreshPromise()`.
55+
*
56+
* Environments lacking an interpreter are identified by environment folder paths,
57+
* whereas other envs can be identified using executable path.
58+
*/
59+
getEnvironmentPaths(): Promise<EnvPathType[] | undefined>;
60+
/**
61+
* This event is triggered when the known environment list changes, like when a environment
62+
* is found, existing environment is removed, or some details changed on an environment.
63+
*/
64+
onDidEnvironmentsChanged: Event<EnvironmentsChangedParams[]>;
65+
/**
66+
* This API will re-trigger environment discovery. Extensions can wait on the returned
67+
* promise to get the updated environment list. If there is a refresh already going on
68+
* then it returns the promise for that refresh.
69+
* @param options : [optional]
70+
* * clearCache : When true, this will clear the cache before environment refresh
71+
* is triggered.
72+
*/
73+
refreshEnvironments(options?: RefreshEnvironmentsOptions): Promise<EnvPathType[] | undefined>;
74+
/**
75+
* Returns a promise for the ongoing refresh. Returns `undefined` if there are no active
76+
* refreshes going on.
77+
*/
78+
getRefreshPromise(options?: GetRefreshEnvironmentsOptions): Promise<void> | undefined;
79+
/**
80+
* Tracks discovery progress for current list of known environments, i.e when it starts, finishes or any other relevant
81+
* stage. Note the progress for a particular query is currently not tracked or reported, this only indicates progress of
82+
* the entire collection.
83+
*/
84+
readonly onRefreshProgress: Event<ProgressNotificationEvent>;
85+
};
86+
};
87+
}
88+
89+
export enum Architecture {
90+
Unknown = 1,
91+
x86 = 2,
92+
x64 = 3,
93+
}
94+
95+
export type EnvSource = KnownEnvSourceTypes | string;
96+
97+
export enum KnownEnvSourceTypes {
98+
Conda = 'Conda',
99+
Pipenv = 'PipEnv',
100+
Poetry = 'Poetry',
101+
VirtualEnv = 'VirtualEnv',
102+
Venv = 'Venv',
103+
VirtualEnvWrapper = 'VirtualEnvWrapper',
104+
Pyenv = 'Pyenv',
105+
}
106+
107+
export type EnvType = KnownEnvTypes | string;
108+
109+
export enum KnownEnvTypes {
110+
VirtualEnv = 'VirtualEnv',
111+
Conda = 'Conda',
112+
Unknown = 'Unknown',
113+
Global = 'Global',
114+
}
115+
116+
export type BasicVersionInfo = {
117+
major: number;
118+
minor: number;
119+
micro: number;
120+
};
121+
122+
/**
123+
* The possible Python release levels.
124+
*/
125+
export enum PythonReleaseLevel {
126+
Alpha = 'alpha',
127+
Beta = 'beta',
128+
Candidate = 'candidate',
129+
Final = 'final',
130+
}
131+
132+
/**
133+
* Release information for a Python version.
134+
*/
135+
export type PythonVersionRelease = {
136+
level: PythonReleaseLevel;
137+
serial: number;
138+
};
139+
140+
export type StandardVersionInfo = BasicVersionInfo & {
141+
release?: PythonVersionRelease;
142+
};
143+
144+
export interface EnvironmentDetails {
145+
executable: {
146+
path: string;
147+
bitness?: Architecture;
148+
sysPrefix: string;
149+
// To be added later:
150+
// run: {
151+
// exec: Function;
152+
// shellExec: Function;
153+
// execObservable: Function;
154+
// terminalExec: () => void;
155+
// env?: { [key: string]: string | null | undefined };
156+
// };
157+
};
158+
environment?: {
159+
type: EnvType;
160+
name?: string;
161+
path: string;
162+
project?: string; // Any specific project environment is created for.
163+
source: EnvSource[];
164+
};
165+
version: StandardVersionInfo & {
166+
sysVersion?: string;
167+
};
168+
implementation?: {
169+
// `sys.implementation`
170+
name: string;
171+
version: StandardVersionInfo;
172+
};
173+
}
174+
175+
export interface EnvironmentDetailsOptions {
176+
useCache: boolean;
177+
}
178+
179+
export interface GetRefreshEnvironmentsOptions {
180+
/**
181+
* Get refresh promise which resolves once the following stage has been reached for the list of known environments.
182+
*/
183+
stage?: ProgressReportStage;
184+
}
185+
186+
export enum ProgressReportStage {
187+
discoveryStarted = 'discoveryStarted',
188+
allPathsDiscovered = 'allPathsDiscovered',
189+
discoveryFinished = 'discoveryFinished',
190+
}
191+
192+
export type ProgressNotificationEvent = {
193+
stage: ProgressReportStage;
194+
};
195+
196+
export type Resource = Uri | undefined;
197+
198+
/**
199+
* Path to environment folder or path to interpreter that uniquely identifies an environment.
200+
* Environments lacking an interpreter are identified by environment folder paths,
201+
* whereas other envs can be identified using interpreter path.
202+
*/
203+
export type UniquePathType = string;
204+
205+
export interface EnvPathType {
206+
path: UniquePathType;
207+
pathType: 'envFolderPath' | 'interpreterPath';
208+
}
209+
210+
export interface EnvironmentsChangedParams {
211+
path?: UniquePathType;
212+
type: 'add' | 'remove' | 'update' | 'clear-all';
213+
}
214+
215+
export interface ActiveEnvironmentChangedParams {
216+
path: UniquePathType;
217+
resource?: Uri;
218+
}
219+
220+
export interface RefreshEnvironmentsOptions {
221+
clearCache?: boolean;
222+
}

0 commit comments

Comments
 (0)