-
+
width=734 height=413>
### Environment Management
-This extension provides an Environments view, which can be accessed via the VS Code Activity Bar, where you can manage your Python environments. Here, you can create, delete, and switch between environments, as well as install and uninstall packages within the selected environment. It also provides APIs for extension developers to contribute their own environment managers.
+This extension provides an Environment Managers view, accessible via the VS Code Activity Bar, where you can:
+
+- Create, delete, and switch between environments.
+- Install and uninstall packages within the selected environment.
+- Use APIs to allow extension developers to contribute their own environment managers.
+
+![ADD A QUICK REFERENCE FOR UI BUTTON]()
+
+To simplify the environment creation process, you can use "Quick Create" to automatically create a new virtual environment using:
-ADD A QUICK REFERENCE FOR UI BUTTON
+- Your default environment manager (e.g., `venv`)
+- The latest Python version
+- Workspace dependencies
-To further simplify the environment creation process, you can create a virtual environments using "Quick Create", which uses your default environment manager (i.e. `venv`) and the most updated Python version to create a virtual environment. If you would like more control over your environment features, such as the Python version used, the environment name, packages installed, etc. you can create a custom environment.
+For more control, you can create a custom environment where you can specify Python version, environment name, packages to be installed, and more!
+
+![Gif showing environment creation using Quick Create.]()
The following environment managers are supported out of the box:
-| Id | name | Description |
+| Id | Name | Description |
| ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ms-python.python:venv | `venv` | The default environment manager. It is a built-in environment manager provided by the Python standard library. |
| ms-python.python:system | System Installed Python | These are global Python installs on your system. These are typically installed with your OS, from [python.org](https://www.python.org/), or any other OS package manager. |
| ms-python.python:conda | `conda` | The [conda](https://conda.org) environment manager, as provided by conda distributions like [Anaconda Distribution](https://docs.anaconda.com/anaconda/) or [conda-forge](https://conda-forge.org/download/). |
-The environment manager is responsible for specifying which package manager will be used by default to install and manage Python packages within the environment. This ensures that packages are managed consistently according to the preferred tools and settings of the chosen environment manager.
+Environment managers are responsible for specifying which package manager will be used by default to install and manage Python packages within the environment (`venv` uses `pip` by default). This ensures that packages are managed consistently according to the preferred tools and settings of the chosen environment manager.
### Package Management
-This extension provides a package view for you to manage, install and uninstall you Python packages in any particular environment. This extension provides APIs for extension developers to contribute package managers.
+The extension also provides an interface to install and uninstall Python packages, and provides APIs for extension developers to contribute package managers of their choice.
-ADD A QUICK REFERENCE FOR BUTTONS
+![ADD A QUICK REFERENCE PICTURE FOR BUTTONS]()
The extension uses `pip` as the default package manager. You can change this by setting the `python-envs.defaultPackageManager` setting to a different package manager. The following are package managers supported out of the box:
-| Id | Name | Description |
+| Id | Name | Description|
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ms-python.python:pip | `pip` | Pip acts as the default package manager and it's typically built-in to Python. |
| 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/). |
-## Command Reference
+### Project Creation
+
+The **Python: Create Project** command simplifies the process of starting a new Python project by scaffolding it for you. Whether in a new workspace or an existing one, this command sets up the necessary environment and files, so you donβt have to worry about the initial setup, and only the code you want to write.
+
+![Gif showing project creation using the `Python: Create Project` command for a Python package.]()
-| Name | Description |
-| Python: Manage Packages | |
-| Python: Create Project | |
-| Python: Activate Environment in Current Terminal | |
-| Python: Deactivate Environment in Current Terminal | |
-| Python: Run as Task | |
+#### Types of Projects
+
+The `Python: Create Project` command supports the following project types:
+
+- Package: A structured Python package with files like `__init__.py` and setup configurations.
+- Generic script: A simple project for standalone Python scripts, ideal for quick tasks or just to get you started.
+
+## Command Reference
+
+| Name | Description |
+| -------- | ------------- |
+| Python: Create Environment | Create a virtual environment using your preferred environment manager preconfigured with "Quick Create" or configured to your choices. |
+| Python: Manage Packages | Install and uninstall packages in a given Python environment. |
+| Python: Create Project | Creates a scaffolded Python project with a virtual environment. |
+| Python: Activate Environment in Current Terminal | Activates the currently opened terminal with a particular environment. |
+| Python: Deactivate Environment in Current Terminal | Deactivates environment in currently opened terminal. |
+| Python: Run as Task | Runs Python module as a task. |
## Settings Reference
| Setting (python-envs.) | Default | Description |
| --------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| defaultEnvManager | `"ms-python.python:venv"` | The default environment manager used for creating and managing environments. |
-| 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. |
+| defaultEnvManager | `"ms-python.python:venv"` | The default environment manager used for creating and managing environments. |
+| 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. |
| 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"]}`. |
-| 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. |
+| 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. |
## Extensibility
-The Python Environments extension was built to provide a cohesive and user friendly experience with `venv` as the default. However, the extension is built with extensibility in mind so that any environment manager could build an extension using the supported APIs to plug-in and provide a seamless and incirporated experience for their users in VS Code.
+The Python Environments extension was built to provide a cohesive and user friendly experience with `venv` as the default. However, the extension is built with extensibility in mind so that any environment manager could build an extension using the supported APIs to plug-in and provide a seamless and incorporated experience for their users in VS Code.
### API Reference (proposed)
See [api.ts](https://github.com/microsoft/vscode-python-environments/blob/main/src/api.ts) for the full list of Extension APIs.
-To consume these APIs you can look at the example here:
-https://github.com/microsoft/vscode-python-environments/blob/main/examples/README.md
-
+To consume these APIs you can look at the example here: [API Consumption Examples](https://github.com/microsoft/vscode-python-environments/blob/main/examples/README.md)
## Extension Dependency
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.
Tools that may rely on these APIs in their own extensions include:
+
- **Debuggers** (e.g., `debugpy`)
- **Linters** (e.g., Pylint, Flake8, Mypy)
- **Formatters** (e.g., Black, autopep8)
@@ -86,9 +111,10 @@ Tools that may rely on these APIs in their own extensions include:
- **Environment and Package Manager extensions** (e.g., Pixi, Conda, Hatch)
### API Dependency
+
The relationship between these extensions can be represented as follows:
-
+
width=734 height=413>
Users who do not need to execute code or work in **Virtual Workspaces** can use the Python extension to access language features like hover, completion, and go-to definition. However, executing code (e.g., running a debugger, linter, or formatter), creating/modifying environments, or managing packages requires the Python Environments extension to enable these functionalities.
@@ -98,7 +124,7 @@ VS Code supports trust management, allowing extensions to function in either **t
The relationship is illustrated below:
-
+
width=734 height=413>
In **trusted mode**, the Python Environments extension supports tasks like managing environments, installing/removing packages, and running tools. In **untrusted mode**, functionality is limited to language features, ensuring a secure and restricted environment.
@@ -106,7 +132,7 @@ In **trusted mode**, the Python Environments extension supports tasks like manag
This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+the rights to use your contribution. For details, visit
width=734 height=413>
### Environment Management
-This extension provides an Python Environments view, accessible via the VS Code Activity Bar, where you can:
-
-- Create, delete, and switch between environments.
-- Install and uninstall packages within the selected environment.
-- Use APIs to allow extension developers to contribute their own environment managers.
+The Python Environments panel provides an interface to create, delete and manage environments.
![ADD A QUICK REFERENCE FOR UI BUTTON]()
From 088d145d9c7f4575890f2562b5e91f7ef5d615db Mon Sep 17 00:00:00 2001
From: Courtney Webster <60238438+cwebster-99@users.noreply.github.com>
Date: Thu, 17 Apr 2025 15:04:43 +0000
Subject: [PATCH 05/12] moving things around
---
README.md | 16 +++++++---------
1 file changed, 7 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
index 72ad3fad..6bddcd72 100644
--- a/README.md
+++ b/README.md
@@ -2,19 +2,17 @@
## Overview
-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 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:
+
+- π Create, delete, and manage environments
+- π¦ Install and uninstall packages within the selected environment
+- β
Create activated terminals Activate terminals
+- ποΈ Add and create new Python projects
> **Note:** This extension is in preview, and its APIs and features are subject to change as the project evolves.
> **Important:** This extension requires the pre-release version of the Python extension (`ms-python.python`) to operate (version 2024.23.2025010901 or later).
-This extension provides a Python Environments view, accessible via the VS Code Activity Bar, where you can:
-
-- Create, delete, and manage environments
-- Install and uninstall packages within the selected environment
-- Create activated terminals Activate terminals
-- Add and create new Python projects
-
## Features
width=734 height=413>
@@ -51,7 +49,7 @@ The extension also provides an interface to install and uninstall Python package
![ADD A QUICK REFERENCE PICTURE FOR BUTTONS]()
-The extension uses `pip` as the default package manager. You can change this by setting the `python-envs.defaultPackageManager` setting to a different package manager. The following are package managers supported out of the box:
+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:
| Id | Name | Description|
| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
From 908cbe880ce28edbf8d5a668c267cd15e2befc58 Mon Sep 17 00:00:00 2001
From: Courtney Webster <60238438+cwebster-99@users.noreply.github.com>
Date: Thu, 17 Apr 2025 15:09:38 +0000
Subject: [PATCH 06/12] Add python project button
---
README.md | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 6bddcd72..b575c03d 100644
--- a/README.md
+++ b/README.md
@@ -56,7 +56,13 @@ The extension uses `pip` as the default package manager, but you can use the pac
| ms-python.python:pip | `pip` | Pip acts as the default package manager and it's typically built-in to Python. |
| 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/). |
-### Project Creation
+### Project Creation and Management
+
+The Python Environments extension allows you to assign additional files or folders to various environments. Using `Add Python Project` in the Python Projects view you can:
+
+- Add existing projects : Allows you to select a file or folder that is currently in your VS Code workspace
+- Auto find projects: Searches for folders in your VS Code workspace with `pyproject.toml` and other setup files
+- Create new project: Create a new project from scratch
The **Python: Create Project** command simplifies the process of starting a new Python project by scaffolding it for you. Whether in a new workspace or an existing one, this command sets up the necessary environment and files, so you donβt have to worry about the initial setup, and only the code you want to write.
From e2093b3b92019a74942a34713530bef619bc1ed0 Mon Sep 17 00:00:00 2001
From: Courtney Webster <60238438+cwebster-99@users.noreply.github.com>
Date: Thu, 17 Apr 2025 15:13:28 +0000
Subject: [PATCH 07/12] Introducing the folds
---
README.md | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/README.md b/README.md
index b575c03d..34dce186 100644
--- a/README.md
+++ b/README.md
@@ -15,6 +15,10 @@ The Python Environments extension for VS Code helps you manage Python environmen
## Features
+The "Python Projects" fold shows you all of the projects that are currently in your workspace and their selected environments. From this view you can add more files or folders as projects, select a new environment for your project, and manage your selected environments.
+
+The "Environment Managers" fold shows you all of the environment managers that are available on your machine with all related environments nested below. From this view, you can create new environments, delete old environments, and manage packages.
+
width=734 height=413>
### Environment Management
From b2fb5f43c1e71fafa2f374fcfb6d93e18c210555 Mon Sep 17 00:00:00 2001
From: Courtney Webster <60238438+cwebster-99@users.noreply.github.com>
Date: Tue, 29 Apr 2025 20:24:40 +0000
Subject: [PATCH 08/12] Pulling in fresh updates
---
README.md | 31 +++++++-------------
images/environment-managers-quick-start.png | Bin 0 -> 147715 bytes
2 files changed, 10 insertions(+), 21 deletions(-)
create mode 100644 images/environment-managers-quick-start.png
diff --git a/README.md b/README.md
index 34dce186..f21999ed 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ The Python Environments extension for VS Code helps you manage Python environmen
## Features
-The "Python Projects" fold shows you all of the projects that are currently in your workspace and their selected environments. From this view you can add more files or folders as projects, select a new environment for your project, and manage your selected environments.
+The "Python Projects" fold shows you all of the projects that are currently in your workspace and their selected environments. From this view you can add more files or folders as projects, select a new environment for your project, and manage your selected environments.
The "Environment Managers" fold shows you all of the environment managers that are available on your machine with all related environments nested below. From this view, you can create new environments, delete old environments, and manage packages.
@@ -25,7 +25,7 @@ The "Environment Managers" fold shows you all of the environment managers that a
The Python Environments panel provides an interface to create, delete and manage environments.
-![ADD A QUICK REFERENCE FOR UI BUTTON]()
+
width=734 height=413>
To simplify the environment creation process, you can use "Quick Create" to automatically create a new virtual environment using:
@@ -35,8 +35,6 @@ To simplify the environment creation process, you can use "Quick Create" to auto
For more control, you can create a custom environment where you can specify Python version, environment name, packages to be installed, and more!
-![Gif showing environment creation using Quick Create.]()
-
The following environment managers are supported out of the box:
| Id | Name | Description |
@@ -51,8 +49,6 @@ Environment managers are responsible for specifying which package manager will b
The extension also provides an interface to install and uninstall Python packages, and provides APIs for extension developers to contribute package managers of their choice.
-![ADD A QUICK REFERENCE PICTURE FOR BUTTONS]()
-
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:
| Id | Name | Description|
@@ -60,24 +56,18 @@ The extension uses `pip` as the default package manager, but you can use the pac
| ms-python.python:pip | `pip` | Pip acts as the default package manager and it's typically built-in to Python. |
| 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/). |
-### Project Creation and Management
-
-The Python Environments extension allows you to assign additional files or folders to various environments. Using `Add Python Project` in the Python Projects view you can:
-
-- Add existing projects : Allows you to select a file or folder that is currently in your VS Code workspace
-- Auto find projects: Searches for folders in your VS Code workspace with `pyproject.toml` and other setup files
-- Create new project: Create a new project from scratch
-
-The **Python: Create Project** command simplifies the process of starting a new Python project by scaffolding it for you. Whether in a new workspace or an existing one, this command sets up the necessary environment and files, so you donβt have to worry about the initial setup, and only the code you want to write.
+## Project Management
-![Gif showing project creation using the `Python: Create Project` command for a Python package.]()
+A "Python Project" can be a file or folder that contains runnable Python code. With the Python Environments extension, you can add files and folders as projects and assign individual environments to them.
-#### Types of Projects
+Projects can be added via the Python Environments pane or in the File Explorer by right-clicking on the folder/file and selecting the "Add as Python Project" menu item.
-The `Python: Create Project` command supports the following project types:
+There are a couple of ways that you can add a Python Project from the Python Environments panel:
-- Package: A structured Python package with files like `__init__.py` and setup configurations.
-- Generic script: A simple project for standalone Python scripts, ideal for quick tasks or just to get you started.
+| Name | Description |
+| ----- | ---------- |
+| Add Existing | Allows you to add an existing folder from the file explorer. |
+| Auto find | Searches for folders that contain `pyproject.toml` or `setup.py` files |
## Command Reference
@@ -85,7 +75,6 @@ The `Python: Create Project` command supports the following project types:
| -------- | ------------- |
| Python: Create Environment | Create a virtual environment using your preferred environment manager preconfigured with "Quick Create" or configured to your choices. |
| Python: Manage Packages | Install and uninstall packages in a given Python environment. |
-| Python: Create Project | Creates a scaffolded Python project with a virtual environment. |
| Python: Activate Environment in Current Terminal | Activates the currently opened terminal with a particular environment. |
| Python: Deactivate Environment in Current Terminal | Deactivates environment in currently opened terminal. |
| Python: Run as Task | Runs Python module as a task. |
diff --git a/images/environment-managers-quick-start.png b/images/environment-managers-quick-start.png
new file mode 100644
index 0000000000000000000000000000000000000000..c36f1f390e00b9c5be5eef782a3c8950b7f8cf11
GIT binary patch
literal 147715
zcmce;WmH_-5-r>W3$DQ>L4pK_;O?#o1cJM}1r6@*?ht~z(**0_P6xN(9^BvNo_o%@
zf4=Y68!uxto$kGR^^&T&s^+TMVake9Xvjp!AP@*mMp|4I1cK`VfnJonL;&8=w_;TU
zo?x6*r9?rMqa?e)3pg_o1rZRaCI;o+03LXaWG}7h1OnkvKR;k(RH;rtpr;}kagh)1
zx(7>NytHS&TtAKJnCjKbCA-P}>8$yL5DA|;f=-oK&W&U<#fjD@Gey2qEc`--<#Y8E
z2cyNyLWQYfVfmMgGT}9I)(kMZHE6#OKF7O#j&F!I1rOaku*O&Sw*_bppN;Orjdg4<
zw>WJ_n{K6T^Gm78(gk9QzI^l7A8xtb8NR5a0~
z6C0Ez(AE6WF2}qTuE~Dp2A~Z&@;`p_l66(%=?pQs Y05`Q|3QURGJ0KUAo2t7rbKrhlvJA&{a(
z)Wegc(jE5_ux5%pP?5*Gnj->cJGqIB+S5%FCCgp7MlR{&<~jLH2dtcy^A}9bJBDvR
z0Gv#$;h?M>9V262eLdBc7Cl{FeRCj%9fGeTq8;avk&zlQgsA&lm|C;_5$gBga~-(}
zQDiw;+6vmS!;-?l_;}U9cSB(wwckj`rU+1KC{-buXAl-AZJs#&RC5tl_`V`woi;0D
zCRLFO4D#1r$4Lj~GRqgf4qsUbOBN7!lPqZSdXZ=0)V#GGk?J-l{#J>!KX#o>He%?O
zOpLAwaJ*zZ74@Arxe(0`A7Z |U11yu7r*Fjya_&y20wgMz4{P!n4pyxk8`|J+u
z;$Qu?b4yFZfP#EWD=R=N#kbDGO$wAAn+4X|aM*$BOy9o8*BP17&>q~}j?(YOWNzIz
zB(L~1iNrm}up=1$ebi{Z{9VgIxLnJ9` SW>UZ9cttHjN%
zZLN!7Kle`bf$+b%dYSpQ_A)62Fhc)l(R1rza>AW&ZS;*U{5D3pWv=5SA~sXTSiGFh
zPY$Vmlq-ii_6VHt7z1q)(RPXZw2fK?N=vjV!i)}4ST!MW$;iP$)$n0fw%vwm&s#FC
zBipQU5e_jmbC{Be4}&{(XFhfJ
z&sJoSm1H||aw70vrbYJRY@OA+lg;D7v*m13pdh1(118gC;Jj$We01$DG9mP8k~jh@
zg6~`lJ`puWRbV0nTC#Rt@|_!9i~FnHDvBaOqU+-
i+