diff --git a/README.md b/README.md index 05ab421..148b5c2 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,56 @@ # Mypy extension for Visual Studio Code -A Visual Studio Code extension with support for the `mypy` linter. The extension ships with `mypy=1.6.1`. +A Visual Studio Code extension with support for the Mypy type checker. This extension ships with `mypy=1.6.1`. -For more information on `mypy`, see https://www.mypy-lang.org/. +> **Note**: The minimum version of Mypy this extension supports is `1.0.0`. -Note: +This extension supports all [actively supported versions](https://devguide.python.org/#status-of-python-branches) of the Python language (i.e., Python >= 3.8). -- This extension is supported for all [actively supported versions](https://devguide.python.org/#status-of-python-branches) of the `python` language (i.e., Python >= 3.8). -- Minimum supported version of `mypy` is `1.0.0`. +For more information on Mypy, see https://www.mypy-lang.org/ -## Usage +## Usage and Features -Once installed in Visual Studio Code, mypy will be automatically executed when you open a Python file. +The Mypy extension provides a series of features to help your productivity while working with Python code in Visual Studio Code. Check out the [Settings section](#settings) for more details on how to customize the extension. -If you want to disable mypy, you can [disable this extension](https://code.visualstudio.com/docs/editor/extension-marketplace#_disable-an-extension) per workspace in Visual Studio Code. +- **Integrated type checking**: Once this extension is installed in Visual Studio Code, Mypy will be automatically executed when you open a Python file, reporting any errors or warnings in the "Problems" window. +- **Customizable Mypy version**: By default, this extension uses the version of Mypy that is shipped with the extension. However, you can configure it to use a different binary installed in your environment through the `mypy-type-checker.importStrategy` setting, or set it to a custom Mypy executable through the `mypy-type-checker.path` settings. +- **Workspace-wide type checking**: By default, this extension will only report errors and warnings for files open in the editor. However, you can configure it to report errors and warnings for the entire workspace through the `mypy-type-checker.reportingScope` setting. +- **Mono repo support**: If you are working with a mono repo, you can configure the extension offer type checking for Python files in subfolders of the workspace root folder by setting the `mypy-type-checker.cwd` setting to `${fileDirname}`. You can also set it to ignore/skip type checking for certain files or folder paths by specifying a glob pattern to the `mypy-type-checker.ignorePatterns` setting. +- **Customizable linting rules**: You can customize the severity of specific Mypy error codes through the `mypy-type-checker.severity` setting. +- **Mypy Daemon support**: This extension supports the Mypy daemon (`dmypy`) for faster type checking when the reporting scope is set to the entire workspace. To enable it, set the `mypy-type-checker.preferDaemon` setting to `true`. + +### Disabling Mypy + +You can skip type checking with Mypy for specific files or directories by setting the `mypy-type-checker.ignorePatterns` setting. + +If you wish to disable Mypy for your entire workspace or globally, you can [disable this extension](https://code.visualstudio.com/docs/editor/extension-marketplace#_disable-an-extension) in Visual Studio Code. ## Settings -| Settings | Default | Description | -| ----------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| mypy-type-checker.args | `[]` | Custom arguments passed to `mypy`. E.g `"mypy-type-checker.args" = ["--config-file="]` | -| mypy-type-checker.cwd | `${workspaceFolder}` | This setting specifies the working directory for `mypy`. By default, it uses the root directory of the workspace `${workspaceFolder}`. If you want `mypy` to operate within the directory of the file currently being linted, you can set this to `${fileDirname}`. | -| mypy-type-checker.severity | `{ "error": "Error", "note": "Information" }` | Controls mapping of severity from `mypy` to VS Code severity when displaying in the problems window. You can override specific `mypy` error codes `{ "error": "Error", "note": "Information", "name-defined": "Warning" }` | -| mypy-type-checker.path | `[]` | Setting to provide custom `mypy` executable. This will slow down linting, since we will have to run `mypy` executable every time or file save or open. Example 1: `["~/global_env/mypy"]` Example 2: `["conda", "run", "-n", "lint_env", "python", "-m", "mypy"]` | -| mypy-type-checker.interpreter | `[]` | Path to a Python interpreter to use to run the linter server. When set to `[]`, the interpreter for the workspace is obtained from `ms-python.python` extension. If set to some path, that path takes precedence, and the Python extension is not queried for the interpreter. | -| mypy-type-checker.importStrategy | `useBundled` | Setting to choose where to load `mypy` from. `useBundled` picks mypy bundled with the extension. `fromEnvironment` uses `mypy` available in the environment. | -| mypy-type-checker.showNotifications | `off` | Setting to control when a notification is shown. | -| mypy-type-checker.reportingScope | `file` | (experimental) Setting to control if problems are reported for files open in the editor (`file`) or for the entire workspace (`workspace`). | -| mypy-type-checker.preferDaemon | `true` | (experimental) Setting to control how to invoke mypy. If true, `dmypy` is preferred over mypy; otherwise, mypy is preferred. Be aware, that the latter may slow down linting since it requires the `mypy` executable to be run whenever a file is saved or opened. Note that this setting will be overridden if `mypy-type-checker.path` is set. | -| mypy-type-checker.ignorePatterns | `[]` | Glob patterns used to exclude files and directories from being linted. | +There are several settings you can configure to customize the behavior of this extension. + +| Settings | Default | Description | +| -------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| mypy-type-checker.args | `[]` | Arguments passed to Mypy to enable type checking on Python files. Each argument should be provided as a separate string in the array.
Example:
`"mypy-type-checker.args" = ["--config-file="]` | +| mypy-type-checker.severity | `{ "error": "Error", "note": "Information" }` | Mapping of Mypy's message types to VS Code's diagnostic severity levels as displayed in the Problems window. You can also use it to override specific Mypy error codes.
For example: `{ "error": "Error", "note": "Information", "name-defined": "Warning" }` | +| mypy-type-checker.path | `[]` | Path or command to be used by the extension to type check Python files with Mypy. Accepts an array of a single or multiple strings. If passing a command, each argument should be provided as a separate string in the array. If set to `["mypy"]`, it will use the version of Mypy available in the `PATH` environment variable. Note: Using this option may slowdown type checking.
Examples:
- `["~/global_env/mypy"]`
- `["conda", "run", "-n", "lint_env", "python", "-m", "mypy"]` | +| mypy-type-checker.interpreter | `[]` | Path to a Python executable or a command that will be used to launch the Mypy server and any subprocess. Accepts an array of a single or multiple strings. When set to `[]`, the extension will use the path to the selected Python interpreter. If passing a command, each argument should be provided as a separate string in the array. | +| mypy-type-checker.importStrategy | `useBundled` | Defines which Mypy binary to be used to type check Python files. When set to `useBundled`, the extension will use the Mypy binary that is shipped with the extension. When set to `fromEnvironment`, the extension will attempt to use the Mypy binary and all dependencies that are available in the currently selected environment. Note: If the extension can't find a valid Mypy binary in the selected environment, it will fallback to using the Mypy binary that is shipped with the extension. Note: The `mypy-type-checker.path` setting takes precedence and overrides the behavior of `mypy-type-checker.importStrategy`. | + +| mypy-type-checker.showNotifications | `off` | Controls when notifications are shown by this extension. Accepted values are `onError`, `onWarning`, `always` and `off`. | + +| mypy-type-checker.reportingScope | `file` | (experimental) Controls the scope of Mypy's problem reporting. If set to `file`, Mypy will limit its problem reporting to the files currently open in the editor. If set to `workspace``, Mypy will extend its problem reporting to include all files within the workspace. | +| mypy-type-checker.preferDaemon | true | (experimental) Whether the Mypy daemon (`dmypy`) will take precedence over `mypy`for type checking. Note: if `mypy-type-checker.reportingScope`is set to `workspace`, enabling the Mypy daemon will offer a faster type checking experience. This setting will be overridden if `mypy-type-checker.path`is set. | +| mypy-type-checker.ignorePatterns |`[]` | Configure [glob patterns](https://code.visualstudio.com/docs/editor/glob-patterns) to exclude files or folders from being type checked by Mypy. | + +The following variables are supported for substitution in the `mypy-type-checker.args`, `mypy-type-checker.cwd`, `mypy-type-checker.path`, `mypy-type-checker.interpreter` and `mypy-type-checker.ignorePatterns` settings: + +- `${workspaceFolder}` +- `${workspaceFolder:FolderName}` +- `${userHome}` +- `${env:EnvVarName}` + +The `mypy-type-checker.path` setting also supports the `${interpreter}` variable as one of the entries of the array. This variable is subtituted based on the value of the `mypy-type-checker.interpreter` setting. ## Commands @@ -38,4 +60,21 @@ If you want to disable mypy, you can [disable this extension](https://code.visua ## Logging -From the command palette (View > Command Palette ...), run the `Developer: Set Log Level...` command. From the quick pick menu, select `Mypy Type Checker` extension from the `Extension logs` group. Then select the log level you want to set. +From the Command Palette (**View** > **Command Palette ...**), run the **Developer: Set Log Level...** command. Select **Mypy Type Checker** from the **Extension logs** group. Then select the log level you want to set. + +Alternatively, you can set the `mypy-type-checker.trace.server` setting to `verbose` to get more detailed logs from the Mypy server. This can be helpful when filing bug reports. + +To open the logs, click on the language status icon (`{}`) on the bottom right of the Status bar, next to the Python language mode. Locate the **Mypy Type Checker** entry and select **Open logs**. + +## Troubleshooting + +In this section, you will find some common issues you might encounter and how to resolve them. If you are experiencing any issues that are not covered here, please [file an issue](https://github.com/microsoft/vscode-mypy/issues). + +- If the `mypy-type-checker.importStrategy` setting is set to `fromEnvironment` but Mypy is not found in the selected environment, this extension will fallback to using the Mypy binary that is shipped with the extension. However, if there are dependencies installed in the environment, those dependencies will be used along with the shipped Mypy binary. This can lead to problems if the dependencies are not compatible with the shipped Mypy binary. + + To resolve this issue, you can: + + - Set the `mypy-type-checker.importStrategy` setting to `useBundled` and the `mypy-type-checker.path` setting to point to the custom binary of Mypy you want to use; or + - Install Mypy in the selected environment. + +- If you have the reporting scope set to `workspace` and notice a slowdown in type checking, you can try enabling the Mypy daemon (`dmypy`) by setting the `mypy-type-checker.preferDaemon` setting to `true`. diff --git a/package.nls.json b/package.nls.json index ed08343..152f0f3 100644 --- a/package.nls.json +++ b/package.nls.json @@ -1,22 +1,20 @@ { - "extension.description": "Linting support for Python files using `mypy`.", + "extension.description": "Type checking support for Python files using Mypy.", "command.restartServer": "Restart Server", - "settings.args.description": "Arguments passed in. Each argument is a separate string in the array.", - "settings.cwd.description": "The current working directory used to run `mypy`. To use the directory of the file currently being linted, you can use `${fileDirname}` .", - "settings.severity.description": "Mapping from severity of `mypy` message type to severity shown in problem window.", - "settings.path.description": "When set to a path to `mypy` binary, extension will use that for linting. NOTE: Using this option may slowdown linting.", - "settings.ignorePatterns.description": "Patterns used to exclude files or folders from being linted. Applies to `reportingScope==file` only.", - "settings.importStrategy.description": "Defines where `mypy` is imported from. This setting may be ignored if `mypy-type-checker.path` is set.", - "settings.importStrategy.useBundled.description": "Always use the bundled version of `mypy`.", - "settings.importStrategy.fromEnvironment.description": "Use `mypy` from environment, fallback to bundled version only if `mypy` not available in the environment.", - "settings.interpreter.description": "When set to a path to Python executable, extension will use that to launch the server and any subprocess.", - "settings.preferDaemon.description": "When set to true, `dmypy` is preferred over `mypy`; otherwise, `mypy` is preferred. This setting will be overridden if `mypy-type-checker.path` is set. NOTE: Setting this option to false may slowdown linting.", - "settings.reportingScope.description": "Defines the scope of the problems reported by the extension.", + "settings.args.description": "Arguments passed to Mypy to enable type checking on Python files. Each argument should be provided as a separate string in the array. \n Example: \n `\"mypy-type-checker.args\" = [\"--config-file=\"]`", + "settings.severity.description": "Mapping of Mypy's message types to VS Code's diagnostic severity levels as displayed in the Problems window. You can also use it to override specific Mypy error codes.
For example: `{\"error\": \"Error\", \"note\": \"Information\", \"name-defined\": \"Warning\" }`", + "settings.path.description": "Path or command to be used by the extension to type check Python files with Mypy. Accepts an array of a single or multiple strings. If passing a command, each argument should be provided as a separate string in the array. If set to `[\"mypy\"]`, it will use the version of Mypy available in the `PATH` environment variable. Note: Using this option may slowdown type checking. \n Examples: \n- `[\"~/global_env/mypy\"]` \n- `[\"conda\", \"run\", \"-n\", \"lint_env\", \"python\", \"-m\", \"mypy\"]`", + "settings.importStrategy.description": "defines which Mypy binary to be used to type check Python files. When set to `useBundled`, the extension will use the Mypy binary that is shipped with the extension. When set to `fromEnvironment`, the extension will attempt to use the Mypy binary and all dependencies that are available in the currently selected environment. Note: If the extension can't find a valid Mypy binary in the selected environment, it will fallback to using the Mypy binary that is shipped with the extension. Note: The `mypy-type-checker.path` setting takes precedence and overrides the behavior of `mypy-type-checker.importStrategy`.", + "settings.importStrategy.useBundled.description": "Always use the bundled version of Mypy shipped with the extension.", + "settings.importStrategy.fromEnvironment.description": "Use Mypy from the selected environment. If the extension fails to find a valid Mypy binary, it will fallback to using the bundled version of Mypy.", + "settings.interpreter.description": "Path to a Python executable or a command that will be used to launch the Mypy server and any subprocess. Accepts an array of a single or multiple strings. When set to `[]`, the extension will use the path to the selected Python interpreter. If passing a command, each argument should be provided as a separate string in the array.", + "settings.preferDaemon.description": "Whether the Mypy daemon (`dmypy`) will take precedence over `mypy`for type checking. Note: if `mypy-type-checker.reportingScope`is set to `workspace`, enabling the Mypy daemon will offer a faster type checking experience. This setting will be overridden if `mypy-type-checker.path`is set.", + "settings.reportingScope.description": "Controls the scope of Mypy's problem reporting. If set to `file`, Mypy will limit its problem reporting to the files currently open in the editor. If set to `workspace`, Mypy will extend its problem reporting to include all files within the workspace. ", "settings.reportingScope.file.description": "Problems are reported for the files open in the editor only.", - "settings.reportingScope.workspace.description": "Problems are reported for files in the workspace.", + "settings.reportingScope.workspace.description": "Problems are reported for all files within the workspace.", "settings.showNotifications.description": "Controls when notifications are shown by this extension.", - "settings.showNotifications.off.description": "All notifications are turned off, any errors or warning are still available in the logs.", - "settings.showNotifications.onError.description": "Notifications are shown only in the case of an error.", - "settings.showNotifications.onWarning.description": "Notifications are shown for errors and warnings.", - "settings.showNotifications.always.description": "Notifications are show for anything that the server chooses to show." + "settings.showNotifications.off.description": "Never display a notification. Any errors or warning are still available in the logs.", + "settings.showNotifications.onError.description": "Show notifications for errors.", + "settings.showNotifications.onWarning.description": "Show notifications for errors and warnings.", + "settings.showNotifications.always.description": "Show notifications for errors and warnings." }