From 929ed7466a067e52a9f032814afde959a62f6a28 Mon Sep 17 00:00:00 2001 From: luabud Date: Fri, 3 Mar 2023 17:35:53 -0800 Subject: [PATCH 1/4] Update settings references --- docs/python/editing.md | 21 ++++----------------- docs/python/settings-reference.md | 22 +++++----------------- 2 files changed, 9 insertions(+), 34 deletions(-) diff --git a/docs/python/editing.md b/docs/python/editing.md index 8f62aa53be..aba9e66c49 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,15 @@ 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. - -Invoked by: +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. +You can invoke this command through: - Right-click in editor and select **Sort Imports** (no selection is required) -- Command Palette (`kb(workbench.action.showCommands)`), then **Python Refactor: Sort Imports** +- Command Palette (`kb(workbench.action.showCommands)`), then **Organize Imports** - Assign a keyboard shortcut to the `python.sortImports` 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..d5fafbcb11 100644 --- a/docs/python/settings-reference.md +++ b/docs/python/settings-reference.md @@ -24,12 +24,13 @@ 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. | ## Code analysis settings @@ -68,6 +69,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. Accepted values in this list are `source.unusedImports` to remove all unused imports in the open file, and `source.convertImportFormat` to convert the imports according to the `python.analysis.importFormat` setting. | +| logLevel | `Error` | Specifies the level of logging to be performed by the language server.
The possible levels of logging, in increasing level of information provided, are `Error`, `Warning`, `Information`, and `Trace`.| **Diagnostic severity rules** @@ -132,14 +135,6 @@ This section details all the available rules that can be customized using the `p | reportUnsupportedDunderAll | Diagnostics for unsupported operations performed on `__all__`. | | reportUnusedCoroutine | Diagnostics for call expressions that return a Coroutine and whose results are not consumed. | -#### Jedi Language Server - -The language server settings apply when `python.languageServer` is `Jedi`. -| Setting | Default | Description | -| --- | --- | --- | -| jediPath | `""` | Path to folder containing the Jedi library (folder should contain a `jedi` subfolder). | -| jediMemoryLimit | 0 | Memory limit for the Jedi completion engine in megabytes. Zero (the default) means 1024 MB. -1 disables the memory limit check. | - ## AutoComplete settings | Setting
(python.autoComplete.) | Default | Description | See also | @@ -158,13 +153,6 @@ The language server settings apply when `python.languageServer` is `Jedi`. | yapfPath | `"yapf"` | Path to yapf | [Editing - Formatting](/docs/python/editing.md#formatting) | | yapfArgs| `[]` | Arguments for yapf, where each top-level element that's separated by a space is a separate item in the list. | [Editing - Formatting](/docs/python/editing.md#formatting) | -## Refactoring - Sort Imports settings - -| Setting
(python.sortImports.) | Default | Description | See also | -| --- | --- | --- | --- | -| path | `""` | Path to isort script | [Editing - Refactoring - Sort Imports](/docs/python/editing.md#sort-imports) | -| args | `[]` | Arguments for isort, each argument as a separate item in the array. | [Editing - Refactoring - Sort Imports](/docs/python/editing.md#sort-imports) | - ## Linting settings ### General linting From 8f8d8e2978651fff865ab0ce3bb1e2a410da15cf Mon Sep 17 00:00:00 2001 From: luabud Date: Fri, 3 Mar 2023 17:44:34 -0800 Subject: [PATCH 2/4] Minor tweaks --- docs/python/editing.md | 8 +++----- docs/python/settings-reference.md | 2 +- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/python/editing.md b/docs/python/editing.md index aba9e66c49..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** and **Rename Module**. It also supports extensions that implement additional refactoring features such as **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 @@ -198,10 +198,8 @@ To customize which references need to be updated, you can toggle the checkboxes 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. -You can invoke this command through: -- Right-click in editor and select **Sort Imports** (no selection is required) -- Command Palette (`kb(workbench.action.showCommands)`), then **Organize 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) diff --git a/docs/python/settings-reference.md b/docs/python/settings-reference.md index d5fafbcb11..78a3bbae17 100644 --- a/docs/python/settings-reference.md +++ b/docs/python/settings-reference.md @@ -69,7 +69,7 @@ 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. Accepted values in this list are `source.unusedImports` to remove all unused imports in the open file, and `source.convertImportFormat` to convert the imports according to the `python.analysis.importFormat` setting. | +| fixAll | `[]` | A list of code actions to run when running the **Fix All** command.
Accepted values in this list are `source.unusedImports` to remove all unused imports in the open file, and `source.convertImportFormat` to convert the imports according to the `python.analysis.importFormat` setting. | | logLevel | `Error` | Specifies the level of logging to be performed by the language server.
The possible levels of logging, in increasing level of information provided, are `Error`, `Warning`, `Information`, and `Trace`.| **Diagnostic severity rules** From 1db995beb981bea58814a1bc5aed55e9ae179cfb Mon Sep 17 00:00:00 2001 From: Luciana Abud <45497113+luabud@users.noreply.github.com> Date: Mon, 6 Mar 2023 14:46:34 -0800 Subject: [PATCH 3/4] Address review comments --- docs/python/settings-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/python/settings-reference.md b/docs/python/settings-reference.md index 78a3bbae17..82dc87cb48 100644 --- a/docs/python/settings-reference.md +++ b/docs/python/settings-reference.md @@ -69,7 +69,7 @@ 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.
Accepted values in this list are `source.unusedImports` to remove all unused imports in the open file, and `source.convertImportFormat` to convert the imports according to the `python.analysis.importFormat` setting. | +| 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: