0
# Typeshed
1

2
The official repository of type stubs for the Python standard library and third-party packages. Typeshed provides comprehensive type annotations that enable static type checking, code completion, and other developer tools to understand Python code without needing to execute it.
3

4
## Package Information
5

6
- **Package Name**: typeshed
7
- **Package Type**: Git Repository
8
- **Language**: Python Type Stubs (.pyi files)
9
- **Repository**: `git clone https://github.com/python/typeshed.git`
10
- **Usage**: Bundled with type checkers (mypy, pyright, PyCharm)
11

12
## Core Imports
13

14
Typeshed is not directly imported - it provides type information consumed by type checkers:
15

16
```python
17
# Type checkers automatically use typeshed for standard library
18
import os
19
import sys
20
from typing import Dict, List
21

22
# Third-party package stubs are installed via pip
23
# pip install types-requests types-flask
24
import requests
25
import flask
26
```
27

28
## Basic Usage
29

30
### Using with Type Checkers
31

32
```python
33
# mypy configuration (mypy.ini)
34
[mypy]
35
python_version = 3.9
36
warn_return_any = True
37
warn_unused_configs = True
38

39
# pyright configuration (pyrightconfig.json)
40
{
41
    "pythonVersion": "3.9",
42
    "typeCheckingMode": "basic",
43
    "useLibraryCodeForTypes": true
44
}
45
```
46

47
### Installing Third-party Stubs
48

49
```bash
50
# Install type stubs for specific packages
51
pip install types-requests    # For requests library
52
pip install types-redis      # For redis library  
53
pip install types-flask      # For Flask framework
54

55
# View available stub packages
56
pip search types-
57
```
58

59
## Architecture
60

61
Typeshed is organized into two main directories:
62

63
- **stdlib/**: Type stubs for Python standard library modules (742+ .pyi files)
64
- **stubs/**: Type stubs for 188+ third-party packages, each in separate directories
65
- **tests/**: Test infrastructure ensuring stub accuracy and completeness
66
- **scripts/**: Automation tools for maintenance and validation
67

68
The repository supports Python versions 3.9 through 3.14, with version-specific stubs managed through conditional imports and version checks.
69

70
## Capabilities
71

72
### Standard Library Type Stubs
73

74
Comprehensive type annotations for Python's built-in modules and packages, covering core functionality like data structures, I/O, networking, concurrency, and system interfaces.
75

76
```python { .api }
77
# Examples of stdlib modules with type stubs:
78
import os                    # File system operations
79
import sys                   # System-specific parameters
80
import typing                # Type hints and generics
81
import asyncio               # Asynchronous programming
82
import collections           # Specialized container datatypes
83
import functools             # Higher-order functions and decorators
84
import itertools             # Functions for creating iterators
85
import json                  # JSON encoder/decoder
86
import re                    # Regular expression operations
87
import threading             # Thread-based parallelism
88
import urllib                # URL handling modules
89
```
90

91
[Standard Library Stubs](./stdlib-stubs.md)
92

93
### Third-party Package Stubs
94

95
Type stubs for popular Python packages maintained by the community, enabling type checking for external dependencies.
96

97
```python { .api }
98
# Popular third-party packages with type stubs:
99
import requests              # HTTP library
100
import flask                 # Web framework  
101
import django                # Web framework
102
import numpy                 # Scientific computing
103
import pandas                # Data analysis
104
import matplotlib            # Plotting library
105
import sqlalchemy            # Database toolkit
106
import redis                 # Redis client
107
import boto3                 # AWS SDK
108
import pydantic              # Data validation
109
```
110

111
[Third-party Stubs](./third-party-stubs.md)
112

113
### Type Stub Structure
114

115
All stub files follow Python's .pyi format with type annotations but no implementation code.
116

117
```python { .api }
118
# Example stub file structure (.pyi)
119
from typing import Any, Optional, Union, overload
120
from types import TracebackType
121

122
class ExampleClass:
123
    def __init__(self, value: str) -> None: ...
124
    
125
    @overload
126
    def method(self, arg: str) -> str: ...
127
    @overload  
128
    def method(self, arg: int) -> int: ...
129
    def method(self, arg: Union[str, int]) -> Union[str, int]: ...
130
    
131
    @property
132
    def value(self) -> str: ...
133

134
def function(
135
    required: str,
136
    optional: Optional[int] = None,
137
    *args: Any,
138
    **kwargs: Any
139
) -> bool: ...
140
```
141

142
### Version Support
143

144
Version-specific type information handled through conditional imports and version checks.
145

146
```python { .api }
147
import sys
148
from typing import TYPE_CHECKING
149

150
if sys.version_info >= (3, 10):
151
    from typing import TypeAlias
152
else:
153
    from typing_extensions import TypeAlias
154

155
if TYPE_CHECKING:
156
    from typing_extensions import Self
157
```
158

159
### Quality Assurance
160

161
Automated testing and validation ensures stub accuracy and completeness.
162

163
```python { .api }
164
# Test infrastructure capabilities:
165
# - Syntax validation for all .pyi files
166
# - Import testing against target Python versions  
167
# - Consistency checks between stubs and runtime
168
# - Coverage analysis for public APIs
169
# - Performance regression testing
170
```
171

172
## Installation Methods
173

174
### Type Checker Integration
175

176
Most type checkers bundle standard library stubs automatically:
177

178
```bash
179
# mypy (includes stdlib stubs)
180
pip install mypy
181
mypy your_code.py
182

183
# pyright/pylance (includes stdlib stubs)  
184
npm install -g pyright
185
pyright your_code.py
186
```
187

188
### Third-party Stub Installation
189

190
Install specific stub packages for external dependencies:
191

192
```bash
193
# Individual packages
194
pip install types-requests types-flask types-redis
195

196
# Multiple packages  
197
pip install types-requests types-flask types-redis types-boto3
198

199
# Check installed stub packages
200
pip list | grep types-
201
```
202

203
## Error Handling
204

205
### Missing Stubs
206

207
When type stubs are missing, type checkers may show warnings:
208

209
```python
210
import some_library  # type: ignore[import-untyped]
211

212
# Or install stub package if available:
213
# pip install types-some-library
214
```
215

216
### Stub Inconsistencies
217

218
Report issues to typeshed when stubs don't match runtime behavior:
219

220
```python
221
# If you encounter incorrect type annotations,
222
# report at: https://github.com/python/typeshed/issues
223
```
224

225
## Contributing
226

227
### Development Setup
228

229
```bash
230
git clone https://github.com/python/typeshed.git
231
cd typeshed
232
python -m pip install -r requirements-tests.txt
233
```
234

235
### Running Tests
236

237
```bash
238
# Run all tests
239
python tests/mypy_test.py
240
python tests/pyright_test.py
241

242
# Test specific stubs
243
python tests/stubtest_third_party.py requests
244
```
245

246
### Stub Guidelines
247

248
- Follow PEP 484, 585, 586, 612, 613 type hinting standards
249
- Match runtime behavior exactly
250
- Use `...` for function/method bodies  
251
- Provide complete type information for public APIs
252
- Support multiple Python versions when applicable