diff --git a/docs/python/environments.md b/docs/python/environments.md index 92864538ec..3fc830d060 100644 --- a/docs/python/environments.md +++ b/docs/python/environments.md @@ -8,7 +8,31 @@ MetaSocialImage: images/tutorial/python-social.png An "environment" in Python is the context in which a Python program runs that consists of an interpreter and any number of installed packages. -> **Note**: If you'd like to become more familiar with the Python programming language, review [More Python resources](#more-python-resources). +> **Note**: If you'd like to become more familiar with the Python programming language, review [more Python resources](#more-python-resources). + +## Python Environments extension + +Python environments are managed via the Python Environments extension. The extension provides a dedicated view in the Activity Bar for creating, managing, and switching between environments, as well as installing and uninstalling packages. + +### Python Environments view + +The Python Environments view can be accessed from the Activity Bar and provides a unified interface for managing your Python projects and environments: + +![Python Environments view in the Activity Bar.](/docs/python/images/environments/python-environments-activity-bar.png) + +The view consists of two main sections: + +1. **Python Projects**: Shows all the projects in your workspace and their selected environments. From here you can: + - Add existing folders as Python projects + - Auto-find Python projects in your workspace + - Create new projects from templates + - Select different environments for each project + +2. **Environment Managers**: Shows all available environment managers with their environments. From here you can: + - Create new environments + - Delete environments + - Manage packages + - Activate environments in terminals ## Types of Python environments @@ -30,7 +54,7 @@ A [**virtual environment**](https://docs.python.org/3/glossary.html#term-virtual #### Conda environments -A **conda environment** is a Python environment that's managed using the `conda` package manager (see [Getting started with conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html)).Choosing between conda and virtual environments depends on your packaging needs, team standards, etc. +A **conda environment** is a Python environment that's managed using the `conda` package manager (see [Getting started with conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html)). Choosing between conda and virtual environments depends on your packaging needs, team standards, etc. ### Python environment tools @@ -44,27 +68,39 @@ The following table lists the various tools involved with Python environments: ## Creating environments -### Using the Create Environment command - -To create local environments in VS Code using virtual environments or Anaconda, you can follow these steps: open the Command Palette (`kb(workbench.action.showCommands)`), search for the **Python: Create Environment** command, and select it. +### Quick Create -The command presents a list of environment types: **Venv** or **Conda**. +Quick create allows for a one-click environment creation flow, choosing the defaults for you. Quick create configures a virtual environment using the default environment manager and the latest Python version, and installing dependencies found in a `requirements.txt` or `pyproject.toml` file. -![Create Environment dropdown](images/environments/create_environment_dropdown.png) +1. Open the Python Environments view from the Activity Bar +2. Under "Environment Managers", find your preferred environment manager (e.g., venv) +3. Select the **Create Environment** option +4. Choose **Quick Create** to automatically create a virtual environment using: + - Your default environment manager + - The latest Python version + - Workspace dependencies (if available) -If you are creating an environment using **Venv**, the command presents a list of interpreters that can be used as a base for the new virtual environment. +![Screenshot of the environment creation options for venv.](/docs/python/images/environments/environment-creation-dropdown.png) -![Virtual environment interpreter selection](images/environments/interpreters-list.png) +### Custom environment creation -If you are creating an environment using **Conda**, the command presents a list of Python versions that can be used for your project. +For more control over your environment settings, choose custom environment creation. -![Conda environment Python version selection](images/environments/conda_environment_python_versions.png) +1. Open the Python Environments view from the Activity Bar +2. Under "Environment Managers", find your preferred environment manager +3. Select **Create Environment** +4. Choose **Custom Create** +5. Follow the prompts to specify: + - Python version + - Environment name + - Packages to install + - Additional options specific to your environment manager -After selecting the desired interpreter or Python version, a notification will show the progress of the environment creation and the environment folder will appear in your workspace. +You can continue to create environments in VS Code using the Command Palette (Ctrl/Cmd + Shift + P) and searching for **Python: Create Environment**. ![Create environment status notification](images/environments/create_environment_prompt_status.png) -> **Note**: The command will also install necessary packages outlined in a requirements/dependencies file, such as `requirements.txt`, `pyproject.toml`, or `environment.yml`, located in the project folder. It will also add a `.gitignore` file to the virtual environment to help prevent you from accidentally committing the virtual environment to source control. +> **Note**: The Create Environment command will install packages outlined in a requirements/dependencies file, such as `requirements.txt`, `pyproject.toml`, or `environment.yml`, located in the project folder. It will also add a `.gitignore` file to the virtual environment to help prevent you from accidentally committing the virtual environment to source control. ### Create a virtual environment in the terminal @@ -116,7 +152,20 @@ Additional notes: ### Select and activate an environment -The Python extension tries to find and then select what it deems the best environment for the workspace. If you would prefer to select a specific environment, use the **Python: Select Interpreter** command from the **Command Palette** (`kb(workbench.action.showCommands)`). +The Python extension attempts to find and select what it deems the best environment for the workspace. If you would prefer to select a specific environment, you can do so in one of the following ways: + +#### Using the Python Environments extension + +1. Open the Python Environments view from the Activity Bar +2. Under "Python Projects", find your project +3. Select the current environment to open a dropdown list of available environments +4. Choose the environment you want to use for the project + +Alternatively, under "Environment Managers", you can navigate to any environment and use the "Select" option to choose it for your workspace. + +#### Using the Select Interpreter command + +Use the **Python: Select Interpreter** command from the **Command Palette** (`kb(workbench.action.showCommands)`). ![Python: Select Interpreter command](images/environments/select-interpreters-command.png) diff --git a/docs/python/images/environments/environment-creation-dropdown.png b/docs/python/images/environments/environment-creation-dropdown.png new file mode 100644 index 0000000000..8385230184 --- /dev/null +++ b/docs/python/images/environments/environment-creation-dropdown.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fc3065655dc8ad030ea257ca219df104f3fc26b7c40210c251bd3003bd3a9b82 +size 28521 diff --git a/docs/python/images/environments/python-environments-activity-bar.png b/docs/python/images/environments/python-environments-activity-bar.png new file mode 100644 index 0000000000..a317a9cb48 --- /dev/null +++ b/docs/python/images/environments/python-environments-activity-bar.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6c8231802c8f9294b28f7da5f055062303749edc5f943bd88e394e62d42c396f +size 37359 diff --git a/docs/python/images/environments/selected-interpreter-envs.png b/docs/python/images/environments/selected-interpreter-envs.png new file mode 100644 index 0000000000..f46273242f --- /dev/null +++ b/docs/python/images/environments/selected-interpreter-envs.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9283121a9d91fed23f5de1079f153475bade1c6313768d3741722b3403efc8a8 +size 40392 diff --git a/docs/python/images/quick-start/create-project.png b/docs/python/images/quick-start/create-project.png new file mode 100644 index 0000000000..d9a1622a92 --- /dev/null +++ b/docs/python/images/quick-start/create-project.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4d3e416610c4423d0f69bc2d472ff93a5cc946fcafa1658180e35f28e9ebf301 +size 9888 diff --git a/docs/python/images/quick-start/updated-ui-tour.png b/docs/python/images/quick-start/updated-ui-tour.png new file mode 100644 index 0000000000..61dd607513 --- /dev/null +++ b/docs/python/images/quick-start/updated-ui-tour.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:d7659e9484aa1b7c11b38d86a91712ef50cd9200f10a4666de0d47cdf722ab0f +size 194202 diff --git a/docs/python/images/tutorial/install-numpy.png b/docs/python/images/tutorial/install-numpy.png new file mode 100644 index 0000000000..f1e06d07c1 --- /dev/null +++ b/docs/python/images/tutorial/install-numpy.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c219d88fac45f3693e4fbb0d8322e100f5c84003941460387c96d2488bca70ed +size 30515 diff --git a/docs/python/images/tutorial/manage-packages.png b/docs/python/images/tutorial/manage-packages.png new file mode 100644 index 0000000000..5ce49ab947 --- /dev/null +++ b/docs/python/images/tutorial/manage-packages.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:46567a67e503dec6f258199af4fc5fc6891b4494db068e34c3c4a6d0dd49ec66 +size 17649 diff --git a/docs/python/images/tutorial/numpy-installed.png b/docs/python/images/tutorial/numpy-installed.png new file mode 100644 index 0000000000..73da1d18e4 --- /dev/null +++ b/docs/python/images/tutorial/numpy-installed.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b28f676781275bd1d0e5c58e47a44b7837720205b7923d3ba55db434de9633a5 +size 22308 diff --git a/docs/python/python-quick-start.md b/docs/python/python-quick-start.md index 1c00a064c0..344c2a3892 100644 --- a/docs/python/python-quick-start.md +++ b/docs/python/python-quick-start.md @@ -22,6 +22,24 @@ To further customize VS Code for Python, you can leverage the [Python profile te ## How to create and open a Python project or file +You can quickly create a scaffolded Python project for scripts or a Python package. + +1. Open the **Python Environments** view from the Activity Bar. + +![Screenshot showing the Python Environments Activity Bar.](/docs/python/images/environments/python-environments-activity-bar.png) + +2. In the "Python Projects" section, select **Add Python Project** and **Create New**. + +![Screenshot showing the UI entry point to add a new python project.](/docs/python/images/quick-start/create-project.png) + +3. Choose from available project templates: + - **Package**: A structured Python package with `__init__.py` and setup configurations. + - **Script**: A simple project for standalone Python scripts. + +4. Follow the prompts to specify the project name, location, and environment settings. + +5. The extension will create the project structure and configure a virtual environment automatically. + If you have an existing Python project you wish to work on in VS Code, you can begin by opening your folder or file from the VS Code Welcome page or File Explorer view, or by selecting **File > Open Folder** (`kb(workbench.action.files.openFolder)`) or **File > Open File** (`kb(workbench.action.files.openFile)`). You can create a new Python file by selecting **New File** on the VS Code Welcome page and then selecting **Python file**, or by navigating to **File > New File** (`kb(workbench.action.files.newFile)`). @@ -32,7 +50,7 @@ You can create a new Python file by selecting **New File** on the VS Code Welcom When you launch VS Code for the very first time, you will need to install the Python extension to get Python-specific features and UI. Let’s look at the UI after installing the Python extension: -![Image of the Python UI highlights in VS Code.](images/quick-start/ui-tour.png) +![Image of the Python UI highlights in VS Code.](images/quick-start/updated-ui-tour.png) ## Code Actions diff --git a/docs/python/python-tutorial.md b/docs/python/python-tutorial.md index 079451090f..c8ce6fd421 100644 --- a/docs/python/python-tutorial.md +++ b/docs/python/python-tutorial.md @@ -81,25 +81,29 @@ Alternately, you can create a folder through the operating system UI, then use V ## Create a virtual environment -A best practice among Python developers is to use a project-specific `virtual environment`. Once you activate that environment, any packages you then install are isolated from other environments, including the global interpreter environment, reducing many complications that can arise from conflicting package versions. You can create non-global environments in VS Code using Venv or Anaconda with **Python: Create Environment**. +A best practice among Python developers is to use a project-specific `virtual environment`. Once you activate that environment, any packages you then install are isolated from other environments, including the global interpreter environment, reducing many complications that can arise from conflicting package versions. -Open the Command Palette (`kb(workbench.action.showCommands)`), start typing the **Python: Create Environment** command to search, and then select the command. +### Using the Python Environments extension -The command presents a list of environment types, Venv or Conda. For this example, select **Venv**. +The Python Environments extension provides a dedicated interface for managing environments. To create a virtual environment: -![Create Environment dropdown](images/environments/create_environment_dropdown.png) +1. Open the Python Environments view from the Activity Bar on the left side of VS Code. -The command then presents a list of interpreters that can be used for your project. Select the interpreter you installed at the beginning of the tutorial. +![Screenshot of the Python Environments panel from the Activity Bar.](/docs/python/images/environments/python-environments-activity-bar.png) -![Virtual environment interpreter selection](images/environments/interpreters-list.png) +2. Under "Environment Managers", select the `+` next to your preferred environment manager (such as Venv). -After selecting the interpreter, a notification will show the progress of the environment creation and the environment folder (`/.venv`) will appear in your workspace. +3. Select the **Quick Create** option which automatically creates a new virtual environment using your default environment manager and the latest Python version. -![Create environment status notification](images/environments/create_environment_prompt_status.png) + ![Screenshot of the environment creation options for venv.](/docs/python/images/environments/environment-creation-dropdown.png) -Ensure your new environment is selected by using the **Python: Select Interpreter** command from the **Command Palette**. +4. A notification will show the progress of the environment creation and the environment folder (`/.venv`) will appear in your workspace. -![Select an Interpreter](images/tutorial/interpreter-venv.png) + ![Create environment status notification](images/environments/create_environment_prompt_status.png) + +5. Once created, your new environment will be available in the list and automatically selected for your workspace. + + ![Select an Interpreter](/docs/python/images/environments/selected-interpreter-envs.png) > **Note**: For additional information about virtual environments, or if you run into an error in the environment creation process, see [Environments](/docs/python/environments.md#creating-environments). @@ -233,13 +237,31 @@ print(np.random.randint(1,9)) Next, run the file in the debugger using the "Python: Current file" configuration as described in the last section. -You should see the message, **"ModuleNotFoundError: No module named 'numpy'"**. This message indicates that the required package isn't available in your interpreter. If you're using an Anaconda distribution or have previously installed the `numpy` package you may not see this message. +You should see the message, **"ModuleNotFoundError: No module named 'numpy'"**. This message indicates that the required package isn't available in your interpreter. If you're using an Anaconda distribution or have previously installed the `numpy` package you may not see this message. Before proceeding, stop the debugger. + +Installing Python packages can be done fully within the UI. + +1. Open the **Python Environments** view from the Activity Bar. + +2. Locate your active environment under "Environment Managers". + +3. Expand your environment and the **Packages** node to view packages currently available in your environment. Select the package icon on the environment. + +![Screenshot of UI entry point for package management.](/docs/python/images/tutorial/manage-packages.png) + +4. Select **Search common PyPI packages** and search for and select `numpy`. + +![Screenshot of package installation UI.](/docs/python/images/tutorial/install-numpy.png) + +5. Once installed, the package will appear in your environment's package list. + +![Screenshot showing numpy installed in the virtual environment.](/docs/python/images/tutorial/numpy-installed.png) -To install the `numpy` package, stop the debugger and use the Command Palette to run **Terminal: Create New Terminal** (`kb(workbench.action.terminal.new)`). This command opens a command prompt for your selected interpreter. +### Using the terminal to install packages -To install the required packages in your virtual environment, enter the following commands as appropriate for your operating system: +Alternatively, you can install packages using the terminal: -1. Install the packages +Install the required packages in your virtual environment, entering the following commands as appropriate for your operating system: ```bash # Don't use with Anaconda distributions because they include matplotlib already. @@ -255,7 +277,39 @@ To install the required packages in your virtual environment, enter the followin python3 -m pip install numpy ``` -1. Now, rerun the program, with or without the debugger, to view the output! +3. Now, rerun the program, with or without the debugger, to view the output! + +### Managing dependencies across environments + +When working on Python projects, it's essential to manage your dependencies effectively. One useful tip is to use the `pip freeze > requirements.txt` command. This command helps you create a `requirements.txt` file that lists all the packages installed in your virtual environment. This file can then be used to recreate the same environment elsewhere. + +Follow these steps to create a `requirements.txt` file: + +1. Activate your virtual environment, if you haven't already. + + ```bash + source venv/bin/activate # On macOS/Linux + ``` + + ```powershell + .\venv\Scripts\activate # On Windows + ``` + +2. Generate the `requirements.txt` file. + + ```powershell + pip freeze > requirements.txt + ``` + +You can now use the newly generated `requirements.txt` file to install dependencies in another environment. Furthermore, you can continue to add dependencies to it as your project may grow in complexity. + + ```powershell + pip install -r requirements.txt + ``` + +By following these steps, you ensure that your project dependencies are consistent across different environments, making it easier to collaborate with others and deploy your project. + +Congrats on completing the Python tutorial! During the course of this tutorial, you learned how to create a Python project, create a virtual environment, run and debug your Python code, and install Python packages. Explore additional resources to learn how to get the most out of Python in Visual Studio Code! ### Managing dependencies across environments When working on Python projects, it’s essential to manage your dependencies effectively. One useful tip is to use the `pip freeze > requirements.txt` command. This command helps you create a `requirements.txt` file that lists all the packages installed in your virtual environment. This file can then be used to recreate the same environment elsewhere. diff --git a/docs/python/settings-reference.md b/docs/python/settings-reference.md index 6928893c26..762a92ef54 100644 --- a/docs/python/settings-reference.md +++ b/docs/python/settings-reference.md @@ -1,5 +1,4 @@ --- -ContentId: d256dc5c-95e9-4c02-a82f-947bf34a3517 DateApproved: 3/6/2023 MetaDescription: Settings Reference for the Python extension in Visual Studio Code MetaSocialImage: images/tutorial/python-social.png @@ -30,6 +29,16 @@ For general information about working with settings in VS Code, refer to [User a | terminal.launchArgs | `[]` | Launch arguments that are given to the Python interpreter when you run a file using commands such as **Python: Run Python File in Terminal**.
In the `launchArgs` list, each item is a top-level command-line element that's separated by a space (quoted values that contain spaces are a single top-level element and are thus one item in the list).
For example, for the arguments `--a --b --c {"value1" : 1, "value2" : 2}`, the list items should be `["--a", "--b", "--c", "{\"value1\" : 1, \"value2\" : 2}\""]`.
Note that VS Code ignores this setting when debugging because it instead uses arguments from your selected debugging configuration in `launch.json`. | | venvFolders | `[]` | Paths to folders where virtual environments are created.
Depending on the virtualization tool used, it can be the project itself: `${workspaceFolder}`, or separate folders for all virtual environments located side by side: `.\envs`, `~/.virtualenvs`, and so on. | +## Python Environments extension settings + +| 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. | +| pythonProjects | `[]` | A list of Python workspaces, specified by the path, in which you can set particular environment and package managers. Format: `[{"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.autoActivationType | `"command"` | Specifies how the extension can activate an environment in a terminal. Using 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. | + ## Debugger Settings ### General debugging