repository·main·Indexed 25 days ago
https://github.com/detachhead/basedpyrightA fork of Microsoft's pyright enhanced with additional type checking improvements and features typically found in Pylance. It includes a baseline feature for managing existing errors, a "recommended" typeCheckingMode by default, stricter diagnostics for redeclarations and duplicate imports, and a browser-adapted version via the browser-basedpyright package.
The browser-basedpyright package is a version of basedpyright specifically adapted to run within a web browser environment. It is an adaptation of the microbit-foundation pyright fork.
Important Recommendation: Unless you have a specific requirement for a browser-based implementation, it is recommended to use the standard basedpyright package installed via PyPI instead.
basedpyright is a type checker that provides several advantages over the standard Pyright:
basedpyright re-implements several features that were previously exclusive to Microsoft's closed-source Pylance extension, making them available in any LSP-compatible editor:
type keyword and Final variable coloring.Callable types.docify to include docstrings for compiled builtin functions/classes for all supported Python versions and platforms (macOS, Windows, Linux) within the default typeshed stubs.In Pyright, a symbol is any name that is not a keyword (e.g., classes, functions, variables, parameters). Symbols exist within scopes, which define visibility.
Common scopes include:
int, list).The repository is organized into several packages that serve different entry points and environments:
packages/vscode-pyright/src/extension.ts: LSP client entry point for the VS Code extension.packages/pyright-internal/src/pyright.ts: Main entry point for the command-line tool.packages/pyright-internal/src/server.ts: Main entry point for the LSP server.packages/pyright: The core basedpyright npm package.packages/browser-pyright: A build of basedpyright designed to run in a browser.basedpyright: The PyPI package wrapper for the npm package (allows usage without manual Node.js installation).packages/pyright-internal/typeshed-fallback/: Contains recent copies of Typeshed type stub files for the Python stdlib.docstubs: Generated stubs containing docstrings for compiled modules.Core logic for parsing and analysis is located in packages/pyright-internal/src/analyzer, packages/pyright-internal/src/parser, and packages/pyright-internal/src/common.
A TUI (Terminal User Interface) tool is provided to assist with the localization process. It allows you to:
The interface is built with textual and supports mouse interaction:
Note: If the "Compare message keys differences" operation is active, you can only close the popup by pressing the C key.
# use uv
./gg.cmd uv run build/py_latest/localization_helper.py
# or from inside the venv
npm run localization-helperThe baseline feature allows you to adopt new tools or enable new checks without being overwhelmed by existing errors. It tracks current errors in a baseline file and only reports errors in newly written or modified code.
To enable baseline, generate the baseline file by running the following command in your terminal:
basedpyright --writebaselineAlternatively, you can run the basedpyright: Write new errors to baseline task within your editor. This creates a file at ./.basedpyright/baseline.json. You should commit this file to your version control system.
Pyright functions as a language server to provide IDE-like features during development. Key capabilities include:
To provide a high-quality developer experience, follow these annotation patterns:
Sequence[str] instead of list[str] or Mapping[str, int] instead of dict[str, int] to allow more flexible caller arguments.@overload for multiple return types: Use the typing.overload mechanism when a function's return type depends on its input arguments.* for keyword-only arguments and / for positional-only arguments to clarify the API.TypeVar and Callable. For complex signature mutations, consider ParamSpec and Concatenate (Python 3.10+).Literal for specificity: Use Literal for specific allowed values instead of broad types.Final for constants: Mark constants with Final to indicate they should not be reassigned.Generic types (like list[int]) use type arguments in square brackets to specify the type of their contents.
Mutable container types (like list, dict, or set) are typically invariant. This means the type argument must match exactly. For example, you cannot assign a list[int] to a variable declared as list[int | None] because appending None to the latter would violate the type contract of the former.
To resolve assignability errors with mutable containers, switch to their immutable counterparts. Immutable types are generally more flexible with type arguments.
| Mutable Type | Immutable Type |
|---|---|
list | Sequence |
dict | Mapping |
set | Container |
| n/a | tuple |
Example of resolving an invariance error by using Sequence instead of list:
my_list_1: list[int] = [1, 2, 3]
# my_list_2: list[int | None] = my_list_1 # Error due to invariance
my_list_2: Sequence[int | None] = my_list_1 # No longer an error