Skip to content

Commit b680b21

Browse files
StellaHuang95StellaHuang95
authored
Improve Settings Reference documentation and fix python-env.* naming inconsistency (#1114)
This PR does the following: - Fix settings prefix inconsistency Renames `python-env.*` settings to `python-envs.*` for consistency and updates `package.json`, localization files, and source code accordingly. - Improve Settings Reference documentation Restructures the settings tables for clarity, adds missing documentation for Python Environments settings, and clarifies supported values and path resolution behavior. - Clarify legacy settings and deprecation direction Improves user-facing guidance on legacy Python settings, including migration paths and deprecation notes, and documents the planned replacement of terminal activation settings with `python-envs.terminal.autoActivationType` based on discussion with Anthony. Here's what the readme looks like now. <img width="1621" height="573" alt="image" src="https://github.com/user-attachments/assets/7dd9608b-6c9c-4f85-b71f-41fdd95692cb" /> <img width="1620" height="469" alt="image" src="https://github.com/user-attachments/assets/888e2b13-ca69-4cfa-bfd8-2359644962bb" />
1 parent edd4c31 commit b680b21

5 files changed

Lines changed: 38 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -125,13 +125,33 @@ All commands can be accessed via the Command Palette (`ctrl/cmd + Shift + P`):
125125

126126
## Settings Reference
127127

128-
| Setting (python-envs.) | Default | Description |
129-
| --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
130-
| defaultEnvManager | `"ms-python.python:venv"` | The default environment manager used for creating and managing environments. |
131-
| defaultPackageManager | `"ms-python.python:pip"` | The default package manager to use for installing and managing packages. This is often dictated by the default environment manager but can be customized. |
132-
| pythonProjects | `[]` | A list of Python workspaces, specified by the path, in which you can set particular environment and package managers. You can set information for a workspace as `[{"path": "/path/to/workspace", "envManager": "ms-python.python:venv", "packageManager": "ms-python.python:pip"]}`. |
133-
| terminal.showActivateButton | `false` | (experimental) Show a button in the terminal to activate/deactivate the current environment for the terminal. This button is only shown if the active terminal is associated with a project that has an activatable environment. |
134-
| python-envs.terminal.autoActivationType | `command` | Specifies how the extension can activate an environment in a terminal. Utilizing Shell Startup requires changes to the shell script file and is only enabled for the following shells: zsh, fsh, pwsh, bash, cmd. When set to `command`, any shell can be activated. This setting applies only when terminals are created, so you will need to restart your terminals for it to take effect. To revert changes made during shellStartup, run `Python Envs: Revert Shell Startup Script Changes`. |
128+
### Python Environments Settings (`python-envs.`)
129+
130+
| Setting (python-envs.) | Default | Description |
131+
| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
132+
| defaultEnvManager | `"ms-python.python:venv"` | The default environment manager used for creating and managing environments. |
133+
| defaultPackageManager | `"ms-python.python:pip"` | The default package manager to use for installing and managing packages. This is often dictated by the default environment manager but can be customized. |
134+
| pythonProjects | `[]` | A list of Python workspaces, specified by the path, in which you can set particular environment and package managers. You can set information for a workspace as `[{"path": "/path/to/workspace", "envManager": "ms-python.python:venv", "packageManager": "ms-python.python:pip"]}`. |
135+
| terminal.showActivateButton | `false` | (experimental) Show a button in the terminal to activate/deactivate the current environment for the terminal. This button is only shown if the active terminal is associated with a project that has an activatable environment. |
136+
| terminal.autoActivationType | `"command"` | Specifies how the extension can activate an environment in a terminal. Accepted values: `command` (execute activation command in terminal), `shellStartup` (`terminal.integrated.shellIntegration.enabled` successfully enabled or we may modify shell startup scripts ), `off` (no auto-activation). Shell startup is only supported for: zsh, fish, pwsh, bash, cmd. **Takes precedence over** `python.terminal.activateEnvironment`. Restart terminals after changing this setting. To revert shell startup changes, run `Python Envs: Revert Shell Startup Script Changes`. |
137+
| alwaysUseUv | `true` | When `true`, [uv](https://github.com/astral-sh/uv) will be used to manage all virtual environments if available. When `false`, uv will only manage virtual environments explicitly created by uv. |
138+
| globalSearchPaths | `[]` | Global search paths for Python environments. Array of absolute directory paths to search for environments at the user level. This setting is merged with the legacy `python.venvPath` and `python.venvFolders` settings. |
139+
| workspaceSearchPaths | `[]` | Workspace search paths for Python environments. Can be absolute paths or relative directory paths searched within the workspace. |
140+
141+
### Supported Legacy Python Settings (`python.`)
142+
143+
The following settings from the Python extension (`python.*`) are also supported by Python Environments.
144+
145+
| Setting (`python.`) | Default | Description |
146+
| ------------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
147+
| condaPath | `""` | Path to the conda executable. Used to locate and run conda for environment discovery and management. |
148+
| defaultInterpreterPath | `"python"` | Path to the default Python interpreter. |
149+
| envFile | `"${workspaceFolder}/.env"` | Path to the environment file (`.env`) containing environment variable definitions. Used with `python.terminal.useEnvFile` to inject environment variables into terminals. |
150+
| terminal.activateEnvironment | `true` | Legacy setting for terminal auto-activation. If `python-envs.terminal.autoActivationType` is not set and this is `false`, terminal auto-activation will be disabled. **Superseded by** `python-envs.terminal.autoActivationType` which takes precedence when configured. |
151+
| terminal.executeInFileDir | `false` | When `true`, the terminal's working directory will be set to the directory containing the Python file being executed, rather than the project root directory. |
152+
| terminal.useEnvFile | `false` | Controls whether environment variables from `.env` files (specified by `python.envFile`) are injected into terminals. |
153+
| venvFolders | `[]` | Array of folder names to search for virtual environments. These folders are searched in addition to the standard locations. **Note:** This setting is merged with `python-envs.globalSearchPaths`. Consider migrating to `python-envs.globalSearchPaths` for future compatibility. |
154+
| venvPath | `""` | Path to a folder containing virtual environments. **Note:** This setting is merged with `python-envs.globalSearchPaths`. Consider migrating to `python-envs.globalSearchPaths` for future compatibility. |
135155

136156
## Extensibility
137157

‎package.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -111,18 +111,18 @@
111111
"default": false,
112112
"scope": "resource"
113113
},
114-
"python-env.globalSearchPaths": {
114+
"python-envs.globalSearchPaths": {
115115
"type": "array",
116-
"markdownDescription": "%python-env.globalSearchPaths.description%",
116+
"markdownDescription": "%python-envs.globalSearchPaths.description%",
117117
"default": [],
118118
"scope": "machine",
119119
"items": {
120120
"type": "string"
121121
}
122122
},
123-
"python-env.workspaceSearchPaths": {
123+
"python-envs.workspaceSearchPaths": {
124124
"type": "array",
125-
"description": "%python-env.workspaceSearchPaths.description%",
125+
"description": "%python-envs.workspaceSearchPaths.description%",
126126
"default": [],
127127
"scope": "resource",
128128
"items": {

‎package.nls.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@
88
"python-envs.terminal.showActivateButton.description": "Whether to show the 'Activate' button in the terminal menu",
99
"python-envs.terminal.autoActivationType.description": "Specifies how the extension can activate an environment in a terminal.\n\nShell startup activates using [shell integration](https://code.visualstudio.com/docs/terminal/shell-integration) or may require changes to the shell initialization files and is only enabled for the following shells: zsh, fsh, pwsh, bash, cmd. When set to `command`, any shell can be activated.\n\n**Legacy Setting Support:** This setting takes precedence over the legacy `python.terminal.activateEnvironment` setting. If this setting is not explicitly set and `python.terminal.activateEnvironment` is set to false, this setting will automatically be set to `off` to preserve your preference.\n\nThis setting applies only when terminals are created, so you will need to restart your terminals for it to take effect.\n\nTo revert changes made during shellStartup, run `Python Envs: Revert Shell Startup Script Changes`.",
1010
"python-envs.terminal.autoActivationType.command": "Activation by executing a command in the terminal.",
11-
"python-envs.terminal.autoActivationType.shellStartup": "Activation by modifying the terminal shell startup script. To use this feature we will need to modify your shell startup scripts.",
11+
"python-envs.terminal.autoActivationType.shellStartup": "Activation by modifying the terminal shell startup script. To use this feature we may need to modify your shell startup scripts and terminal.integrated.shellIntegration.enabled enabled for ideal experience.",
1212
"python-envs.terminal.autoActivationType.off": "No automatic activation of environments.",
1313
"python-envs.terminal.useEnvFile.description": "Controls whether environment variables from .env files and python.envFile setting are injected into terminals.",
14-
"python-env.globalSearchPaths.description": "Global search paths for Python environments. Absolute directory paths that are searched at the user level.\n\n**Legacy Setting Support:** This setting is merged with the legacy `python.venvPath` and `python.venvFolders` settings. All paths from these three settings are combined into a single list of search paths. The legacy settings `python.venvPath` and `python.venvFolders` will be deprecated in the future, after which this setting will fully replace them. Please consider migrating your paths to this setting.",
15-
"python-env.workspaceSearchPaths.description": "Workspace search paths for Python environments. Can be absolute paths or relative directory paths searched within the workspace.",
14+
"python-envs.globalSearchPaths.description": "Global search paths for Python environments. Absolute directory paths that are searched at the user level.\n\n**Legacy Setting Support:** This setting is merged with the legacy `python.venvPath` and `python.venvFolders` settings. All paths from these three settings are combined into a single list of search paths. The legacy settings `python.venvPath` and `python.venvFolders` will be deprecated in the future, after which this setting will fully replace them. Please consider migrating your paths to this setting.",
15+
"python-envs.workspaceSearchPaths.description": "Workspace search paths for Python environments. Can be absolute paths or relative directory paths searched within the workspace.",
1616
"python-envs.terminal.revertStartupScriptChanges.title": "Revert Shell Startup Script Changes",
1717
"python-envs.reportIssue.title": "Report Issue",
1818
"python-envs.setEnvManager.title": "Set Environment Manager",

‎src/managers/common/nativePythonFinder.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -455,7 +455,7 @@ export async function getAllExtraSearchPaths(): Promise<string[]> {
455455
*/
456456
function getGlobalSearchPaths(): string[] {
457457
try {
458-
const envConfig = getConfiguration('python-env');
458+
const envConfig = getConfiguration('python-envs');
459459
const inspection = envConfig.inspect<string[]>('globalSearchPaths');
460460

461461
const globalPaths = inspection?.globalValue || [];
@@ -471,12 +471,12 @@ function getGlobalSearchPaths(): string[] {
471471
*/
472472
function getWorkspaceSearchPaths(): string[] {
473473
try {
474-
const envConfig = getConfiguration('python-env');
474+
const envConfig = getConfiguration('python-envs');
475475
const inspection = envConfig.inspect<string[]>('workspaceSearchPaths');
476476

477477
if (inspection?.globalValue) {
478478
traceError(
479-
'Error: python-env.workspaceSearchPaths is set at the user/global level, but this setting can only be set at the workspace or workspace folder level.',
479+
'Error: python-envs.workspaceSearchPaths is set at the user/global level, but this setting can only be set at the workspace or workspace folder level.',
480480
);
481481
}
482482

‎src/test/managers/common/nativePythonFinder.getAllExtraSearchPaths.unit.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ suite('getAllExtraSearchPaths Integration Tests', () => {
7878
if (section === 'python') {
7979
return pythonConfig;
8080
}
81-
if (section === 'python-env') {
81+
if (section === 'python-envs') {
8282
return envConfig;
8383
}
8484
throw new Error(`Unexpected configuration section: ${section}`);

0 commit comments

Comments
 (0)