browser-basedpyright 1.14.0-047da5de6154ece025c4d52e72b71ecd9ff074e4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.txt +22 -0
- package/README.md +450 -0
- package/dist/pyright.worker.js +3 -0
- package/dist/pyright.worker.js.LICENSE.txt +8 -0
- package/dist/pyright.worker.js.map +1 -0
- package/package.json +51 -0
package/LICENSE.txt
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Pyright - A static type checker for the Python language
|
|
4
|
+
Copyright (c) Microsoft Corporation. All rights reserved.
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE
|
package/README.md
ADDED
|
@@ -0,0 +1,450 @@
|
|
|
1
|
+
<h1><img src="https://github.com/DetachHead/basedpyright/assets/57028336/c7342c31-bf23-413c-af6d-bc430898b3dd"> basedpyright</h1>
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/basedpyright/)
|
|
4
|
+
[](https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright)
|
|
6
|
+
[](https://open-vsx.org/extension/detachhead/basedpyright)
|
|
7
|
+
[](https://packagecontrol.io/packages/LSP-basedpyright)
|
|
8
|
+
[](./docs/installation.md#pycharm)
|
|
9
|
+
[](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#basedpyright)
|
|
10
|
+
[](https://github.com/fannheyward/coc-basedpyright)
|
|
11
|
+
[](https://github.com/manateelazycat/lsp-bridge)
|
|
12
|
+
[](https://discord.gg/7y9upqPrk2)
|
|
13
|
+
[](https://detachhead.github.io/basedpyright)
|
|
14
|
+
|
|
15
|
+
Basedpyright is a fork of [pyright](https://github.com/microsoft/pyright) with various type checking improvements, improved vscode support and pylance features built into the language server.
|
|
16
|
+
|
|
17
|
+
📚 [Documentation](https://detachhead.github.io/basedpyright) | 🛝 [Playground](http://basedpyright.com)
|
|
18
|
+
|
|
19
|
+
## why?
|
|
20
|
+
|
|
21
|
+
there are two main reasons for this fork:
|
|
22
|
+
|
|
23
|
+
1. pyright is lacking several features that are made exclusive to pylance, microsoft's closed-source vscode extension
|
|
24
|
+
2. the maintainer of pyright [closes valid issues for no reason and lashes out at users](https://github.com/microsoft/pyright/issues/8065#issuecomment-2146352290)
|
|
25
|
+
|
|
26
|
+
here is a (mostly) comprehensive list of the new features we've added to basedpyright:
|
|
27
|
+
|
|
28
|
+
### ability to pin the version used by vscode
|
|
29
|
+
|
|
30
|
+
in pyright, if the vscode extension gets updated, you may see errors in your project that don't appear in the CI, or vice-versa. see [this issue](https://github.com/microsoft/pylance-release/issues/5207).
|
|
31
|
+
|
|
32
|
+
basedpyright fixes this problem by adding an `importStrategy` option to the extension, which defaults to looking in your project for the [basedpyright pypi package](#published-as-a-pypi-package---no-nodejs-required).
|
|
33
|
+
|
|
34
|
+
### published as a pypi package - no nodejs required
|
|
35
|
+
|
|
36
|
+
pyright is only published as an npm package, which requires you to install nodejs. [the version on pypi](https://pypi.org/project/pyright/) is just an unofficial wrapper that installs node and the npm package the first time you invoke the cli, [which is quite flaky](https://github.com/RobertCraigie/pyright-python/issues/231).
|
|
37
|
+
|
|
38
|
+
python developers should not be expected to have to install nodejs in order to typecheck their python code. it should just be a regular pypi package like mypy, ruff, and pretty much all other python tooling. this is why basedpyright is [officially published on pypi](https://pypi.org/project/basedpyright/), which comes bundled with the npm package.
|
|
39
|
+
|
|
40
|
+
### new diagnostic rules
|
|
41
|
+
|
|
42
|
+
#### `reportUnreachable` - report errors on code that would otherwise be completely unchecked
|
|
43
|
+
|
|
44
|
+
pyright often incorrectly marks code as unreachable. in most cases, unreachable code is a mistake and therefore should be an error, but pyright does not have an option to report unreachable code. in fact, unreachable code is not even type-checked at all:
|
|
45
|
+
|
|
46
|
+
```py
|
|
47
|
+
if sys.platform == "win32":
|
|
48
|
+
1 + "" # no error
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
by default, pyright will treat the body in the code above as unreachable if pyright itself was run on an operating system other than windows. this is bad of course, because chances are if you write such a check, you intend for your code to be executed on multiple platforms.
|
|
52
|
+
|
|
53
|
+
to make things worse, unreachable code is not even type-checked, so the obviously invalid `1 + ""` above will go completely unnoticed by the type checker.
|
|
54
|
+
|
|
55
|
+
basedpyright solves this issue with a `reportUnreachable` option, which will report an error on such unchecked code. in this example, you can [update your pyright config to specify more platforms using the `pythonPlatform` option](https://github.com/detachhead/basedpyright/blob/main/docs/configuration.md#main-configuration-options) if you intend for the code to be reachable.
|
|
56
|
+
|
|
57
|
+
#### `reportAny` - fully ban the `Any` type
|
|
58
|
+
|
|
59
|
+
pyright has a few options to ban "Unknown" types such as `reportUnknownVariableType`, `reportUnknownParameterType`, etc. but "Unknown" is not a real type, rather a distinction pyright uses used to represent `Any`s that come from untyped code or unfollowed imports. if you want to ban all kinds of `Any`, pyright has no way to do that:
|
|
60
|
+
|
|
61
|
+
```py
|
|
62
|
+
def foo(bar, baz: Any) -> Any:
|
|
63
|
+
print(bar) # error: unknown type
|
|
64
|
+
print(baz) # no error
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
basedpyright introduces the `reportAny` option, which will report an error on usages of anything typed as `Any`.
|
|
68
|
+
|
|
69
|
+
#### `reportIgnoreCommentWithoutRule` - enforce that all ignore comments specify an error code
|
|
70
|
+
|
|
71
|
+
it's good practice to specify an error code in your `pyright: ignore` comments:
|
|
72
|
+
|
|
73
|
+
```py
|
|
74
|
+
# pyright: ignore[reportUnreachable]
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
this way, if the error changes or a new error appears on the same line in the future, you'll get a new error because the comment doesn't account for the other error. unfortunately there are many rules in pyright that do not have error codes, so you can't always do this.
|
|
78
|
+
|
|
79
|
+
basedpyright resolves this by reporting those errors under the `reportGeneralTypeIssues` diagnostic rule. this isn't a perfect solution, but there were over 100 errors that didn't have diagnostic rules. i intend to split them into their own rules in the future, but this will do for now.
|
|
80
|
+
|
|
81
|
+
note that `type: ignore` comments (`enableTypeIgnoreComments`) are unsafe and are disabled by default (see [#330](https://github.com/DetachHead/basedpyright/issues/330) and [#55](https://github.com/DetachHead/basedpyright/issues/55)). we recommend using `pyright: ignore` comments instead.
|
|
82
|
+
|
|
83
|
+
#### `reportPrivateLocalImportUsage` - prevent implicit re-exports in local code
|
|
84
|
+
|
|
85
|
+
pyright's `reportPrivateImportUsage` rule only checks for private imports of third party modules inside `py.typed` packages. but there's no reason your own code shouldn't be subject to the same restrictions. to explicitly re-export something, give it a redundant alias [as described in the "Stub Files" section of PEP484](https://peps.python.org/pep-0484/#stub-files) (although it only mentions stub files, other type checkers like mypy have also extended this behavior to source files as well):
|
|
86
|
+
|
|
87
|
+
```py
|
|
88
|
+
# foo.py
|
|
89
|
+
|
|
90
|
+
from .some_module import a # private import
|
|
91
|
+
from .some_module import b as b # explicit re-export
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
```py
|
|
95
|
+
# bar.py
|
|
96
|
+
|
|
97
|
+
# reportPrivateLocalImportUsage error, because `a` is not explicitly re-exported by the `foo` module:
|
|
98
|
+
from foo import a
|
|
99
|
+
|
|
100
|
+
# no error, because `b` is explicitly re-exported:
|
|
101
|
+
from foo import b
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
#### `reportImplicitRelativeImport` - reporting errors on invalid "relative" imports
|
|
105
|
+
|
|
106
|
+
pyright allows invalid imports such as this:
|
|
107
|
+
```py
|
|
108
|
+
# ./module_name/foo.py:
|
|
109
|
+
```
|
|
110
|
+
```py
|
|
111
|
+
# ./module_name/bar.py:
|
|
112
|
+
import foo # wrong! should be `import module_name.foo` or `from module_name import foo`
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
this may look correct at first glance, and will work when running `bar.py` directly as a script, but when it's imported as a module, it will crash:
|
|
116
|
+
```py
|
|
117
|
+
# ./main.py:
|
|
118
|
+
import module_name.bar # ModuleNotFoundError: No module named 'foo'
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
the new `reportImplicitRelativeImport` rule bans imports like this. if you want to do a relative import, the correct way to do it is by importing it from `.` (the current package):
|
|
122
|
+
```py
|
|
123
|
+
# ./module_name/bar.py:
|
|
124
|
+
from . import foo
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
#### `reportInvalidCast` - prevent non-overlapping `cast`s
|
|
128
|
+
|
|
129
|
+
most of the time when casting, you want to either cast to a narrower or wider type:
|
|
130
|
+
|
|
131
|
+
```py
|
|
132
|
+
foo: int | None
|
|
133
|
+
cast(int, foo) # narrower type
|
|
134
|
+
cast(object, foo) # wider type
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
but pyright doesn't prevent casts to a type that doesn't overlap with the original:
|
|
138
|
+
|
|
139
|
+
```py
|
|
140
|
+
foo: int
|
|
141
|
+
cast(str, foo)
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
in this example, it's impossible to be `foo` to be a `str` if it's also an `int`, because the `int` and `str` types do not overlap. the `reportInvalidCast` rule will report invalid casts like these.
|
|
145
|
+
|
|
146
|
+
##### note about casting with `TypedDict`s
|
|
147
|
+
|
|
148
|
+
a common use case of `cast` is to convert a regular `dict` into a `TypedDict`:
|
|
149
|
+
|
|
150
|
+
```py
|
|
151
|
+
foo: dict[str, int | str]
|
|
152
|
+
bar = cast(dict[{"foo": int, "bar": str}], foo)
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
unfortunately, this will cause a `reportInvalidCast` error when this rule is enabled, because although at runtime `TypedDict` is a `dict`, type checkers treat it as an unrelated subtype of `Mapping` that doesn't have a `clear` method, which would break its type-safety if it were to be called on a `TypedDict`.
|
|
156
|
+
|
|
157
|
+
this means that although casting between them is a common use case, `TypedDict`s and `dict`s technically do not overlap.
|
|
158
|
+
|
|
159
|
+
#### `reportUnsafeMultipleInheritance` - ban inheriting from multiple different base classes with constructors
|
|
160
|
+
|
|
161
|
+
multiple inheritance in python is awful:
|
|
162
|
+
|
|
163
|
+
```py
|
|
164
|
+
class Foo:
|
|
165
|
+
def __init__(self):
|
|
166
|
+
super().__init__()
|
|
167
|
+
class Bar:
|
|
168
|
+
def __init__(self):
|
|
169
|
+
...
|
|
170
|
+
|
|
171
|
+
class Baz(Foo, Bar):
|
|
172
|
+
...
|
|
173
|
+
|
|
174
|
+
Baz()
|
|
175
|
+
```
|
|
176
|
+
in this example, `Baz()` calls `Foo.__init__`, and the `super().__init__()` in `Foo` now calls to `Bar.__init__` even though `Foo` does not extend `Bar`.
|
|
177
|
+
|
|
178
|
+
this is complete nonsense and very unsafe, because there's no way to statically know what the super class will be.
|
|
179
|
+
|
|
180
|
+
pyright has the `reportMissingSuperCall` rule which, for this reason, complains even when your class doesn't have a base class. but that sucks because there's no way to know what arguments the unknown `__init__` takes, which means even if you do add a call to `super().__init__()` you have no clue what arguments it may take. so this rule is super annoying when it's enabled, and has very little benefit because it barely makes a difference in terms of safety.
|
|
181
|
+
|
|
182
|
+
`reportUnsafeMultipleInheritance` bans multiple inheritance when there are multiple base classes with an `__init__` or `__new__` method, as there's no way to guarantee that all of them will get called with the correct arguments (or at all). this allows `reportMissingSuperCall` to be more lenient. ie. when `reportUnsafeMultipleInheritance` is enabled, missing `super()` calls will only be reported on classes that actually have a base class.
|
|
183
|
+
|
|
184
|
+
### re-implementing pylance-exclusive features
|
|
185
|
+
|
|
186
|
+
basedpyright re-implements some of the features that microsoft made exclusive to pylance, which is microsoft's closed-source vscode extension built on top of the pyright language server with some additional exclusive functionality ([see the pylance FAQ for more information](https://github.com/microsoft/pylance-release/blob/main/FAQ.md#what-features-are-in-pylance-but-not-in-pyright-what-is-the-difference-exactly)).
|
|
187
|
+
|
|
188
|
+
the following features have been re-implemented in basedpyright's language server, meaning they are no longer exclusive to vscode. you can use any editor that supports the [language server protocol](https://microsoft.github.io/language-server-protocol/). for more information on installing pyright in your editor of choice, see [the installation instructions](https://detachhead.github.io/basedpyright/#/installation).
|
|
189
|
+
|
|
190
|
+
#### import suggestion code actions
|
|
191
|
+
pyright only supports import suggestions as autocomplete suggestions, but not as quick fixes (see [this issue](https://github.com/microsoft/pyright/issues/4263#issuecomment-1333987645)).
|
|
192
|
+
|
|
193
|
+
basedpyright re-implements pylance's import suggestion code actions:
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
#### semantic highlighting
|
|
198
|
+
|
|
199
|
+
|before|after|
|
|
200
|
+
|-|-|
|
|
201
|
+
|||
|
|
202
|
+
|
|
203
|
+
basedpyright re-implements pylance's semantic highlighting along with some additional improvements:
|
|
204
|
+
|
|
205
|
+
- variables marked as `Final` have the correct "read-only" colour
|
|
206
|
+
- supports [the new `type` keyword in python 3.12](https://peps.python.org/pep-0695/)
|
|
207
|
+
- `Final` variables are coloured as read-only
|
|
208
|
+
|
|
209
|
+
initial implementation of the semantic highlighting provider was adapted from the [pyright-inlay-hints](https://github.com/jbradaric/pyright-inlay-hints) project.
|
|
210
|
+
|
|
211
|
+
#### inlay hints
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
basedpyright contains several improvements and bug fixes to the original implementation adapted from [pyright-inlay-hints](https://github.com/jbradaric/pyright-inlay-hints).
|
|
216
|
+
|
|
217
|
+
#### docstrings for compiled builtin modules
|
|
218
|
+
|
|
219
|
+
many of the builtin modules are written in c, meaning the pyright language server cannot statically inspect and display their docstrings to the user. unfortunately they are also not available in the `.pyi` stubs for these modules, as [the typeshed maintainers consider it to be too much of a maintanance nightmare](https://github.com/python/typeshed/issues/4881#issuecomment-1275775973).
|
|
220
|
+
|
|
221
|
+
pylance works around this problem by running a "docstring scraper" script on the user's machine, which imports compiled builtin modules, scrapes all the docstrings from them at runtime, then saves them so that the language server can read them. however this isn't ideal for a few reasons:
|
|
222
|
+
|
|
223
|
+
- only docstrings for modules and functions available on the user's current OS and python version will be generated. so if you're working on a cross-platform project, or code that's intended to be run on multiple versions of python, you won't be able to see docstrings for compiled builtin modules that are not available in your current python installation.
|
|
224
|
+
- the check to determine whether a builtin object is compiled is done at the module level, meaning modules like `re` and `os` which have python source files but contain re-exports of compiled functions, are treated as if they are entirely written in python. this means many of their docstrings are still missing in pylance.
|
|
225
|
+
- it's (probably) slower because these docstrings need to be scraped either when the user launches vscode, or when the user hovers over a builtin class/function (disclaimer: i don't actually know when it runs, because pylance is closed source)
|
|
226
|
+
|
|
227
|
+
basedpyright solves all of these problems by using [docify](https://github.com/AThePeanut4/docify) to scrape the docstrings from all compiled builtin functions/classes for all currently supported python versions and all platforms (macos, windows and linux), and including them in the default typeshed stubs that come with the basedpyright package.
|
|
228
|
+
|
|
229
|
+
##### examples
|
|
230
|
+
|
|
231
|
+
here's a demo of basedpyright's builtin docstrings when running on windows, compared to pylance:
|
|
232
|
+
|
|
233
|
+
###### basedpyright
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
###### pylance
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
##### generating your own stubs with docstrings
|
|
242
|
+
|
|
243
|
+
basedpyright uses [docify](https://github.com/AThePeanut4/docify) to add docstrings to its stubs. if you have third party compiled modules and you want basedpyright to see its docstrings, you can do the same:
|
|
244
|
+
|
|
245
|
+
```
|
|
246
|
+
python -m docify path/to/stubs/for/package --in-place
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
or if you're using a different version of typeshed, you can use the `--if-needed` argument to replicate how basedpyright's version of typeshed is generated for your current platform and python version:
|
|
250
|
+
|
|
251
|
+
```
|
|
252
|
+
python -m docify path/to/typeshed/stdlib --if-needed --in-place
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
#### renaming packages and modules
|
|
256
|
+
|
|
257
|
+
when renaming a package or module, basedpyright will update all usages to the new name, just like pylance does:
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
### errors on invalid configuration
|
|
262
|
+
|
|
263
|
+
in pyright, if you have any invalid config, it may or may not print a warning to the console, then it will continue type-checking and the exit code will be 0 as long as there were no type errors:
|
|
264
|
+
|
|
265
|
+
```toml
|
|
266
|
+
[tool.pyright]
|
|
267
|
+
mode = "strict" # wrong! the setting you're looking for is called `typeCheckingMode`
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
in this example, it's very easy for errors to go undetected because you thought you were on strict mode, but in reality pyright just ignored the setting and silently continued type-checking on "basic" mode.
|
|
271
|
+
|
|
272
|
+
to solve this problem, basedpyright will exit with code 3 on any invalid config.
|
|
273
|
+
|
|
274
|
+
### fixes for the `reportRedeclaration` and `reportDuplicateImport` rules
|
|
275
|
+
|
|
276
|
+
pyright does not report redeclarations if the redeclaration has the same type:
|
|
277
|
+
```py
|
|
278
|
+
foo: int = 1
|
|
279
|
+
foo: int = 2 # no error
|
|
280
|
+
```
|
|
281
|
+
nor does it care if you have a duplicated import in multiple different `import` statements, or in aliases:
|
|
282
|
+
```py
|
|
283
|
+
from foo import bar
|
|
284
|
+
from bar import bar # no error
|
|
285
|
+
from baz import foo as baz, bar as baz # no error
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
basedpyright solves both of these problems by always reporting an error on a redeclaration or an import with the same name as an existing import.
|
|
289
|
+
|
|
290
|
+
### better defaults
|
|
291
|
+
we believe that type checkers and linters should be as strict as possible by default, making the user aware of all the available rules so they can more easily make informed decisions about which rules they don't want enabled in their project. that's why the following defaults have been changed in basedpyright
|
|
292
|
+
|
|
293
|
+
#### `typeCheckingMode`
|
|
294
|
+
used to be `basic`, but now defaults to `all`. in the future we intend to add [baseline](https://kotlinisland.github.io/basedmypy/baseline.html) to allow for easy adoption of more strict rules in existing codebases.
|
|
295
|
+
|
|
296
|
+
#### `pythonPlatform`
|
|
297
|
+
used to assume that the operating system pyright is being run on is the only operating system your code will run on, which is rarely the case. in basedpyright, `pythonPlatform` defaults to `All`, which assumes your code can run on any operating system.
|
|
298
|
+
|
|
299
|
+
### inline `TypedDict` support
|
|
300
|
+
|
|
301
|
+
pyright used to support defining `TypedDict`s inline, like so:
|
|
302
|
+
|
|
303
|
+
```py
|
|
304
|
+
foo: dict[{"foo": int, "bar": str}] = {"foo": "a", "bar": 1}
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
this was an experimental feature and was removed because it never made it into a PEP. but this functionality is very convenient and we see no reason not to continue supporting it, so we added it back in basedpyright.
|
|
308
|
+
|
|
309
|
+
currently this can be disabled by setting `enableExperimentalFeatures` to `false`. in the future there will be a separate `enableNonStandardFeatures` option once we [add more "based" features](#basedmypy-feature-parity).
|
|
310
|
+
|
|
311
|
+
### improved integration with CI platforms
|
|
312
|
+
|
|
313
|
+
regular pyright has third party integrations for github actions and gitlab, but they are difficult to install/set up. these integrations are built into basedpyright, which makes them much easier to use.
|
|
314
|
+
|
|
315
|
+
#### github actions
|
|
316
|
+
|
|
317
|
+
basedpyright automatically detects when it's running in a github action, and modifies its output to use [github workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions). this means errors will be displayed on the affected lines of code in your pull requests automatically:
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
this is an improvement to regular pyright, which requires you to use a [third party action](https://github.com/jakebailey/pyright-action) that [requires boilerplate to get working](https://github.com/jakebailey/pyright-action?tab=readme-ov-file#use-with-a-virtualenv). basedpyright just does it automatically without you having to do anything special:
|
|
322
|
+
|
|
323
|
+
```yaml
|
|
324
|
+
# .github/workflows/your_workflow.yaml
|
|
325
|
+
|
|
326
|
+
jobs:
|
|
327
|
+
check:
|
|
328
|
+
steps:
|
|
329
|
+
- run: ... # checkout repo, install dependencies, etc
|
|
330
|
+
- run: basedpyright # no additional arguments required. it automatically detects if it's running in a github action
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
#### gitlab code quality reports
|
|
334
|
+
|
|
335
|
+
the `--gitlabcodequality` argument will output a [gitlab code quality report](https://docs.gitlab.com/ee/ci/testing/code_quality.html) which shows up on merge requests:
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
to enable this in your gitlab CI, just specify a file path to output the report to, and in the `artifacts.reports.codequality` section of your `.gitlab-ci.yml` file:
|
|
340
|
+
|
|
341
|
+
```yaml
|
|
342
|
+
basedpyright:
|
|
343
|
+
script: basedpyright --gitlabcodequality report.json
|
|
344
|
+
artifacts:
|
|
345
|
+
reports:
|
|
346
|
+
codequality: report.json
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
## basedmypy feature parity
|
|
350
|
+
|
|
351
|
+
[basedmypy](https://github.com/kotlinisland/basedmypy) is a fork of mypy with a similar goal in mind: to fix some of the serious problems in mypy that do not seem to be a priority for the maintainers. it also adds many new features which may not be standardized but greatly improve the developer experience when working with python's far-from-perfect type system.
|
|
352
|
+
|
|
353
|
+
we aim to [port most of basedmypy's features to basedpyright](https://github.com/DetachHead/basedpyright/issues?q=is%3Aissue+is%3Aopen+label%3A%22basedmypy+feature+parity%22), however as mentioned above our priority is to first fix the critical problems with pyright.
|
|
354
|
+
|
|
355
|
+
note that any non-standard features we add will be optional, as we intend to support library developmers who can't control what type checker their library is used with.
|
|
356
|
+
|
|
357
|
+
# pypi package
|
|
358
|
+
|
|
359
|
+
basedpyright differs from pyright by publishing the command line tool as a [pypi package](https://pypi.org/project/basedpyright/) instead of an npm package. this makes it far more convenient for python developers to use, since there's no need to install any additional tools.
|
|
360
|
+
|
|
361
|
+
for more information, see the [installation instructions](https://detachhead.github.io/basedpyright/#/installation?id=command-line).
|
|
362
|
+
|
|
363
|
+
# vscode extension
|
|
364
|
+
|
|
365
|
+
## install
|
|
366
|
+
|
|
367
|
+
install the extension from [the vscode extension marketplace](https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright) or [the open VSX registry](https://open-vsx.org/extension/detachhead/basedpyright)
|
|
368
|
+
|
|
369
|
+
## usage
|
|
370
|
+
|
|
371
|
+
the basedpyright vscode extension will automatically look for the pypi package in your python environment.
|
|
372
|
+
|
|
373
|
+
if you're adding basedpyright as a development dependency in your project, we recommend adding it to the recommended extensions list in your workspace to prompt others working on your repo to install it:
|
|
374
|
+
|
|
375
|
+
```jsonc
|
|
376
|
+
// .vscode/extensions.json
|
|
377
|
+
|
|
378
|
+
{
|
|
379
|
+
"recommendations": ["detachhead.basedpyright"]
|
|
380
|
+
}
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
in `.vscode/settings.json`, remove any settings starting with `python.analysis`, as they are not used by basedpyright. you should instead set these settings using the `tool.basedpyright` (or `tool.pyright`) section in `pyroject.toml` ([see below](#pyprojecttoml))
|
|
384
|
+
|
|
385
|
+
you should also disable the built in language server support from the python extension, as it conflicts with basedpyright's language server. the basedpyright extension will detect this problem and suggest fixing it automatically.
|
|
386
|
+
|
|
387
|
+
<!-- if changing this section title, make sure you also change the url in the pylance notification in the vscode extension -->
|
|
388
|
+
## using basedpyright with pylance (not recommended)
|
|
389
|
+
|
|
390
|
+
unless you depend on any pylance-exclusive features that haven't yet been re-implemented in basedpyright, it's recommended to disable/uninstall the pylance extension.
|
|
391
|
+
|
|
392
|
+
if you do want to continue using pylance, all of the options and commands in basedpyright have been renamed to avoid any conflicts with the pylance extension, and the restriction that prevents both extensions from being enabled at the same time has been removed. for an optimal experience you should change the following settings in your `.vscode/settings.json` file:
|
|
393
|
+
|
|
394
|
+
- disable pylance's type-checking by setting `"python.analysis.typeCheckingMode"` to `"off"`. this will prevent pylance from displaying duplicated errors from its bundled pyright version alongside the errors already displayed by the basedpyright extension.
|
|
395
|
+
- disable basedpyright's LSP features by setting `"basedpyright.disableLanguageServices"` to `true`. this will prevent duplicated hover text and other potential issues with pylance's LSP. keep in mind that this may result in some inconsistent behavior since pylance uses its own version of the pyright LSP.
|
|
396
|
+
|
|
397
|
+
```json
|
|
398
|
+
{
|
|
399
|
+
"python.analysis.typeCheckingMode": "off",
|
|
400
|
+
"basedpyright.disableLanguageServices": true
|
|
401
|
+
}
|
|
402
|
+
```
|
|
403
|
+
*(the basedpyright extension will detect this problem and suggest fixing it automatically)*
|
|
404
|
+
|
|
405
|
+
# playground
|
|
406
|
+
|
|
407
|
+
you can try basedpyright in your browser using the [basedpyright playground](http://basedpyright.com)
|
|
408
|
+
|
|
409
|
+
# pre-commit hook
|
|
410
|
+
|
|
411
|
+
integration with [pre-commit](https://pre-commit.com) is also supported.
|
|
412
|
+
|
|
413
|
+
```yaml
|
|
414
|
+
# .pre-commit-config.yaml
|
|
415
|
+
|
|
416
|
+
repos:
|
|
417
|
+
- repo: https://github.com/DetachHead/basedpyright-pre-commit-mirror
|
|
418
|
+
rev: v1.13.0 # or whatever the latest version is at the time
|
|
419
|
+
hooks:
|
|
420
|
+
- id: basedpyright
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
for more information, see the documentation [here](https://github.com/DetachHead/basedpyright-pre-commit-mirror/blob/main/README.md)
|
|
424
|
+
|
|
425
|
+
# recommended setup
|
|
426
|
+
|
|
427
|
+
it's recommended to use both the basedpyright cli and vscode extension in your project. the vscode extension is for local development and the cli is for your CI.
|
|
428
|
+
|
|
429
|
+
below are the changes i recommend making to your project when adopting basedpyright
|
|
430
|
+
|
|
431
|
+
## `pyproject.toml`
|
|
432
|
+
|
|
433
|
+
we recommend using [pdm with pyprojectx](https://pdm-project.org/latest/#other-installation-methods) (click the "inside project" tab) to manage your dependencies.
|
|
434
|
+
|
|
435
|
+
```toml
|
|
436
|
+
[tool.pyprojectx]
|
|
437
|
+
main = ["pdm==2.12.4"] # installs pdm to your project instead of globally
|
|
438
|
+
|
|
439
|
+
[tool.pdm.dev-dependencies] # or the poetry equivalent
|
|
440
|
+
dev = [
|
|
441
|
+
"basedpyright", # you can pin the version here if you want, or just rely on the lockfile
|
|
442
|
+
]
|
|
443
|
+
|
|
444
|
+
[tool.basedpyright]
|
|
445
|
+
# many settings are not enabled even in strict mode, which is why basedpyright includes an "all" option
|
|
446
|
+
# you can then decide which rules you want to disable
|
|
447
|
+
typeCheckingMode = "all"
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
pinning your dependencies is important because it allows your CI builds to be reproducible (ie. two runs on the same commit will always produce the same result). basedpyright ensures that the version of pyright used by vscode always matches this pinned version.
|