Skip to content

Commit 4273ec0

Browse files
eleanorjboydeleanorjboyd
authored
Merge branch 'main' into new-script-723
2 parents 069f184 + 08cd367 commit 4273ec0

File tree

3 files changed

+161
-42
lines changed

3 files changed

+161
-42
lines changed

‎README.md‎

Lines changed: 153 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
## Overview
44

5-
The Python Environments extension for VS Code helps you manage Python environments and packages using your preferred environment manager, backed by its extensible APIs. This extension provides unique support for specifying environments for specific files, entire Python folders, or projects, including multi-root and mono-repo scenarios. The core feature set includes:
5+
The Python Environments extension for VS Code helps you manage Python environments and packages using your preferred environment manager, backed by its extensible APIs. This extension provides unique support for specifying environments for specific files, entire Python folders, or projects, including multi-root and mono-repo scenarios. The core feature set includes:
66

7-
- 🌐 Create, delete, and manage environments
8-
- 📦 Install and uninstall packages within the selected environment
9-
- ✅ Create activated terminals
10-
- 🖌️ Add and create new Python projects
7+
- 🌐 Create, delete, and manage environments
8+
- 📦 Install and uninstall packages within the selected environment
9+
- ✅ Create activated terminals
10+
- 🖌️ Add and create new Python projects
1111

1212
> **Note:** This extension is in preview, and its APIs and features are subject to change as the project evolves.
1313
@@ -29,9 +29,9 @@ The Python Environments panel provides an interface to create, delete and manage
2929

3030
To simplify the environment creation process, you can use "Quick Create" to automatically create a new virtual environment using:
3131

32-
- Your default environment manager (e.g., `venv`)
33-
- The latest Python version
34-
- Workspace dependencies
32+
- Your default environment manager (e.g., `venv`)
33+
- The latest Python version
34+
- Workspace dependencies
3535

3636
For more control, you can create a custom environment where you can specify Python version, environment name, packages to be installed, and more!
3737

@@ -51,7 +51,7 @@ The extension also provides an interface to install and uninstall Python package
5151

5252
The extension uses `pip` as the default package manager, but you can use the package manager of your choice using the `python-envs.defaultPackageManager` setting. The following are package managers supported out of the box:
5353

54-
| Id | Name | Description|
54+
| Id | Name | Description |
5555
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
5656
| ms-python.python:pip | `pip` | Pip acts as the default package manager and it's typically built-in to Python. |
5757
| ms-python.python:conda | `conda` | The [conda](https://conda.org) package manager, as provided by conda distributions like [Anaconda Distribution](https://docs.anaconda.com/anaconda/) or [conda-forge](https://conda-forge.org/download/). |
@@ -64,30 +64,30 @@ Projects can be added via the Python Environments pane or in the File Explorer b
6464

6565
There are a couple of ways that you can add a Python Project from the Python Environments panel:
6666

67-
| Name | Description |
68-
| ----- | ---------- |
69-
| Add Existing | Allows you to add an existing folder from the file explorer. |
70-
| Auto find | Searches for folders that contain `pyproject.toml` or `setup.py` files |
67+
| Name | Description |
68+
| ------------ | ---------------------------------------------------------------------- |
69+
| Add Existing | Allows you to add an existing folder from the file explorer. |
70+
| Auto find | Searches for folders that contain `pyproject.toml` or `setup.py` files |
7171

7272
## Command Reference
7373

74-
| Name | Description |
75-
| -------- | ------------- |
76-
| Python: Create Environment | Create a virtual environment using your preferred environment manager preconfigured with "Quick Create" or configured to your choices. |
77-
| Python: Manage Packages | Install and uninstall packages in a given Python environment. |
78-
| Python: Activate Environment in Current Terminal | Activates the currently opened terminal with a particular environment. |
79-
| Python: Deactivate Environment in Current Terminal | Deactivates environment in currently opened terminal. |
80-
| Python: Run as Task | Runs Python module as a task. |
74+
| Name | Description |
75+
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
76+
| Python: Create Environment | Create a virtual environment using your preferred environment manager preconfigured with "Quick Create" or configured to your choices. |
77+
| Python: Manage Packages | Install and uninstall packages in a given Python environment. |
78+
| Python: Activate Environment in Current Terminal | Activates the currently opened terminal with a particular environment. |
79+
| Python: Deactivate Environment in Current Terminal | Deactivates environment in currently opened terminal. |
80+
| Python: Run as Task | Runs Python module as a task. |
8181

8282
## Settings Reference
8383

84-
| Setting (python-envs.) | Default | Description |
85-
| --------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
86-
| defaultEnvManager | `"ms-python.python:venv"` | The default environment manager used for creating and managing environments. |
87-
| 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. |
88-
| 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"]}`. |
89-
| 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. |
90-
| 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`.|
84+
| Setting (python-envs.) | Default | Description |
85+
| --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
86+
| defaultEnvManager | `"ms-python.python:venv"` | The default environment manager used for creating and managing environments. |
87+
| 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. |
88+
| 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"]}`. |
89+
| 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. |
90+
| 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`. |
9191

9292
## Extensibility
9393

@@ -118,23 +118,137 @@ Create a new environment using any of the available environment managers. This c
118118
* Default `true`. If `true`, the environment after creation will be selected.
119119
*/
120120
selectEnvironment?: boolean;
121+
122+
/**
123+
* Provides some context about quick create based on user input.
124+
* - if true, the environment should be created without any user input or prompts.
125+
* - if false, the environment creation can show user input or prompts.
126+
* This also means user explicitly skipped the quick create option.
127+
* - if undefined, the environment creation can show user input or prompts.
128+
* You can show quick create option to the user if you support it.
129+
*/
130+
quickCreate?: boolean;
131+
/**
132+
* Packages to install in addition to the automatically picked packages as a part of creating environment.
133+
*/
134+
additionalPackages?: string[];
121135
}
122136
```
123137

124138
usage: `await vscode.commands.executeCommand('python-envs.createAny', options);`
125139

140+
# Experimental Features
141+
142+
## Shell Startup Activation
143+
144+
The Python Environments extension supports shell startup activation for environments. This feature allows you to automatically activate a Python environment when you open a terminal in VS Code. The activation is done by modifying the shell's startup script, which is supported for the following shells:
145+
146+
- **Bash**: `~/.bashrc`
147+
- **Zsh**: `~/.zshrc`
148+
- **Fish**: `~/.config/fish/config.fish`
149+
- **PowerShell**:
150+
- (Mac/Linux):`~/.config/powershell/profile.ps1`
151+
- (Windows): `~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1`
152+
- **CMD**: `~/.cmdrc/cmd_startup.bat`
153+
154+
### CMD
155+
156+
1. Add or update `HKCU\\Software\\Microsoft\\Command Processor` `AutoRun` string value to use a command script.
157+
2. A command script is added to `%USERPROFILE%\.cmdrc\cmd_startup.bat`
158+
3. A script named `vscode-python.bat` is added to `%USERPROFILE%\.cmdrc` and called from `cmd_startup.bat`
159+
160+
contents of `cmd_startup.bat`
161+
162+
```bat
163+
:: >>> vscode python
164+
if "%TERM_PROGRAM%"=="vscode" (
165+
if not defined VSCODE_PYTHON_AUTOACTIVATE_GUARD (
166+
set "VSCODE_PYTHON_AUTOACTIVATE_GUARD=1"
167+
if exist "%USERPROFILE%\.cmdrc\vscode-python.bat" call "%USERPROFILE%\.cmdrc\vscode-python.bat"
168+
)
169+
)
170+
:: <<< vscode python
171+
```
172+
173+
contents of `vscode-python.bat`
174+
175+
```bat
176+
:: >>> vscode python
177+
:: version: 0.1.0
178+
if defined VSCODE_CMD_ACTIVATE (
179+
call %VSCODE_CMD_ACTIVATE%
180+
)
181+
:: <<< vscode python
182+
```
183+
184+
### Powershell/pwsh
185+
186+
1. Runs `powershell -Command $profile` to get the profile location
187+
2. If it does not exist creates it.
188+
3. Adds following code to the shell profile script:
189+
190+
```powershell
191+
#region vscode python
192+
if ($null -ne $env:VSCODE_PWSH_ACTIVATE) {
193+
Invoke-Expression $env:VSCODE_PWSH_ACTIVATE
194+
}
195+
#endregion vscode python
196+
197+
```
198+
199+
### sh/bash/gitbash
200+
201+
1. Adds or creates `~/.bashrc`
202+
2. Updates it with following code:
203+
204+
```bash
205+
# >>> vscode python
206+
# version: 0.1.0
207+
if [ -n "$VSCODE_BASH_ACTIVATE" ] && [ "$TERM_PROGRAM" = "vscode" ]; then
208+
eval "$VSCODE_BASH_ACTIVATE" || true
209+
fi
210+
# <<< vscode python
211+
```
212+
213+
### zsh
214+
215+
1. Adds or creates `~/.zshrc`
216+
2. Updates it with following code:
217+
218+
```zsh
219+
# >>> vscode python
220+
# version: 0.1.0
221+
if [ -n "$VSCODE_BASH_ACTIVATE" ] && [ "$TERM_PROGRAM" = "vscode" ]; then
222+
eval "$VSCODE_BASH_ACTIVATE" || true
223+
fi
224+
# <<< vscode python
225+
```
226+
227+
### fish
228+
229+
1. Adds or creates `~/.config/fish/config.fish`
230+
2. Updates it with following code:
231+
232+
```fish
233+
# >>> vscode python
234+
# version: 0.1.0
235+
if test "$TERM_PROGRAM" = "vscode"; and set -q VSCODE_FISH_ACTIVATE
236+
eval $VSCODE_FISH_ACTIVATE
237+
end
238+
# <<< vscode python
239+
```
126240

127241
## Extension Dependency
128242

129243
This section provides an overview of how the Python extension interacts with the Python Environments extension and other tool-specific extensions. The Python Environments extension allows users to create, manage, and remove Python environments and packages. It also provides an API that other extensions can use to support environment management or consume it for running Python tools or projects.
130244

131245
Tools that may rely on these APIs in their own extensions include:
132246

133-
- **Debuggers** (e.g., `debugpy`)
134-
- **Linters** (e.g., Pylint, Flake8, Mypy)
135-
- **Formatters** (e.g., Black, autopep8)
136-
- **Language Server extensions** (e.g., Pylance, Jedi)
137-
- **Environment and Package Manager extensions** (e.g., Pixi, Conda, Hatch)
247+
- **Debuggers** (e.g., `debugpy`)
248+
- **Linters** (e.g., Pylint, Flake8, Mypy)
249+
- **Formatters** (e.g., Black, autopep8)
250+
- **Language Server extensions** (e.g., Pylance, Jedi)
251+
- **Environment and Package Manager extensions** (e.g., Pixi, Conda, Hatch)
138252

139253
### API Dependency
140254

@@ -170,13 +284,13 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
170284

171285
## Questions, issues, feature requests, and contributions
172286

173-
- If you have a question about how to accomplish something with the extension, please [ask on our Discussions page](https://github.com/microsoft/vscode-python/discussions/categories/q-a).
174-
- If you come across a problem with the extension, please [file an issue](https://github.com/microsoft/vscode-python).
175-
- Contributions are always welcome! Please see our [contributing guide](https://github.com/Microsoft/vscode-python/blob/main/CONTRIBUTING.md) for more details.
176-
- Any and all feedback is appreciated and welcome!
177-
- If someone has already [filed an issue](https://github.com/Microsoft/vscode-python) that encompasses your feedback, please leave a 👍/👎 reaction on the issue.
178-
- Otherwise please start a [new discussion](https://github.com/microsoft/vscode-python/discussions/categories/ideas).
179-
- If you're interested in the development of the extension, you can read about our [development process](https://github.com/Microsoft/vscode-python/blob/main/CONTRIBUTING.md#development-process).
287+
- If you have a question about how to accomplish something with the extension, please [ask on our Discussions page](https://github.com/microsoft/vscode-python/discussions/categories/q-a).
288+
- If you come across a problem with the extension, please [file an issue](https://github.com/microsoft/vscode-python).
289+
- Contributions are always welcome! Please see our [contributing guide](https://github.com/Microsoft/vscode-python/blob/main/CONTRIBUTING.md) for more details.
290+
- Any and all feedback is appreciated and welcome!
291+
- If someone has already [filed an issue](https://github.com/Microsoft/vscode-python) that encompasses your feedback, please leave a 👍/👎 reaction on the issue.
292+
- Otherwise please start a [new discussion](https://github.com/microsoft/vscode-python/discussions/categories/ideas).
293+
- If you're interested in the development of the extension, you can read about our [development process](https://github.com/Microsoft/vscode-python/blob/main/CONTRIBUTING.md#development-process).
180294

181295
## Data and telemetry
182296

‎src/features/terminal/shells/cmd/cmdStartup.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,9 +77,11 @@ function getMainBatchFileContent(startupFile: string): string {
7777
const lineSep = '\r\n';
7878
const content = [];
7979

80-
content.push('if not defined VSCODE_PYTHON_AUTOACTIVATE_GUARD (');
81-
content.push(' set "VSCODE_PYTHON_AUTOACTIVATE_GUARD=1"');
82-
content.push(` if exist "${startupFile}" call "${startupFile}"`);
80+
content.push('if "%TERM_PROGRAM%"=="vscode" (');
81+
content.push(' if not defined VSCODE_PYTHON_AUTOACTIVATE_GUARD (');
82+
content.push(' set "VSCODE_PYTHON_AUTOACTIVATE_GUARD=1"');
83+
content.push(` if exist "${startupFile}" call "${startupFile}"`);
84+
content.push(' )');
8385
content.push(')');
8486

8587
return content.join(lineSep);

‎src/features/terminal/shells/common/shellUtils.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ function getCommandAsString(command: PythonCommandRunConfiguration[], shell: str
1010
parts.push(quoteArgs([normalizeShellPath(cmd.executable, shell), ...args]).join(' '));
1111
}
1212
if (shell === ShellConstants.PWSH) {
13+
if (parts.length === 1) {
14+
return parts[0];
15+
}
1316
return parts.map((p) => `(${p})`).join(` ${delimiter} `);
1417
}
1518
return parts.join(` ${delimiter} `);

0 commit comments

Comments
 (0)