repository·main·Indexed 12 days ago
https://github.com/microsoft/pyrightA high-performance, standards-based static type checker for Python designed for large-scale codebases. It is available as a command-line tool, a Language Server (LSP), and a Visual Studio Code extension (ms-pyright.pyright).
Pyright is a high-performance, standards-compliant static type checker for Python. It is designed to handle large Python codebases efficiently. Pyright can be consumed in three primary ways:
ms-pyright.pyright) for seamless integration within VS Code.Pyright is a high-performance, standards-based static type checker for Python designed for large codebases. You can use it in two primary ways:
ms-pyright.pyright extension to get type checking and language service features directly in your editor.You can also test Pyright's capabilities in your browser using the Pyright Playground.
Pyright is a fast, incremental type checker that supports a wide range of Python typing standards (PEPs) and features:
if/else statements).Pyright supports numerous PEPs, including but not limited to:
Pyright and Mypy are both Python static type checkers, but they differ in design goals and implementation.
Key Differences:
--check-untyped-defs flag is enabled.The Pyright Type Server is a specialized component that provides direct access to Python type information via the Type Server Protocol (TSP). Unlike the Language Server Protocol (LSP), which is optimized for editor features (like hover or completions), TSP is designed for tools that need deep type information without editor-oriented overhead.
TSP is a JSON-RPC protocol layered on top of the same transport as LSP. A client can open documents using standard LSP notifications (e.g., textDocument/didOpen) and then query the type server for specific type-related data.
Pyright prioritizes type stub (.pyi) files over Python source (.py) files when resolving imports.
.pyi): Pyright always attempts to resolve an import with a .pyi file first.py.typed): If no stub is found, Pyright checks if the package contains a py.typed file (per PEP 561). If present, Pyright uses the inline type information from the source.Unknown: If no stub is found and no py.typed file exists, Pyright treats all symbols from that module as type Unknown. Wildcard imports (from foo import *) will not populate the namespace with specific symbol names.To ensure high-quality static type checking, it is highly recommended to use packages that include py.typed or provide type stub files.
reportUnnecessaryTypeIgnoreComment configuration option is enabled, Pyright will report any # type: ignore or # pyright: ignore comments that are no longer needed (e.g., because the code no longer violates the rule), allowing you to keep your codebase clean.If a function or method lacks a return type annotation, Pyright infers the return type from return and yield statements within the function body (including the implied return None at the end). This enables better completion suggestions and coverage without requiring manual annotations for trivial types.
In contrast, Mypy assumes functions without return annotations have a return type of Any.
Pyright distinguishes between explicit and implicit forms of Any:
Any: When a developer explicitly uses the Any type (e.g., list[Any]).Any (Unknown): When a type is missing or cannot be determined (e.g., list becomes list[Unknown]).Pyright's "strict" modes include checks that report the use of Unknown types, helping developers identify where missing type information might be masking errors.
Pyright can perform narrowing even when an else block is missing, provided it can statically prove that the code must have entered one of the preceding if or elif blocks. This is known as narrowing for implied else.
This is particularly useful for:
Enum in an if/elif chain, Pyright knows the variable is fully handled.Union (e.g., str | int), Pyright knows the variable is handled.Limitations:
from enum import Enum
class Color(Enum):
RED = 1
BLUE = 2
GREEN = 3
def func3(color: Color) -> str:
if color == Color.RED or color == Color.BLUE:
return "yes"
elif color == Color.GREEN:
return "no"
# Pyright knows all Color members are covered, so no 'None' return errorPyright attempts to follow runtime behavior for constructor calls. It evaluates the flow: metaclass.__call__ $\rightarrow$ class.__new__ $\rightarrow$ class.__init__.
If __new__ returns an instance of the class (or a child), Pyright proceeds to evaluate __init__. If a custom metaclass is present, Pyright evaluates its __call__ method. If a class provides a __new__ method that returns a type other than the class being constructed, Pyright assumes __init__ will not be called.
Pyright supports configuration files that allow for granular control over settings. You can define different "execution environments" for specific subdirectories within your source base. This is useful for monorepos or projects with mixed requirements. Each environment can specify its own: