diff --git a/CHANGELOG_CODE.md b/CHANGELOG_CODE.md index 4e1e6de..0b6a4be 100644 --- a/CHANGELOG_CODE.md +++ b/CHANGELOG_CODE.md @@ -19,7 +19,7 @@ For user-facing changes, see [`CHANGELOG.md`][_-1]. ### Changed -* [The documentation][60-2] is updated. (fcf2c0fb, 91d467ac) +* [The documentation][60-2] is updated. (fcf2c0fb, 91d467ac, HEAD) * [`PyrightBundle`][60-3] and [`PyrightIcon`][60-4] are renamed. (7032faff) * Gradle is updated to 8.9. (2397aafd, c5d7c8c8) * [Kotlin Serialization Gradle Plugin][60-5] is updated to 1.7.1. @@ -27,7 +27,7 @@ For user-facing changes, see [`CHANGELOG.md`][_-1]. * [Kover Gradle Plugin][60-6] is updated to 0.8.2. (eb306695, 87e5660a) * [The `lsp4ij` submodule][60-7] is added. (b67210b7) * Various files are moved to [the new `cli` submodule][60-8]. (37136d65) -* Path-hints-related logic is revisited to use `PropertyGraph`. (HEAD) +* Path-hints-related logic is revisited to use `PropertyGraph`. (bf2de95e) ### Fixed @@ -37,7 +37,7 @@ For user-facing changes, see [`CHANGELOG.md`][_-1]. [60-1]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/4ca4b746/src/main/kotlin/com/insyncwithfoo/pyright/actions/CopyFileCommand.kt - [60-2]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/91d467ac/docs + [60-2]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/HEAD/docs [60-3]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/7032faff/src/main/kotlin/com/insyncwithfoo/pyright/Bundle.kt [60-4]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/7032faff/src/main/kotlin/com/insyncwithfoo/pyright/Icon.kt [60-5]: https://github.com/Kotlin/kotlinx.serialization diff --git a/README.md b/README.md index 6dd9c68..664440d 100644 --- a/README.md +++ b/README.md @@ -6,27 +6,23 @@ [![Rating](https://img.shields.io/jetbrains/plugin/r/rating/24145)][7] [![Downloads](https://img.shields.io/jetbrains/plugin/d/24145)][8] -![](docs/assets/cli-demo-2.png) +![](./docs/assets/demo.png) Pyright integration for PyCharm. This plugin runs [the Pyright type checker][1] on-the-fly -as you edit your Python files. +and reroutes its diagnostics back to the IDE as you code. -It works by saving all your files as-is before running -the executable provided by you. If you are not OK with that, -please do not install this plugin. - -Note: If you use PyCharm Professional, -install [the Pyright Language Server plugin][2] instead. +Warning: Depending on the running mode, +it might save your files at very fast pace. ## Usage Go to Settings | Tools | Pyright (Global) / Pyright (Project) -and set the path to your Pyright executable. +and set the path to your Pyright executable(s). (Not sure what this means? See [the docs][3] for more information.) @@ -36,7 +32,7 @@ You should see the annotations in a few seconds. [1]: https://github.com/microsoft/pyright [2]: https://github.com/InSyncWithFoo/pyright-langserver-for-pycharm - [3]: https://insyncwithfoo.github.io/pyright-for-pycharm/configurations/common/#executable + [3]: https://insyncwithfoo.github.io/pyright-for-pycharm/configurations/running-modes/ diff --git a/docs/assets/cli-demo-1.png b/docs/assets/cli-demo-1.png deleted file mode 100644 index bdcb1fc..0000000 Binary files a/docs/assets/cli-demo-1.png and /dev/null differ diff --git a/docs/assets/cli-global-configuration-panel.png b/docs/assets/cli-global-configuration-panel.png deleted file mode 100644 index 51fda94..0000000 Binary files a/docs/assets/cli-global-configuration-panel.png and /dev/null differ diff --git a/docs/assets/cli-project-configuration-panel.png b/docs/assets/cli-project-configuration-panel.png deleted file mode 100644 index bf5cfa5..0000000 Binary files a/docs/assets/cli-project-configuration-panel.png and /dev/null differ diff --git a/docs/assets/cli-configurations-demo-others-minimum-severity-level-error.png b/docs/assets/configurations-demo-others-minimum-severity-level-error.png similarity index 100% rename from docs/assets/cli-configurations-demo-others-minimum-severity-level-error.png rename to docs/assets/configurations-demo-others-minimum-severity-level-error.png diff --git a/docs/assets/cli-configurations-demo-others-minimum-severity-level-information.png b/docs/assets/configurations-demo-others-minimum-severity-level-information.png similarity index 100% rename from docs/assets/cli-configurations-demo-others-minimum-severity-level-information.png rename to docs/assets/configurations-demo-others-minimum-severity-level-information.png diff --git a/docs/assets/cli-configurations-demo-others-minimum-severity-level-warning.png b/docs/assets/configurations-demo-others-minimum-severity-level-warning.png similarity index 100% rename from docs/assets/cli-configurations-demo-others-minimum-severity-level-warning.png rename to docs/assets/configurations-demo-others-minimum-severity-level-warning.png diff --git a/docs/assets/configurations-global-panel.png b/docs/assets/configurations-global-panel.png new file mode 100644 index 0000000..10f9ad2 Binary files /dev/null and b/docs/assets/configurations-global-panel.png differ diff --git a/docs/assets/configurations-project-panel.png b/docs/assets/configurations-project-panel.png new file mode 100644 index 0000000..61a23a6 Binary files /dev/null and b/docs/assets/configurations-project-panel.png differ diff --git a/docs/assets/cli-demo-2.png b/docs/assets/demo.png similarity index 100% rename from docs/assets/cli-demo-2.png rename to docs/assets/demo.png diff --git a/docs/assets/cli-features-demo-auto-suggest-executable.png b/docs/assets/features-demo-auto-suggest-executable.png similarity index 100% rename from docs/assets/cli-features-demo-auto-suggest-executable.png rename to docs/assets/features-demo-auto-suggest-executable.png diff --git a/docs/assets/icon-outline-10.svg b/docs/assets/icon-outline-10.svg deleted file mode 120000 index c257c8c..0000000 --- a/docs/assets/icon-outline-10.svg +++ /dev/null @@ -1 +0,0 @@ -../../src/main/resources/icons/outline-bold-black.svg \ No newline at end of file diff --git a/docs/assets/icon-outline-5-white.svg b/docs/assets/icon-outline-5-white.svg deleted file mode 120000 index 3b92e76..0000000 --- a/docs/assets/icon-outline-5-white.svg +++ /dev/null @@ -1 +0,0 @@ -../../src/main/resources/icons/outline-thin-white.svg \ No newline at end of file diff --git a/docs/assets/icon-outline-5.svg b/docs/assets/icon-outline-5.svg deleted file mode 120000 index 262ec41..0000000 --- a/docs/assets/icon-outline-5.svg +++ /dev/null @@ -1 +0,0 @@ -../../src/main/resources/icons/outline-thin-black.svg \ No newline at end of file diff --git a/docs/assets/icon-outline-10-white.svg b/docs/assets/icon-outline.svg similarity index 100% rename from docs/assets/icon-outline-10-white.svg rename to docs/assets/icon-outline.svg diff --git a/docs/assets/inspection-highlight-severity-levels.png b/docs/assets/inspection-highlight-severity-levels.png index 9bff07a..4abfc4a 100644 Binary files a/docs/assets/inspection-highlight-severity-levels.png and b/docs/assets/inspection-highlight-severity-levels.png differ diff --git a/docs/assets/lsp-configurations-demo-auto-import-completions-disabled.png b/docs/assets/lsp-configurations-demo-auto-import-completions-disabled.png deleted file mode 100644 index 1b84881..0000000 Binary files a/docs/assets/lsp-configurations-demo-auto-import-completions-disabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-before.png b/docs/assets/lsp-configurations-demo-autocomplete-parentheses-before.png deleted file mode 100644 index 22273fe..0000000 Binary files a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-before.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-disabled.png b/docs/assets/lsp-configurations-demo-autocomplete-parentheses-disabled.png deleted file mode 100644 index 05c2610..0000000 Binary files a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-disabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-enabled.png b/docs/assets/lsp-configurations-demo-autocomplete-parentheses-enabled.png deleted file mode 100644 index 430061a..0000000 Binary files a/docs/assets/lsp-configurations-demo-autocomplete-parentheses-enabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-completion-support-disabled.png b/docs/assets/lsp-configurations-demo-completion-support-disabled.png deleted file mode 100644 index 1bc96e7..0000000 Binary files a/docs/assets/lsp-configurations-demo-completion-support-disabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-completion-support-enabled.png b/docs/assets/lsp-configurations-demo-completion-support-enabled.png deleted file mode 100644 index b35d857..0000000 Binary files a/docs/assets/lsp-configurations-demo-completion-support-enabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-diagnostics-support-disabled.png b/docs/assets/lsp-configurations-demo-diagnostics-support-disabled.png deleted file mode 100644 index 15aa347..0000000 Binary files a/docs/assets/lsp-configurations-demo-diagnostics-support-disabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-diagnostics-support-enabled.png b/docs/assets/lsp-configurations-demo-diagnostics-support-enabled.png deleted file mode 100644 index d3e2cef..0000000 Binary files a/docs/assets/lsp-configurations-demo-diagnostics-support-enabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-hover-support-disabled.png b/docs/assets/lsp-configurations-demo-hover-support-disabled.png deleted file mode 100644 index 5d66226..0000000 Binary files a/docs/assets/lsp-configurations-demo-hover-support-disabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-hover-support-enabled.png b/docs/assets/lsp-configurations-demo-hover-support-enabled.png deleted file mode 100644 index e3e3f71..0000000 Binary files a/docs/assets/lsp-configurations-demo-hover-support-enabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-disabled.png b/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-disabled.png deleted file mode 100644 index 6c0e220..0000000 Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-disabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-enabled.png b/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-enabled.png deleted file mode 100644 index 1fd64c7..0000000 Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-auto-import-details-enabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-before.png b/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-before.png deleted file mode 100644 index a4cf9ba..0000000 Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-before.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-disabled.png b/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-disabled.png deleted file mode 100644 index c027ef8..0000000 Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-disabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-enabled.png b/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-enabled.png deleted file mode 100644 index e0849ab..0000000 Binary files a/docs/assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-enabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-tagged-hints-disabled.png b/docs/assets/lsp-configurations-demo-tagged-hints-disabled.png deleted file mode 100644 index 3cbab75..0000000 Binary files a/docs/assets/lsp-configurations-demo-tagged-hints-disabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-tagged-hints-enabled.png b/docs/assets/lsp-configurations-demo-tagged-hints-enabled.png deleted file mode 100644 index 7a834bd..0000000 Binary files a/docs/assets/lsp-configurations-demo-tagged-hints-enabled.png and /dev/null differ diff --git a/docs/assets/lsp-configurations-demo-tooltips-link-error-codes.png b/docs/assets/lsp-configurations-demo-tooltips-link-error-codes.png deleted file mode 100644 index be99018..0000000 Binary files a/docs/assets/lsp-configurations-demo-tooltips-link-error-codes.png and /dev/null differ diff --git a/docs/assets/lsp-demo-1.png b/docs/assets/lsp-demo-1.png deleted file mode 100644 index c2629c0..0000000 Binary files a/docs/assets/lsp-demo-1.png and /dev/null differ diff --git a/docs/assets/lsp-features-demo-auto-suggest-executable.png b/docs/assets/lsp-features-demo-auto-suggest-executable.png deleted file mode 100644 index 8bba17b..0000000 Binary files a/docs/assets/lsp-features-demo-auto-suggest-executable.png and /dev/null differ diff --git a/docs/assets/lsp-global-configuration-panel.png b/docs/assets/lsp-global-configuration-panel.png deleted file mode 100644 index b1fb293..0000000 Binary files a/docs/assets/lsp-global-configuration-panel.png and /dev/null differ diff --git a/docs/assets/lsp-project-configuration-panel.png b/docs/assets/lsp-project-configuration-panel.png deleted file mode 100644 index 4de6aa4..0000000 Binary files a/docs/assets/lsp-project-configuration-panel.png and /dev/null differ diff --git a/docs/assets/lsp-restart-server-button.png b/docs/assets/lsp-restart-server-button.png deleted file mode 100644 index 88de29c..0000000 Binary files a/docs/assets/lsp-restart-server-button.png and /dev/null differ diff --git a/docs/assets/lsp4ij-restart-server-button.png b/docs/assets/lsp4ij-restart-server-button.png new file mode 100644 index 0000000..e6a5f26 Binary files /dev/null and b/docs/assets/lsp4ij-restart-server-button.png differ diff --git a/docs/assets/lsp4ij-stop-server-button.png b/docs/assets/lsp4ij-stop-server-button.png new file mode 100644 index 0000000..3418e88 Binary files /dev/null and b/docs/assets/lsp4ij-stop-server-button.png differ diff --git a/docs/configurations/cli.md b/docs/configurations/cli.md deleted file mode 100644 index e7d8fb4..0000000 --- a/docs/configurations/cli.md +++ /dev/null @@ -1,80 +0,0 @@ -# CLI-specific configurations - - -## Configuration file - -!!! note - - This configuration is [deliberately][1] unsupported by LSP. - The language server will search for the configuration file(s) - inside the root directory of the workspace. - -Despite being called "file", this can be a path to a directory -containing a `pyrightconfig.json` and/or a `pyproject.toml` -(the former takes precedence if both are present). -This path will be passed to the executable via [the `--project` option][2]. - -* If the executable is local, only the local path is used. -* If the executable is global, the local path is used if it is specified, - falling back to the global one. - -If the path retrieved using the aforementioned strategy is not specified, -the project directory is used. - - -## Process timeout - -Modify this option to set a maximum limit (in milliseconds) -each process should take before it is forcibly destroyed. - -A value of -1 disables the timeout. - -Default: 10 seconds. - -!!! warning - - If there is no time limit, the process might run indefinitely, - leading to undesired CPU and RAM usage. - - -## Number of threads - -Modify this option to paralellize type checking -on up to the specified number of threads. -A value of 0 means nothing is passed to the executable. - -This corresponds to the `--threads` option. - -Default: 0 - -!!! warning - - The `--thread` option is only available in Pyright 1.1.371 and later. - Modifying it will cause an error for older versions. - - -## Minimum severity level - -Modify this option to set a minimum threshold that -only the diagnostics whose severity is equal or higher than it -will be emitted. - -This corresponds to the `--level` option. - -Default: Information - -=== "Information" - - ![](../assets/cli-configurations-demo-others-minimum-severity-level-information.png) - -=== "Warning" - - ![](../assets/cli-configurations-demo-others-minimum-severity-level-warning.png) - -=== "Error" - - ![](../assets/cli-configurations-demo-others-minimum-severity-level-error.png) - - - [1]: https://github.com/microsoft/pyright/discussions/7650 - [2]: https://microsoft.github.io/pyright/#/command-line diff --git a/docs/configurations/common.md b/docs/configurations/common.md deleted file mode 100644 index 2ae5f1e..0000000 --- a/docs/configurations/common.md +++ /dev/null @@ -1,191 +0,0 @@ -# Common configurations - - -## Executable - -For CLI/LSP to work, at least one executable file needs to be defined -using either the Global or Project panel. - -!!! question "[How do I install the executables?][1]" - -Such a file is typically named `pyright`/`pyright-python` (CLI) -or `pyright-langserver`/`pyright-python-langserver` (LSP) -and can likely be found in: - -!!! note - - The locations mentioned here are for Pip and NPM-like managers. - For other tools (e.g. Homebrew), see their documentation - to know where they store their executable files. - -| Manager | Type | OS | Directory | -|:--------|:-------|:--------|:---------------------------------------------------| -| NPM | Global | Windows | `%APPDATA%\npm` | -| NPM | Global | Linux | `/usr/local/bin` | -| Pip | Global | Windows | `%LOCALAPPDATA%\Programs\Python\\Scripts` | -| Pip | Global | Linux | `~/.local/bin` | -| NPM | Local | Windows | `.\node_modules\.bin` | -| NPM | Local | Linux | `./node_modules/.bin` | -| Pip | Local | Windows | `.\\Scripts` | -| Pip | Local | Linux | `.//bin` | - -??? question "What's the difference between these files?" - - [TLDR][2]: Some may output "unexpected" things. - -!!! note - - For LSP to work with a WSL project, - its interpreter and the executable must be - located within the same distribution. - -If the executables can't be found in the aforementioned locations, -see the following pages for more information: - -* [Where does npm install packages?][3] - Stack Overflow -* [Where does pip install its packages?][4] - Stack Overflow -* [folders][5] - npm Docs - -You can also use a relative path. -It would be interpreted as relative to the project directory. - -The executable is used as-is with no additional checks, -so CLI/LSP will still work even if, for example, -it's a wrapper script that outputs diagnostics in the expected format. - -!!! tip - - For the best experience, always use or maintain compatibility - with the latest version of Pyright. - - -### Always use global - -Check this option to always use the global executable -and configuration file. - -Default: `false` - - -### Auto-suggest executable - -Check this option to automatically find and -suggest an executable for the current project on open. -See [the corresponding feature][6] for more information. - -Default: `true` - - -## Tooltips - -These options are not applied retroactively; -you need to make an edit to see the effect. - - -### Use editor font - -Check this option to display tooltips in the editor font. - -Default: `false` - -=== "Enabled" - - ![](../assets/configurations-demo-tooltips-use-editor-font.png) - -=== "Disabled" - - ![](../assets/configurations-demo-tooltips-default.png) - - -### Add prefix - -Check this option to prefix tooltips with "Pyright:". - -Default: `false` - -=== "Enabled" - - ![](../assets/configurations-demo-tooltips-add-tooltip-prefix.png) - -=== "Disabled" - - ![](../assets/configurations-demo-tooltips-default.png) - - -## Highlight severity levels - -Pyright diagnostics have [three possible levels][7]: -Error, warning, and information. -These can be mapped to different highlight severity levels in the IDE. - -!!! note - - The language server may also output "hint" diagnostics - that report code as ["unnecessary" or "deprecated"][8]. - These can be [disabled][9] from the global configuration panel. - - -### Configuring - -The target levels can be configured by modifying the options provided -at Editor | Inspections --> -Pyright diagnostics / Pyright language server diagnostics. - -!!! note "" - - Only the levels defined in the select boxes - under the Options pane are honored. - -![](../assets/inspection-highlight-severity-levels.png) - -For each diagnostic level, there are four highlight levels to choose from: - -| Level | Default effects | -|--------------|-----------------------| -| Error | Red squiggles | -| Warning | Yellow squiggles | -| Weak warning | Dark yellow squiggles | -| Information | No visible effects | - -!!! info "" - - These levels are semantic, not visual. - -The Information level is the only one not considered -"problematic" by the IDE. Annotations of this kind -will not be reported as "problems" during batch inspections -(File, Project Errors and similar tabs in -the Problems tool window). - -!!! note - - Despite having no visible effects, - Information annotations are still shown on hover. - - === "Information" - - ![](../assets/inspection-information-demo.png) - - === "Weak warning" - - ![](../assets/inspection-weak-warning-demo.png) - - -### Recommended levels - -| Diagnostic | For most users (default) | For lax users | -|-------------|--------------------------|---------------| -| Error | Error | Warning | -| Warning | Warning | Weak warning | -| Information | Weak warning | Weak warning | - - - [1]: ../how-to.md#how-to-install-the-pyright-executables - [2]: ../faq.md#whats-the-difference-between-the-pyright-and-pyright-python-files - [3]: https://stackoverflow.com/q/5926672 - [4]: https://stackoverflow.com/q/29980798 - [5]: https://docs.npmjs.com/cli/v10/configuring-npm/folders#executables - [6]: ../features.md#executable-suggestion - [7]: https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings - [8]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticTag - [9]: lsp.md#tagged-hints diff --git a/docs/configurations/executables.md b/docs/configurations/executables.md new file mode 100644 index 0000000..07cab4d --- /dev/null +++ b/docs/configurations/executables.md @@ -0,0 +1,110 @@ +## Executable and language server executable + +The `pyright` (or `pyright-python`) and +`pyright-langserver` (or `pyright-python-langserver`) files +can be found in the following locations: + +!!! question "[What are these executables used for?][1]" + +!!! question "[How do I install the executables?][2]" + +!!! question "[What's the difference between these files?][3]" + +!!! note + + The locations mentioned here are for Pip and NPM-like managers. + For other tools (e.g. Homebrew), see their documentation + to know where they store their executable files. + +| Manager | Type | OS | Directory | +|:--------|:-------|:--------|:---------------------------------------------------| +| NPM | Global | Windows | `%APPDATA%\npm` | +| NPM | Global | Linux | `/usr/local/bin` | +| Pip | Global | Windows | `%LOCALAPPDATA%\Programs\Python\\Scripts` | +| Pip | Global | Linux | `~/.local/bin` | +| NPM | Local | Windows | `.\node_modules\.bin` | +| NPM | Local | Linux | `./node_modules/.bin` | +| Pip | Local | Windows | `.\\Scripts` | +| Pip | Local | Linux | `.//bin` | + +If the executables can't be found in the aforementioned locations, +see the following pages for more information: + +* [Where does npm install packages?][4] - Stack Overflow +* [Where does pip install its packages?][5] - Stack Overflow +* [folders][6] - npm Docs + +If a relative path is specified, it would be interpreted +as relative to the project directory. + +The executables are used as-is with no additional checks. +This is useful if you want to use a Pyright fork or a custom script. + +!!! tip + + For the best experience, always use or maintain compatibility + with the latest version of Pyright. + + +### Configuration files + +| Used by running mode(s) | Default | Corresponding CLI option | +|-------------------------|--------------------------|--------------------------| +| Command line | Project's root directory | `--project` | + +Despite being called "file", this can be a path to a directory +containing a `pyrightconfig.json` and/or a `pyproject.toml` +(the former takes precedence if both are present). + +* If a local executable is specified, the local path is used. +* If only the global executable is specified, the local path is used. +* If no local configuration file is specified, the global is used. + +If the path retrieved using the aforementioned strategy is not specified, +the project's root directory is used. + +!!! note + + This configuration is [deliberately][7] unsupported by LSP. + The language server will search for the configuration file(s) + inside the root directory of the workspace. + + +### Always use global + +| Used by running mode(s) | Default | +|-------------------------|---------| +| N/A | `false` | + +Enable this setting to always use +the global executables and configuration file. + + +### Auto-suggest executable + +| Used by running mode(s) | Default | +|-------------------------|---------| +| N/A | `true` | + +Enable this setting to automatically find and +suggest an executable for the current project on open. +See [the corresponding feature][8] for more information. + + +### UI hints + +As a path field is edited, the small hint under the field +will show whether the path is valid or invalid. + +This is only used to give a general hint; +a path can still be saved even if it is marked as invalid. + + + [1]: running-modes.md + [2]: ../how-to.md#how-to-install-the-pyright-executables + [3]: ../faq.md#whats-the-difference-between-the-pyright-and-pyright-python-files + [4]: https://stackoverflow.com/q/5926672 + [5]: https://stackoverflow.com/q/29980798 + [6]: https://docs.npmjs.com/cli/v10/configuring-npm/folders#executables + [7]: https://github.com/microsoft/pyright/discussions/7650 + [8]: ../features.md#executable-suggestion diff --git a/docs/configurations/index.md b/docs/configurations/index.md new file mode 100644 index 0000000..d33f250 --- /dev/null +++ b/docs/configurations/index.md @@ -0,0 +1,19 @@ +# Configurations + +The plugin provides two configuration panels: + +* Pyright (Global) for application-level settings, and +* Pyright (Project) for project-level settings. + +They can be found under the Tools section of the Settings panel. + +For the plugin to work, at least one [executable][1] needs to be specified. +Note that different [running modes][2] require different executables. + +To configure highlight severity levels, +use [the inspection entry][3]'s corresponding pane. + + + [1]: executables.md + [2]: running-modes.md + [3]: inspection.md diff --git a/docs/configurations/inspection.md b/docs/configurations/inspection.md new file mode 100644 index 0000000..824fd48 --- /dev/null +++ b/docs/configurations/inspection.md @@ -0,0 +1,58 @@ +## Inspection entry + +This plugin can be disabled by disabling +the inspection Pyright diagnostics, +which can be found under Editor | Inspections. +However, this is not recommended for other purposes than debugging. + + +### Highlight severity levels + +Pyright diagnostics have [three possible levels][1]: +Error, warning, and information. +These can be mapped to different highlight severity levels in the IDE. + +The target levels can be configured via +the inspection's corresponding settings pane. + +!!! note "" + + Only the levels defined in the dropdowns + under the Options pane are honored. + +![](../assets/inspection-highlight-severity-levels.png) + +!!! info "" + + These levels are semantical, not visual. + +The Information level is the only one not considered +"problematic" by the IDE. Annotations of this kind +will not be reported as "problems" during batch inspections +(File, Project Errors and similar tabs in +the Problems tool window). + +!!! note + + Despite having no visible effects, + Information annotations are still shown on hover. + + === "Information" + + ![](../assets/inspection-information-demo.png) + + === "Weak warning" + + ![](../assets/inspection-weak-warning-demo.png) + + +#### Recommended levels + +| Diagnostic | For most users (default) | For lax users | +|-------------|--------------------------|---------------| +| Error | Error | Warning | +| Warning | Warning | Weak warning | +| Information | Weak warning | Weak warning | + + + [1]: https://microsoft.github.io/pyright/#/configuration?id=type-check-diagnostics-settings diff --git a/docs/configurations/lsp.md b/docs/configurations/lsp.md deleted file mode 100644 index 1e5252a..0000000 --- a/docs/configurations/lsp.md +++ /dev/null @@ -1,315 +0,0 @@ -# LSP-specific configurations - - -## Tooltips - -These options are not applied retroactively; -you need to make an edit to see the effect. - - -### Link error codes - -Enable this option to display error codes as links. - -Default: `false` - -=== "Enabled" - - ![](../assets/lsp-configurations-demo-tooltips-link-error-codes.png) - -=== "Disabled" - - ![](../assets/configurations-demo-tooltips-default.png) - - -## Language server settings - -These settings are not applied retroactively; -the server needs to be [restarted][1] for them to have effects. - - -### Auto-restart server - -Check this option to automatically restart -the language server on configuration change. - -[Highlight severity level settings][2] -will not trigger this behaviour. - -Default: `false` - -!!! note - - The server might be restarted more than once if - both configuration panels are modified. - - -### Completion support - -Check this option to enable completion support. - -Default: `false` - -=== "Enabled" - - ![](../assets/lsp-configurations-demo-completion-support-enabled.png) - -=== "Disabled" - - ![](../assets/lsp-configurations-demo-completion-support-disabled.png) - -!!! note - - The autocompletion result might not precisely - follow the server's response due to - a few custom modifications employed by the plugin - to monkeypatch IDE bugs (e.g. [IJPL-155741][3]). - - -### Diagnostics support - -Uncheck this option to disable diagnostics support. - -Default: `true` - -=== "Enabled" - - ![](../assets/lsp-configurations-demo-diagnostics-support-enabled.png) - -=== "Disabled" - - ![](../assets/lsp-configurations-demo-diagnostics-support-disabled.png) - - -### Go-to-definition support - -Check this option to enable go-to-definition support. - -Default: `false` - -!!! note - - As of yet, PyCharm's native support is - prioritized over the language server's. - - This means Ctrl B (or similar shortcuts) - will only trigger PyCharm's support on tokens it can handle - (that is, most of them). - - The difference between the set of all tokens which Pyright support - and that of PyCharm is currently unknown. - - See [this issue][4] for more information. - - -### Hover support - -Uncheck this option to disable hover support. - -Default: `true` - -=== "Enabled" - - ![](../assets/lsp-configurations-demo-hover-support-enabled.png) - -=== "Disabled" - - ![](../assets/lsp-configurations-demo-hover-support-disabled.png) - - -### Autocomplete parentheses - -Check this option to also automatically insert parentheses -for function, method and constructor completions. - -Default: `false` - -=== "Before" - - ![](../assets/lsp-configurations-demo-autocomplete-parentheses-before.png) - -=== "Disabled" - - ![](../assets/lsp-configurations-demo-autocomplete-parentheses-disabled.png) - -=== "Enabled" - - ![](../assets/lsp-configurations-demo-autocomplete-parentheses-enabled.png) - - -### Auto-import completions - -Uncheck this option to prevent the language server from offering -completions which, if accepted, will also add a `import` statement -for that newly introduced symbol. - -This corresponds to the `python.analysis.autoImportCompletions` setting. - -Default: `true` - -=== "Auto-import completions enabled" - - ![](../assets/lsp-configurations-demo-completion-support-enabled.png) - -=== "Auto-import completions disabled" - - ![](../assets/lsp-configurations-demo-auto-import-completions-disabled.png) - -=== "Completion support disabled" - - ![](../assets/lsp-configurations-demo-completion-support-disabled.png) - - -### Add common search paths - -Uncheck this option to tell the language server not to add -common search paths like `src` when there are -no execution environments defined in the configuration file. - -This corresponds to the `python.analysis.autoSearchPaths` setting. - -Default: `true` - - -### Diagnostic mode - -!!! note - - This option's usefulness is as of yet unknown. - -Modify this option to control the number of files -for which the language server will analyze and report diagnostics. - -This corresponds to the `python.analysis.diagnosticMode` setting. - -Default: *Open files only* - - -### Log level - -!!! note - - Language server logs are not recorded in `idea.log` by default. - You need to manually [enable it][5]. - -Modify this option to make the language server -emit more or less [log messages][6]. - -This corresponds to the `python.analysis.logLevel` setting. - -Default: Information - - -### Monkeypatch auto-import details - -Uncheck this option to prevent the original completion item detail -("Auto-import" or a similar localized message) -from being overridden by its import source. - -Default: `true` - -=== "Enabled" - - ![](../assets/lsp-configurations-demo-monkeypatch-auto-import-details-enabled.png) - -=== "Disabled" - - ![](../assets/lsp-configurations-demo-monkeypatch-auto-import-details-disabled.png) - - -### Monkeypatch trailing quote bug - -Uncheck this option to use the IDE's native implementation -when applying quoted completions, -which may insert extraneous trailing quotes. - -Upstream issue: [IJPL-155741][7]. - -Default: `true` - -=== "Before" - - ![](../assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-before.png) - -=== "Enabled" - - ![](../assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-enabled.png) - -=== "Disabled" - - ![](../assets/lsp-configurations-demo-monkeypatch-trailing-quote-bug-disabled.png) - - -### Tagged hints - -Uncheck this option to prevent the language server from emitting -"Unnecessary" and "Deprecated" hints, which are visualized in the IDE -as faded-out and strikethrough text, correspondingly. - -This corresponds to the `pyright.disableTaggedHints` setting. - -Default: `true` - -=== "Enabled" - - ![](../assets/lsp-configurations-demo-tagged-hints-enabled.png) - -=== "Disabled" - - ![](../assets/lsp-configurations-demo-tagged-hints-disabled.png) - - -### Targeted file extensions - -A file whose extension is included in this list will be recognized -as suitable for the language server to run on. -This is useful if you use a server -whose support range is wider than that of Pyright. - -Each extension should be written on one line when the editor is expanded. -Otherwise, use the pipe character (`|`) to separate them. - -Leading and trailing whitespace are stripped away. -Blank extensions are thus considered invalid. - -Default: `py`, `pyi` - -!!! note - - Presumably, due to a limitation/bug of IntelliJ, - characters like "🔥" (U+1F525 Fire, the extension for [Mojo][8]) - cannot be serialized correctly into setting files - and therefore will not persist between IDE sessions. - - Testing shows that this affects characters - whose codepoints are greater than U+FFFD. - - -### Workspace folders - -The folders defined by this option will be passed -to the language server as "[workspace folders][9]". -Pyright will only recognize `pyproject.toml`/`pyrightconfig.json` files -which are direct children of these folders. - -Possible choices: - -* Project base directories: - Top-level directories which contain files related to the project, - often only one (project root). -* Source roots: - Directories marked as "[source roots][10]". - -Default: Project base directories - - - [1]: ../how-to.md#how-to-restart-the-language-server - [2]: ./common.md#highlight-severity-levels - [3]: https://youtrack.jetbrains.com/issue/IJPL-155741 - [4]: https://github.com/InSyncWithFoo/pyright-langserver-for-pycharm/issues/29 - [5]: ../how-to.md#how-to-enable-language-server-logging - [6]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#window_logMessage - [7]: https://youtrack.jetbrains.com/issue/IJPL-155741 - [8]: https://en.wikipedia.org/wiki/Mojo_(programming_language) - [9]: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_workspaceFolders - [10]: https://www.jetbrains.com/help/pycharm/content-root.html diff --git a/docs/configurations/other.md b/docs/configurations/other.md new file mode 100644 index 0000000..020bd80 --- /dev/null +++ b/docs/configurations/other.md @@ -0,0 +1,101 @@ +# Other settings + + +## Tooltip settings + +These options are not applied retroactively; +you need to make an edit to see the effect. + + +### Use editor font + +| Used by running mode(s) | Default | +|-------------------------|---------| +| Command line | `false` | + +Enable this setting to display tooltips in the editor font. + +=== "Enabled" + + ![](../assets/configurations-demo-tooltips-use-editor-font.png) + +=== "Disabled" + + ![](../assets/configurations-demo-tooltips-default.png) + + +### Add prefix + +| Used by running mode(s) | Default | +|-------------------------|---------| +| Command line | `false` | + +Enable this setting to prefix tooltips with "Pyright:". + +=== "Enabled" + + ![](../assets/configurations-demo-tooltips-add-tooltip-prefix.png) + +=== "Disabled" + + ![](../assets/configurations-demo-tooltips-default.png) + + +## Command-line-mode-specific settings + + +### Process timeout + +| Default | Corresponding CLI option | +|-------------------|--------------------------| +| 10 seconds | N/A | + +Modify this setting to set a maximum limit (in milliseconds) +each process should take before it is forcibly destroyed. + +A value of -1 disables the timeout. + +!!! warning + + If there is no time limit, the process might run indefinitely + in cases of bugs, leading to undesired CPU and RAM usage. + + +### Number of threads + +| Default | Corresponding CLI option | +|----------|--------------------------| +| 0 | `--threads` | + +Modify this setting to paralellize type checking +on up to the specified number of threads. + +A value of 0 means nothing is passed to the executable. + +!!! warning + + The `--thread` option is only available in Pyright 1.1.371 and later. + Modifying it will cause an error for older versions. + + +## Minimum severity level + +| Default | Corresponding CLI option | +|--------------------|--------------------------| +| Information | `--level` | + +Modify this setting to set a minimum threshold that +only diagnostics whose severity is equal or higher than it +will be emitted. + +=== "Information" + + ![](../assets/configurations-demo-others-minimum-severity-level-information.png) + +=== "Warning" + + ![](../assets/configurations-demo-others-minimum-severity-level-warning.png) + +=== "Error" + + ![](../assets/configurations-demo-others-minimum-severity-level-error.png) diff --git a/docs/configurations/related.md b/docs/configurations/related.md deleted file mode 100644 index 813ba77..0000000 --- a/docs/configurations/related.md +++ /dev/null @@ -1,26 +0,0 @@ -## UI hints - -As a path field is edited, the small hint under the field -will show whether the path is valid or invalid. - -This is only used to give a general hint; -a path can still be saved even if it is marked as invalid. - - -## Inspections - -The inspections shown in the [Highlight severity levels][1] section -can be disabled, though this is not recommended. -The effect of doing so is different for each plugin. - -* For CLI: - * The executable will not be executed. - * Files will not be automatically saved. - -* For LSP: - * New sessions will not be started. - * Existing sessions will stop on [restart][2]. - - - [1]: ../configurations/common.md#highlight-severity-levels - [2]: ../how-to.md#how-to-restart-the-language-server diff --git a/docs/configurations/running-modes.md b/docs/configurations/running-modes.md new file mode 100644 index 0000000..64881ad --- /dev/null +++ b/docs/configurations/running-modes.md @@ -0,0 +1,70 @@ +Each distribution of Pyright comes with two executables: +`pyright` (also referred to as "executable") and +`pyright-langserver` ("language server executable"). + +Aside from the main functionality discussed here, +the first also provides a few more features and options, +some of which are supported or used by this plugin. + +Different running modes use different executables. + +To make the most of this plugin, +you are recommended to specify both executables. + + +## Comparison tables + +| | `pyright` | `pyright-langserver` | +|-------------------------------------|--------------------------------------------|-----------------------------------------| +| Process type | Stops when finishes checking the file(s) | Long-running process | +| Result | Only type checking diagnostics | Diagnostics and [other LSP features][1] | +| Performance | Good | Better in many cases | +| File reading method | From disk | File contents are sent via stdio | +| [Potentially infinite processes][2] | Long processes are [forcibly destroyed][3] | Processes must be terminated manually | + +| | Command line mode | LSP4IJ mode | +|--------------------|-----------------------------------------------|-------------------------------------------| +| Executable used | `pyright` | `pyright-langserver` | +| Executable invoked | After each change | On project/supported file open | +| Side effect | Will save all files to ensure synchronization | No side effects | +| Error reporting | Notifications and IDE log | LSP4IJ console, notifications and IDE log | + + +## Command line mode + +If this mode is selected, everytime a Python file is edited, +this plugin will save it along with other (unsaved) files, +then invoke the executable in a subprocess. +The result of this process is rerouted back to the IDE +in the form of visual annotations. + +This mode requires two things to work correctly: + +* That the executable you provide accepts said arguments, and +* that it outputs diagnostics in the formats defined [here][4]. + +If any of these requirements are not met, +[a notification][5] will be displayed. + +Due to backward compatibility, this is the default mode. +However, for better performance, LSP4IJ mode is recommended. + + +## LSP4IJ mode + +If this mode is selected, the language server will be invoked on project open. +All LSP messages are then handled by [the various features][6] +of [the LSP4IJ plugin][7], a third-party LSP client for JetBrains IDEs. + +[It is possible][8] to use Pyright with LSP4IJ directly, +but doing so is not recommended. + + + [1]: https://microsoft.github.io/pyright/#/features?id=language-server-support + [2]: ../problems.md#process-timed-out + [3]: other.md#process-timeout + [4]: https://microsoft.github.io/pyright/#/command-line?id=json-output + [5]: ../problems.md + [6]: https://github.com/redhat-developer/lsp4ij/blob/main/docs/LSPSupport.md + [7]: https://github.com/redhat-developer/lsp4ij + [8]: https://github.com/redhat-developer/lsp4ij/blob/main/docs/UserDefinedLanguageServer.md diff --git a/docs/faq.md b/docs/faq.md index 3a62d2b..ac34113 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,45 +1,10 @@ # Frequently asked questions -## What exactly is this plugin doing? - - -### CLI - -In a nutshell: - -* You edit your code. -* This plugin saves your (unsaved) files. -* It then invokes the executable(s) provided by you - with some hardcoded arguments. -* The results of which are used to show annotations. - -And that's it. - -It expects two things: - -* That the executable you provide accepts said arguments, and -* that it outputs diagnostics in the formats specified [here][1]. - -As long as you respect these requirements, -you can use your own script, or whatever. -If you don't, expect some big bad error messages. - - -### LSP - -Most of the logic is already defined by either the [@eclipse-lsp4j/lsp4j][2] -library or [the experimental language server protocol APIs][3]. -LSP simply glues these and the Pyright language server together. - -Again, the executable is not checked. -You can use your own hand-hacked version if you feel like it. - - ## My code should have no/these errors, but it does/doesn't. -Both CLI and LSP contain no type checking logic. -For type checking bugs, please report them to [the Pyright issue tracker][4]. +This plugin contains no type checking logic. +For type checking bugs, please report them to [the Pyright issue tracker][1]. ## What's the difference between the `pyright` and `pyright-python` files? @@ -49,7 +14,7 @@ mainly for the purpose of better integration with VSCode. This requires a dependency on Node, which Python developers might not have on their development machines. -[The PyPI `pyright` package][5] was created to solve this problem. +[The PyPI `pyright` package][2] was created to solve this problem. When installed, it places 4 proxy executables in the same virtual environment/directory you have your `pip` in: @@ -58,7 +23,7 @@ the same virtual environment/directory you have your `pip` in: These proxies will automatically install the actual NPM package if it is not already installed, then re-output the results of -the original executables. [With the correct configurations][6], +the original executables. [With the correct configurations][3], new versions may be automatically installed at runtime. If the corresponding version of the NPM package has not been installed, @@ -72,50 +37,27 @@ Said original executables can typically be found at: * Linux: `~/.cache/pyright-python//node_modules/.bin` -## Why does CLI have to perform saves so often? +## Why does the plugin have to perform saves so often in command line mode? Pyright only reads actual files on disk. It does not support passing files from stdin. -[A feature request][7] was made and quickly rejected. +[A feature request][4] was made and quickly rejected. -Adding an option that makes CLI run only on "manual" saves +Adding an option that makes the plugin run only on "manual" saves (the *Save All* action) is counter-productive, since that doesn't -guarantee the annotator class is called. This is [a known limitation][8]. +guarantee the annotator class is called. This is [a known limitation][5]. -If you use PyCharm Professional, you [should be using][9] LSP instead. +Use [the LSP4IJ mode][6] instead. ## Is the command-line watch mode (`--watch`) supported? -Support for `--watch` is on the roadmap. -There is no ETA, however. - - -## Why does CLI take so long to run on my project? - -There are multiple possible reasons for this. - -### Other inspections are taking too long - -Since CLI invokes a command-line tool, it must be registered -as an [`ExternalAnnotator`][10]. Inspectors of this kind will -only run when all other background tasks have finished. - -Check your other plugins to see if this is the case. - -### There are a lot of files/things to process - -Unlike Mypy, Pyright does not cache previous results. -As such, everytime it runs on a given file, -it also has to reprocess all other files that file depends on. - -Again, for better performance, LSP [is recommended][9]. +No. Use LSP4IJ mode instead. -### Your code triggers a Pyright bug -In some rare cases, Pyright might be stuck in an infinite loop or similar. +## What does this command line option do? -If this seems to be the case, treat it as [a fatal error][11]. +Refer to [Pyright's documentation][7] for the meaning of these options. ## Is this plugin affiliated with Microsoft/JetBrains? @@ -127,22 +69,18 @@ It was, however, created out of adoration of Pyright and JetBrains IDEs. ## I love this project. How can I support it? -You can consider [sponsoring it][12]. +You can consider [sponsoring it][8]. -If you are feeling generous, see [`CONTRIBUTING.md`][13] +If you are feeling generous, see [`CONTRIBUTING.md`][9] for how to contribute non-financially. - [1]: https://microsoft.github.io/pyright/#/command-line?id=json-output - [2]: https://github.com/eclipse-lsp4j/lsp4j - [3]: https://plugins.jetbrains.com/docs/intellij/language-server-protocol.html - [4]: https://github.com/microsoft/pyright/issues - [5]: https://pypi.org/project/pyright/ - [6]: https://github.com/RobertCraigie/pyright-python/blob/HEAD/README.md#automatically-keeping-pyright-up-to-date - [7]: https://github.com/microsoft/pyright/issues/7282 - [8]: https://github.com/InSyncWithFoo/pyright-for-pycharm/issues/10 - [9]: index.md#choosing-the-right-plugin - [10]: https://plugins.jetbrains.com/docs/intellij/syntax-highlighting-and-error-highlighting.html#external-annotator - [11]: problems.md#fatal-error - [12]: https://github.com/sponsors/InSyncWithFoo - [13]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/master/CONTRIBUTING.md + [1]: https://github.com/microsoft/pyright/issues + [2]: https://pypi.org/project/pyright/ + [3]: https://github.com/RobertCraigie/pyright-python/blob/HEAD/README.md#automatically-keeping-pyright-up-to-date + [4]: https://github.com/microsoft/pyright/issues/7282 + [5]: https://github.com/InSyncWithFoo/pyright-for-pycharm/issues/10 + [6]: configurations/running-modes.md + [7]: https://microsoft.github.io/pyright/#/command-line + [8]: https://github.com/sponsors/InSyncWithFoo + [9]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/master/CONTRIBUTING.md diff --git a/docs/features.md b/docs/features.md index 950f935..2e44919 100644 --- a/docs/features.md +++ b/docs/features.md @@ -16,15 +16,9 @@ Available actions: * Absolute path: Set the absolute path. * Relative path: Set the relative path (no leading dot). -* Do not suggest: Turn off [the corresponding option][1]. +* Do not suggest: Turn off [the corresponding setting][1]. -=== "CLI" - - ![](./assets/cli-features-demo-auto-suggest-executable.png) - -=== "LSP" - - ![](./assets/lsp-features-demo-auto-suggest-executable.png) +![](./assets/features-demo-auto-suggest-executable.png) ## Suppressing diagnostics using quick fixes @@ -65,4 +59,4 @@ the entire list will be removed: ![](./assets/features-demo-diagnostic-suppressing-quick-fixes-no-code-after.png) - [1]: configurations/common.md#auto-suggest-executable + [1]: configurations/executables.md#auto-suggest-executable diff --git a/docs/how-to.md b/docs/how-to.md index f5ac81e..879413e 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -1,8 +1,6 @@ ## How to install the Pyright executables -Choose one that works for you (or one you like the most): - -!!! tip "Your favourite tool is not here? [Submit a PR!][1]" +Choose one that works for you: ```shell $ pip install pyright @@ -14,27 +12,25 @@ $ bun install pyright $ brew install pyright ``` -See also [Pyright's official installation guide][2]. +See also [Pyright's official installation guide][1]. ## How to restart the language server -In the status bar, find the cell that has -"Pyright" next to a pair of braces. -Click it, then click the loop icon. +From the LSP Consoles of the Language Servers toolwindow, +find the line that says "Pyright". -![](assets/lsp-restart-server-button.png) +Right click the line below it, then click "Stop". +The line should then say "Disabled". +Right click that line again, then click "Restart". +=== "Stop" -## How to enable language server logging + ![](./assets/lsp4ij-stop-server-button.png) -Add the following line to the Debug Log Settings panel -(Help | Diagnostic Tools): +=== "Restart" -```text -#com.intellij.platform.lsp -``` + ![](./assets/lsp4ij-restart-server-button.png) - [1]: https://github.com/InSyncWithFoo/pyright-for-pycharm/blob/master/CONTRIBUTING.md - [2]: https://microsoft.github.io/pyright/#/installation?id=command-line + [1]: https://microsoft.github.io/pyright/#/installation?id=command-line diff --git a/docs/index.md b/docs/index.md index 6cf232f..1d8e111 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,44 +1,36 @@ # Pyright for PyCharm user documentation This site serves as the user documentation for -the Pyright for PyCharm project. -The project includes two plugins: +[the Pyright PyCharm plugin][1]. -| | The CLI-based plugin | The LSP-based plugin | -|:-----------------|:-------------------------|:------------------------------------| -| Repository | [pyright-for-pycharm][1] | [pyright-langserver-for-pycharm][2] | -| Marketplace name | [Pyright][3] | [Pyright Language Server][4] | -| Codename | CLI | LSP | +The plugin runs and reroutes Pyright's diagnostics back to your IDE. +Both PyCharm Professional and PyCharm Community users can use it. -In this documentation, the two plugins -will be referred to using their codenames. +??? question "Looking for the old LSP plugin?" + It now has [its own documentation site][2]. -## Choosing the right plugin -!!! abstract "TLDR: Professional --> LSP; Community --> CLI." +## Usage -These two plugins have the same naming conventions, -are maintained by the same person, have similar (but not identical) -configurations, but are meant for different target users. +Go to Settings | Tools | +Pyright (Global) / Pyright (Project) +and set the path to [your Pyright executable(s)][3]. -LSP is dependent on [the experimental language server protocol APIs][5] -which are only available for PyCharm Professional and other paid IDEs -since 2023.2. This means that PyCharm Community users cannot use it. +=== "Global" -On the other hand, CLI can be used by both. -However, due to its limited capabilities and performance reason, -it is recommended that PyCharm Professional users use LSP instead. + ![](./assets/configurations-global-panel.png) -!!! warning +=== "Project" - Do not install both plugins. - While doing so will likely cause no technical issues, - their functionalities overlap a lot. + ![](./assets/configurations-project-panel.png) +Save, return to your files and start making some modifications. +You should see Pyright annotations in a few seconds. +If not, refer to [Problems and solutions][4]. - [1]: https://github.com/InSyncWithFoo/pyright-for-pycharm - [2]: https://github.com/InSyncWithFoo/pyright-langserver-for-pycharm - [3]: https://plugins.jetbrains.com/plugin/24145 - [4]: https://plugins.jetbrains.com/plugin/24146 - [5]: https://plugins.jetbrains.com/docs/intellij/language-server-protocol.html + + [1]: https://plugins.jetbrains.com/plugin/24145 + [2]: https://insyncwithfoo.github.io/pyright-langserver-for-pycharm + [3]: configurations/executables.md + [4]: problems.md diff --git a/docs/logging.md b/docs/logging.md index b34118e..60e5da8 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -1,4 +1,4 @@ -For debugging purposes, the plugins may log some informational data. +For debugging purposes, the plugin may log some informational data. When reporting issues, always include the relevant log entries if applicable. @@ -18,7 +18,7 @@ Note that it might be up to 10 MB in size. Alternatively, navigate to the directories documented [here][1]. -## CLI +## Command line mode | Event | Content | Searching keywords | |------------------|--------------------------------------|----------------------------------------| @@ -119,19 +119,13 @@ Exception properties entry format: ``` -## LSP +## LSP4IJ mode -| Event | Content | Keywords to look for | -|--------------|-----------------------|-------------------------------------------| -| Server start | Plugin configurations | `PyrightLSDescriptor - AllConfigurations` | - - -If language server logging [is enabled][4], -every request and response will be logged, -potentially truncated if it is too long. +| Event | Content | Keywords to look for | +|--------------|--------------------------|------------------------------------------------------| +| Server start | Language server settings | `com.insyncwithfoo.pyright.lsp4ij.Client - Settings` | [1]: https://www.jetbrains.com/help/pycharm/directories-used-by-the-ide-to-store-settings-caches-plugins-and-logs.html#logs-directory [2]: https://microsoft.github.io/pyright/#/command-line?id=json-output [3]: https://microsoft.github.io/pyright/#/command-line?id=pyright-exit-codes - [4]: how-to.md#how-to-enable-language-server-logging diff --git a/docs/problems.md b/docs/problems.md index 7facf92..05c424b 100644 --- a/docs/problems.md +++ b/docs/problems.md @@ -6,28 +6,21 @@ Make sure that: * Your project has the correct interpreter set - (Project | Python Interpreter, or a cell in the status bar). + (Project | Python Interpreter). * [The executable][1] is given and is correct. * The plugin itself is enabled (Plugins). -* The corresponding inspection is enabled - (Editor | Inspections --> - Pyright diagnostics / Pyright language server diagnostics). -* (CLI) The file is an actual Python file on disk, not an injected fragment. - -??? question "Why does CLI need the file to be an actual file?" - - [TLDR][2]: Pyright only supports reading files from disk, not stdin. +* [The inspection entry][2] is enabled. Other things to try: * Reinstall the plugin or update to the latest version. * Reopen the files, reopen the project or restart the IDE. -* (LSP) [Restart the language server][3]. +* [Restart the language server][3] (LSP4IJ mode). * Restart your machine. * Reinstall/reset the IDE. If the problem persists, please report it to -[the corresponding issue tracker][4] with [relevant log entries][5]. +[the plugin's issue tracker][4] with [relevant log entries][5]. ## Fatal error @@ -43,9 +36,8 @@ then report it to [Pyright's issue tracker][6]. This most likely means that the configuration file is invalid in some way. -To know which file is being used, see [the configuration docs][1]. -Alternatively, use the "Open file" action to -directly open the file which is reported to be invalid. +Use the "Open file" action to directly open the file +which is reported to be invalid. ## Unrecognized command-line options @@ -55,13 +47,10 @@ doesn't support the options used by the plugin. If you are using [the official NPM package][7] or [the community-maintained PyPI package][8], -please report the problem to [the corresponding issue tracker][4] +please report the problem to [the plugin's issue tracker][4] along with the version of Pyright you are using, which can be retrieved by running ` --version` in your terminal. -If the executable is something you come up with, -check the source code for expected options. - ## Cannot parse output @@ -76,27 +65,55 @@ For custom executables, maintain compatibility with said version. ## Process timed out -This means the process did not finish within [the limit defined][10]. +This means the process did not finish within [the limit specified][10]. -There are [multiple possible reasons][11] for this. +There are multiple possible reasons for this. Increase the limit as necessary. +### Other inspections are taking too long + +Since the command line mode invokes a command-line tool, +it must be registered as an [`ExternalAnnotator`][11]. +Inspectors of this kind will only run +when all other background tasks have finished. + +Check your other plugins to see if this is the case. + + +### There are a lot of files/things to process + +Unlike Mypy, Pyright does not cache previous results. +As such, everytime it runs on a given file, +it also has to reprocess all other files that file depends on. + +For better performance, use LSP4IJ mode instead. + + +### Your code triggers a Pyright bug + +In some rare cases, Pyright might be stuck in an infinite loop or similar. + +If this seems to be the case, treat it as a fatal error. + + ## Other problems -For CLI, you can start debugging by running the commands manually. -The commands can be retrieved using [the provided IDE action][12]. +For command line mode, you can start debugging +by running the commands manually. +The command for the current file can be retrieved +using [a provided IDE action][12]. - [1]: configurations/cli.md#configuration-file - [2]: faq.md#why-does-cli-have-to-perform-saves-so-often + [1]: configurations/executables.md + [2]: configurations/inspection.md [3]: how-to.md#how-to-restart-the-language-server - [4]: index.md + [4]: https://github.com/InSyncWithFoo/pyright-for-pycharm/issues [5]: logging.md [6]: https://github.com/microsoft/pyright/issues [7]: https://www.npmjs.com/package/pyright [8]: https://pypi.org/project/pyright/ [9]: https://microsoft.github.io/pyright/#/command-line?id=json-output - [10]: configurations/cli.md#process-timeout - [11]: faq.md#why-does-cli-take-so-long-to-run-on-my-project + [10]: configurations/other.md#process-timeout + [11]: https://plugins.jetbrains.com/docs/intellij/syntax-highlighting-and-error-highlighting.html#external-annotator [12]: actions.md#copy-pyright-command diff --git a/docs/requirements.txt b/docs/requirements.txt index c7f9f55..058dd16 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,2 @@ -mkdocs~=1.5.3 -mkdocs-material~=9.5.17 +mkdocs~=1.6.0 +mkdocs-material~=9.5.29 diff --git a/docs/usage.md b/docs/usage.md deleted file mode 100644 index c34f933..0000000 --- a/docs/usage.md +++ /dev/null @@ -1,36 +0,0 @@ -=== "CLI" - - Go to Settings | Tools | - Pyright (Global) / Pyright (Project) - and set the path to [your Pyright executable][1]. - - ![](./assets/cli-global-configuration-panel.png) - ![](./assets/cli-project-configuration-panel.png) - - Save, return to your file and start making some modifications. - You should see Pyright annotations in a few seconds. - If not, refer to [Problems and solutions][2]. - -=== "LSP" - - Go to Settings | Tools | - Pyright LS (Global) / Pyright LS (Project) - and set the path to [your Pyright language server executable][1]. - - ![](./assets/lsp-global-configuration-panel.png) - ![](./assets/lsp-project-configuration-panel.png) - - You might need to reopen your files or restart the IDE - for the files to be recognized by the language server. - If that doesn't work, refer to [Problems and solutions][2]. - - ## Enable logging - - You are strongly encouraged to [enable logging][3]. - This way, all requests and responses will be recorded in `idea.log` - for further analysis should a problem arises. - - - [1]: configurations/common.md#executable - [2]: problems.md - [3]: how-to.md#how-to-enable-language-server-logging diff --git a/mkdocs.yaml b/mkdocs.yaml index e8ba484..9223829 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -13,7 +13,7 @@ exclude_docs: | theme: name: material favicon: assets/icon.svg - logo: assets/icon-outline-10-white.svg + logo: assets/icon-outline.svg palette: - media: "(prefers-color-scheme: light)" @@ -34,6 +34,7 @@ theme: features: - content.action.edit - content.action.view + - navigation.indexes - search.suggest markdown_extensions: @@ -62,14 +63,14 @@ markdown_extensions: nav: - Overview: index.md - - Usage: usage.md - Configurations: - - Common: configurations/common.md - - CLI-specific: configurations/cli.md - - LSP-specific: configurations/lsp.md - - Related: configurations/related.md - - Features: features.md + - Overview: configurations/index.md + - Running modes: configurations/running-modes.md + - Executables: configurations/executables.md + - Inspection: configurations/inspection.md + - Other: configurations/other.md - IDE actions: actions.md + - Other features: features.md - Problems: problems.md - Logging: logging.md - How-to guides: how-to.md @@ -79,5 +80,6 @@ validation: omitted_files: warn absolute_links: warn unrecognized_links: warn + anchors: warn strict: true diff --git a/src/main/kotlin/com/insyncwithfoo/pyright/configuration/application/ConfigurationPanel.kt b/src/main/kotlin/com/insyncwithfoo/pyright/configuration/application/ConfigurationPanel.kt index b10fa45..e52d369 100644 --- a/src/main/kotlin/com/insyncwithfoo/pyright/configuration/application/ConfigurationPanel.kt +++ b/src/main/kotlin/com/insyncwithfoo/pyright/configuration/application/ConfigurationPanel.kt @@ -103,7 +103,7 @@ private fun Panel.makeGlobalRunningModeInput(block: ButtonsGroup.() -> Unit) = r } -private fun Row.makeNumberOfThreadsInput(block: Cell.() -> Unit): Cell = run { +private fun Row.makeNumberOfThreadsInput(block: Cell.() -> Unit) = run { val comment = message("configurations.numberOfThreads.comment") spinner(0..1_000_000, step = 1).comment(comment).apply(block) } @@ -165,7 +165,7 @@ internal fun configurationPanel(state: Configurations) = panel { } } - group(message("configurations.group.others")) { + group(message("configurations.group.commandLine")) { row(message("configurations.processTimeout.label")) { makeProcessTimeoutInput { bindIntValue(state::processTimeout) } } diff --git a/src/main/resources/messages/pyright.properties b/src/main/resources/messages/pyright.properties index c8fb8a8..62717e6 100644 --- a/src/main/resources/messages/pyright.properties +++ b/src/main/resources/messages/pyright.properties @@ -2,7 +2,7 @@ configurations.global.displayName = Pyright (Global) configurations.project.displayName = Pyright (Project) configurations.group.tooltips = Tooltips (not applied retroactively) -configurations.group.others = Other settings +configurations.group.commandLine = Command line mode configurations.alwaysUseGlobal.label = Always use global executable configurations.globalExecutable.label = Executable: