diff --git a/docs/python/editing.md b/docs/python/editing.md index 8f62aa53be..d30e505504 100644 --- a/docs/python/editing.md +++ b/docs/python/editing.md @@ -168,7 +168,7 @@ If formatting fails, check the following possible causes: ## Refactoring -The Python extension adds the following refactoring functionalities: **Extract Variable**, **Extract Method**, **Rename Module**, and **Sort Imports**. +The Python extension adds the following refactoring functionalities: **Extract Variable**, **Extract Method** and **Rename Module**. It also supports extensions that implement additional refactoring features such as **Sort Imports**. ### Extract Variable @@ -196,28 +196,13 @@ To customize which references need to be updated, you can toggle the checkboxes ### Sort Imports -Sort Imports uses the isort package to consolidate specific imports from the same module into a single `import` statement and to organize `import` statements in alphabetical order. +The Python extension supports extensions such as [isort](https://marketplace.visualstudio.com/items?itemName=ms-python.isort) and [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) that implement the **Sort Imports** functionality. This command consolidates specific imports from the same module into a single `import` statement, and organizes `import` statements in alphabetical order. -Invoked by: - -- Right-click in editor and select **Sort Imports** (no selection is required) -- Command Palette (`kb(workbench.action.showCommands)`), then **Python Refactor: Sort Imports** -- Assign a keyboard shortcut to the `python.sortImports` command +You can invoke this by opening the command Palette (`kb(workbench.action.showCommands)`) and running **Organize Imports**. +> **Tip**: you can assign a keyboard shortcut to the `editor.action.organizeImports` command. ![Sorting import statements](images/editing/sortImports.gif) -Custom arguments to isort are specified in the `python.sortImports.args` setting, where each top-level element, as separated by spaces on the command line, is a separate item in the array: - -```json -"python.sortImports.args": ["-rc", "--atomic"], -``` - -To use a custom isort script, use the `python.sortImports.path` setting to specify the path. - -Further configurations can be stored in an `.isort.cfg` file as documented on [isort configuration](https://pycqa.github.io/isort/docs/configuration/config_files.html). - -> **Note**: For those migrating from isort4 to isort5, some CLI flags and config options have changed, refer to the project's [isort5 upgrade guide](https://pycqa.github.io/isort/docs/upgrade_guides/5.0.0.html). - ## Next steps - [Linting](/docs/python/linting.md) - Enable, configure, and apply various Python linters. diff --git a/docs/python/settings-reference.md b/docs/python/settings-reference.md index 9edad762bf..b09dec250e 100644 --- a/docs/python/settings-reference.md +++ b/docs/python/settings-reference.md @@ -24,13 +24,15 @@ For general information about working with settings in VS Code, refer to [User a | pipenvPath | `"pipenv"` | Path to the pipenv executable to use for activation. | | 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. | | envFile | `"${workspaceFolder}/`
`.env"` | Absolute path to a file containing environment variable definitions.
See [Configuring Python environments - environment variable definitions file](/docs/python/environments.md#environment-variable-definitions-file). | -| globalModuleInstallation | `false` | Specifies whether to install packages for the current user only using the `--user` command-line argument (the default), or to install for all users in the global environment (when set to `true`). Ignored when using a virtual environment.
For more information on the `--user`argument, see [pip - User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs). | +| globalModuleInstallation | `false` | Specifies whether to install packages for the current user only using the `--user` command-line argument (the default), or to install for all users in the global environment (when set to `true`). Ignored when using a virtual environment.
For more information on the `--user` argument, see [pip - User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs). | | poetryPath | `"poetry"` | Specifies the location of the [Poetry dependency manager](https://poetry.eustace.io/) executable, if installed. The default value `"poetry"` assumes the executable is in the current path.
The Python extension uses this setting to install packages when Poetry is available and there's a `poetry.lock` file in the workspace folder. | -| 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 Visual Studio code ignores this setting when debugging because it instead uses arguments from your selected debugging configuration in `launch.json`. | +| 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`. | | terminal.executeInFileDir | `false` | Indicates whether to run a file in the file's directory instead of the current folder. | | terminal.activateEnvironment | `true` | Indicates whether to automatically activate the environment you select using the **Python: Select Interpreter** command when a new terminal is created.
For example, when this setting is `true` and you select a virtual environment, the extension automatically runs the environment's *activate* command when creating a new terminal (`source env/bin/activate` on macOS/Linux; `env\scripts\activate` on Windows). | | terminal.activateEnvInCurrentTerminal | `false` | Specifies whether to activate the currently open terminal when the Python extension is activated, using the virtual environment selected. | +| terminal.focusAfterLaunch | `false` | Whether to switch the cursor focus to the terminal when launching a Python terminal. | | logging.level| `error` | Specifies the level of logging to be performed by the extension.
The possible levels of logging, in increasing level of information provided, are `off`, `error`, `warn`, `info`, and `debug`.
When set to `off`, which is not recommended, basic information will still be shown such as startup information and commands run by the Python extension.
At the `error` level, basic information and errors will be shown.
At the `warn` level, basic, error, and warning information will be shown. At the `info` level, basic, error, warning, and additional information like method execution times and return values will be shown. At this time, the `debug` level doesn't display additional information. | +| experiments.enabled | `true` | Enables [A/B experiments in the Python extension](https://aka.ms/AAjvt9q). If enabled, you may get included in proposed enhancements and/or features. | ## Code analysis settings @@ -68,6 +70,8 @@ The language server settings apply when `python.languageServer` is `Pylance` or | inlayHints.functionReturnTypes | false | Whether to display inlay hints for function return types. Accepted values are `true` or `false`. | | inlayHints.pytestParameters | false | Whether to display inlay hints for pytest fixture argument types. Accepted values are `true` or `false`. | | diagnosticSeverityOverrides | {} | Allows a user to override the severity levels for individual diagnostics.
For each rule, the available severity levels are `error` (red squiggle), `warning` (yellow squiggle), `information` (blue squiggle), and `none` (rule disabled).
For information about the keys to use for the diagnostic severity rules, see the **Diagnostic severity rules** section below. | +| fixAll | `[]` | A list of code actions to run when running the **Fix All** command or the `source.fixAll` code action.
Accepted values in this list: