|
2 | 2 |
|
3 | 3 | A Visual Studio Code extension with support for the Bandit static analysis tool. |
4 | 4 |
|
5 | | -## Programming Languages and Frameworks |
| 5 | +This extension supports all [actively supported versions](https://devguide.python.org/#status-of-python-branches) of the Python language. |
6 | 6 |
|
7 | | -This extension has two parts, the extension part and language server part. The extension part is written in TypeScript, and language server part is written in Python over the [_pygls_][pygls] (Python language server) library. |
| 7 | +For more information on Bandit, see https://bandit.readthedocs.io/ |
8 | 8 |
|
9 | | -See [Language Server Protocol](https://microsoft.github.io/language-server-protocol). [_pygls_][pygls] currently works on the [version 3.16 of LSP](https://microsoft.github.io/language-server-protocol/specifications/specification-3-16/). |
| 9 | +## Settings |
10 | 10 |
|
11 | | -The TypeScript part handles working with VS Code and its UI. |
| 11 | +There are several settings you can configure to customize the behavior of this extension. |
12 | 12 |
|
13 | | -## Requirements |
| 13 | +| Settings | Default | Description | |
| 14 | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 15 | +| bandit.args | `[]` | Arguments passed to Bandit for linting Python files. Each argument should be provided as a separate string in the array. <br> Examples: <br>- `"bandit.args": ["--severity-level=high"]` <br> - `"bandit.args": ["--skip=B603", "--confidence-level=high"]` | |
| 16 | +| bandit.cwd | `${workspaceFolder}` | Sets the current working directory used to lint Python files with Bandit. By default, it uses the root directory of the workspace `${workspaceFolder}`. You can set it to `${fileDirname}` to use the parent folder of the file being linted as the working directory for Bandit. | |
| 17 | +| bandit.enabled | `true` | Enable/disable linting Python files with Bandit. This setting can be applied globally or at the workspace level. If disabled, the linting server itself will continue to be active and monitor read and write events, but it won't perform linting or expose code actions. | |
| 18 | +| bandit.path | `[]` | "Path or command to be used by the extension to lint Python files with Bandit. 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 `["Bandit"]`, it will use the version of Bandit available in the `PATH` environment variable. Note: Using this option may slowdown linting. <br>Examples: <br>- `"bandit.path" : ["~/global_env/bandit"]` <br>- `"bandit.path" : ["bandit"]` <br>- `"bandit.path" : ["${interpreter}", "-m", "bandit"]` | |
| 19 | +| bandit.interpreter | `[]` | Path to a Python executable or a command that will be used to launch the Bandit 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. | |
| 20 | +| bandit.importStrategy | `useBundled` | Defines which Bandit binary to be used to lint Python files. When set to `useBundled`, the extension will use the Bandit binary that is shipped with the extension. When set to `fromEnvironment`, the extension will attempt to use the Bandit binary and all dependencies that are available in the currently selected environment. Note: If the extension can't find a valid Bandit binary in the selected environment, it will fallback to using the Bandit binary that is shipped with the extension. This setting will be overriden if `bandit.path` is set. | |
| 21 | +| bandit.showNotification | `off` | Controls when notifications are shown by this extension. Accepted values are `onError`, `onWarning`, `always` and `off`. | |
14 | 22 |
|
15 | | -1. VS Code 1.64.0 or greater |
16 | | -1. Python 3.9 or greater |
17 | | -1. node >= 18.17.0 |
18 | | -1. npm >= 8.19.0 ( `npm` is installed with node, check npm version, use `npm install -g [email protected]` to update) |
19 | | -1. Python extension for VS Code |
| 23 | +The following variables are supported for substitution in the `bandit.args`, `bandit.cwd`, `bandit.path`, and `bandit.interpreter` settings: |
20 | 24 |
|
21 | | -You should know to create and work with python virtual environments. |
| 25 | +- `${workspaceFolder}` |
| 26 | +- `${workspaceFolder:FolderName}` |
| 27 | +- `${userHome}` |
| 28 | +- `${env:EnvVarName}` |
22 | 29 |
|
23 | | -## Features of this Template |
| 30 | +The `bandit.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 `bandit.interpreter` setting. |
24 | 31 |
|
25 | | -After finishing the getting started part, this template would have added the following. Assume `<pytool-module>` was replaced with `mytool`, and `<pytool-display-name>` with`My Tool`: |
| 32 | +## Commands |
26 | 33 |
|
27 | | -## Building and Running the extension |
28 | | - |
29 | | -Run the `Debug Extension and Python` configuration form VS Code. That should build and debug the extension in host window. |
30 | | - |
31 | | -Note: if you just want to build you can run the build task in VS Code (`ctrl`+`shift`+`B`) |
32 | | - |
33 | | -## Debugging |
34 | | - |
35 | | -To debug both TypeScript and Python code use `Debug Extension and Python` debug config. This is the recommended way. Also, when stopping, be sure to stop both the Typescript, and Python debug sessions. Otherwise, it may not reconnect to the python session. |
36 | | - |
37 | | -To debug only TypeScript code, use `Debug Extension` debug config. |
38 | | - |
39 | | -To debug a already running server or in production server, use `Python Attach`, and select the process that is running `lsp_server.py`. |
40 | | - |
41 | | -## Logging and Logs |
42 | | - |
43 | | -The template creates a logging Output channel that can be found under `Output` > `Bandit` panel. You can control the log level running the `Developer: Set Log Level...` command from the Command Palette, and selecting your extension from the list. It should be listed using the display name for your tool. You can also set the global log level, and that will apply to all extensions and the editor. |
44 | | - |
45 | | -If you need logs that involve messages between the Language Client and Language Server, you can set `"bandit.server.trace": "verbose"`, to get the messaging logs. These logs are also available `Output` > `Bandit` panel. |
46 | | - |
47 | | -## Linting |
48 | | - |
49 | | -Run `nox --session lint` to run linting on both Python and TypeScript code. Please update the nox file if you want to use a different linter and formatter. |
50 | | - |
51 | | -## Packaging and Publishing |
52 | | - |
53 | | -1. Build package using `nox --session build_package`. |
54 | | -1. Take the generated `.vsix` file and upload it to your extension management page <https://marketplace.visualstudio.com/manage>. |
55 | | - |
56 | | -To do this from the command line see here <https://code.visualstudio.com/api/working-with-extensions/publishing-extension> |
57 | | - |
58 | | -## Upgrading Dependencies |
59 | | - |
60 | | -Dependabot yml is provided to make it easy to setup upgrading dependencies in this extension. Be sure to add the labels used in the dependabot to your repo. |
61 | | - |
62 | | -To manually upgrade your local project: |
63 | | - |
64 | | -1. Create a new branch |
65 | | -1. Run `npm update` to update node modules. |
66 | | -1. Run `nox --session setup` to upgrade python packages. |
67 | | - |
68 | | -## Troubleshooting |
69 | | - |
70 | | -### Changing path or name of `lsp_server.py` something else |
71 | | - |
72 | | -If you want to change the name of `lsp_server.py` to something else, you can. Be sure to update `constants.ts` and `src/test/python_tests/lsp_test_client/session.py`. |
73 | | - |
74 | | -Also make sure that the inserted paths in `lsp_server.py` are pointing to the right folders to pick up the dependent packages. |
75 | | - |
76 | | -### Module not found errors |
77 | | - |
78 | | -This can occurs if `bundled/libs` is empty. That is the folder where we put your tool and other dependencies. Be sure to follow the build steps need for creating and bundling the required libs. |
79 | | - |
80 | | -Common one is [_pygls_][pygls] module not found. |
81 | | - |
82 | | -[pygls]: https://github.com/openlawlibrary/pygls |
| 34 | +| Command | Description | |
| 35 | +| ---------------------- | --------------------------------- | |
| 36 | +| Bandit: Restart Server | Force re-start the linter server. | |
0 commit comments