0
# Basedpyright
1

2
Basedpyright is a static type checker for Python, built as a fork of Microsoft's pyright with enhanced type checking capabilities, additional pylance features, and various improvements. It provides comprehensive static analysis, intelligent error detection, and language server protocol support for Python development environments.
3

4
## Package Information
5

6
- **Package Name**: basedpyright
7
- **Language**: Python
8
- **Installation**: `pip install basedpyright` or `uv add basedpyright`
9

10
## Core Imports
11

12
```python
13
from basedpyright.pyright import main as pyright_main
14
from basedpyright.langserver import main as langserver_main
15
from basedpyright.run_node import run
16
```
17

18
## Basic Usage
19

20
### Command Line Type Checking
21

22
```bash
23
# Check a single file
24
basedpyright myfile.py
25

26
# Check a project directory
27
basedpyright src/
28

29
# Check with specific configuration
30
basedpyright --project pyproject.toml
31

32
# Show version information
33
basedpyright --version
34
```
35

36
### Language Server Mode
37

38
```bash
39
# Start language server for IDE integration
40
basedpyright-langserver --stdio
41
```
42

43
### Programmatic Usage (Python API)
44

45
```python
46
from basedpyright.pyright import main as pyright_main
47
from basedpyright.langserver import main as langserver_main
48

49
# Execute type checking programmatically (exits process)
50
pyright_main()  # Equivalent to running 'basedpyright' command
51

52
# Start language server programmatically (exits process)  
53
langserver_main()  # Equivalent to running 'basedpyright-langserver' command
54
```
55

56
## Capabilities
57

58
### CLI Type Checking
59

60
Primary interface for static type analysis of Python code. Supports project-wide checking, incremental analysis, and comprehensive error reporting.
61

62
```python { .api }
63
def main():
64
    """
65
    Main entry point for basedpyright CLI type checker.
66
    
67
    Executes the Node.js basedpyright implementation with command line arguments.
68
    Supports all pyright CLI options and basedpyright-specific enhancements.
69
    
70
    Exits the process with the type checker's exit code.
71
    """
72
```
73

74
### Language Server Protocol
75

76
Provides IDE integration through Language Server Protocol, enabling real-time type checking, autocompletion, hover information, and other language features.
77

78
```python { .api }  
79
def main():
80
    """
81
    Entry point for basedpyright language server.
82
    
83
    Starts the language server for IDE integration via Language Server Protocol.
84
    Communicates through stdin/stdout for editor integration.
85
    
86
    Exits the process when language server terminates.
87
    """
88
```
89

90
### Node.js Execution Helper
91

92
Internal utility for executing the underlying Node.js type checker implementation.
93

94
```python { .api }
95
def run(script_name: str):
96
    """
97
    Execute a Node.js script from the basedpyright package.
98
    
99
    Args:
100
        script_name (str): Name of the JavaScript file to execute (without .js extension).
101
                          Valid values:
102
                          - "index" - executes the main CLI type checker
103
                          - "langserver.index" - executes the language server
104
    
105
    The function looks for {script_name}.js in the basedpyright package directory
106
    and executes it with Node.js, passing through all command line arguments.
107
    
108
    Exits the process with the Node.js script's exit code.
109
    """
110
```
111

112
## Configuration
113

114
### Project Configuration
115

116
Basedpyright can be configured through multiple methods:
117

118
**pyproject.toml** (recommended):
119
```toml
120
[tool.basedpyright]
121
pythonVersion = "3.11"
122
include = ["src"]
123
exclude = ["tests"]
124
reportMissingImports = true
125
```
126

127
**pyrightconfig.json**:
128
```json
129
{
130
  "pythonVersion": "3.11",
131
  "include": ["src"],
132
  "exclude": ["tests"],
133
  "reportMissingImports": true
134
}
135
```
136

137
### Supported Python Versions
138

139
- Python 3.8, 3.9, 3.10, 3.11, 3.12, 3.13
140

141
### Runtime Requirements
142

143
- **nodejs-wheel-binaries>=20.13.1**: Provides Node.js runtime for executing the type checker
144

145
## CLI Commands
146

147
### basedpyright
148

149
```bash
150
# Entry point: basedpyright.pyright:main
151
# Description: Main type checker CLI command
152
# Common usage patterns:
153

154
# Basic type checking
155
basedpyright .
156
basedpyright src/ tests/
157

158
# With configuration
159
basedpyright --project pyproject.toml
160
basedpyright --pythonversion 3.11
161

162
# Output formats  
163
basedpyright --outputjson
164
basedpyright --stats
165

166
# Watch mode
167
basedpyright --watch
168
```
169

170
### basedpyright-langserver
171

172
```bash
173
# Entry point: basedpyright.langserver:main  
174
# Description: Language server protocol implementation
175
# Usage:
176

177
basedpyright-langserver --stdio
178
basedpyright-langserver --socket=5007
179
```
180

181
## Error Handling
182

183
The CLI commands exit with standard exit codes:
184
- **0**: No errors found
185
- **1**: Type errors or other issues found  
186
- **2**: Fatal error or invalid configuration
187

188
Language server mode runs continuously until terminated by the client.
189

190
## Integration Notes
191

192
- **IDE Integration**: Use `basedpyright-langserver` for VS Code, PyCharm, Vim, Emacs, and other LSP-compatible editors
193
- **CI/CD**: Use `basedpyright` in build scripts and pre-commit hooks
194
- **API Limitations**: No programmatic Python API for accessing type checking results - all functionality accessed through CLI or language server protocol
195

196