0
# pyupgrade
1
2
A tool and pre-commit hook to automatically upgrade Python syntax for newer versions of the language. pyupgrade modernizes Python code by transforming legacy syntax patterns into their modern equivalents, supporting upgrades across Python versions from 3.6 through 3.14+.
3
4
## Package Information
5
6
- **Package Name**: pyupgrade
7
- **Language**: Python
8
- **Installation**: `pip install pyupgrade`
9
- **Minimum Python Version**: 3.9+
10
11
## Core Imports
12
13
For command-line usage:
14
```bash
15
pyupgrade [OPTIONS] [FILES]
16
```
17
18
For programmatic usage:
19
```python
20
from pyupgrade._main import main
21
from pyupgrade._data import Settings
22
```
23
24
## Basic Usage
25
26
### Command Line Interface
27
28
```bash
29
# Upgrade a single file
30
pyupgrade example.py
31
32
# Upgrade multiple files
33
pyupgrade src/*.py
34
35
# Upgrade for specific Python version
36
pyupgrade --py311-plus src/*.py
37
38
# Use as pre-commit hook
39
pyupgrade --py310-plus --keep-percent-format src/*.py
40
```
41
42
### Programmatic Interface
43
44
```python
45
from pyupgrade._main import main, _fix_plugins, _fix_tokens
46
from pyupgrade._data import Settings
47
48
# Use main function
49
exit_code = main(['--py310-plus', 'example.py'])
50
51
# Transform code programmatically
52
settings = Settings(min_version=(3, 10), keep_percent_format=True)
53
upgraded_code = _fix_plugins(source_code, settings)
54
upgraded_code = _fix_tokens(upgraded_code)
55
```
56
57
## Architecture
58
59
pyupgrade uses a two-phase transformation approach:
60
61
- **Plugin System**: AST-based transformations for complex syntax upgrades (set literals, f-strings, type annotations, etc.)
62
- **Token System**: Token-level transformations for simpler patterns (escape sequences, parentheses, format strings)
63
64
The plugin system uses a registration mechanism where plugins register callbacks for specific AST node types. Each plugin can examine the AST and generate token-level transformations that are applied during the second phase.
65
66
## Capabilities
67
68
### Command Line Interface
69
70
Command-line tool for upgrading Python files with extensive configuration options for different Python versions and preservation settings.
71
72
```python { .api }
73
def main(argv: Sequence[str] | None = None) -> int:
74
"""
75
Main entry point for command-line interface.
76
77
Args:
78
argv: Command line arguments (None uses sys.argv)
79
80
Returns:
81
Exit code (0 for success, 1 for failure/changes made)
82
"""
83
```
84
85
[Command Line Interface](./cli.md)
86
87
### Core Transformation Engine
88
89
Core functionality for applying syntax transformations through plugin and token systems.
90
91
```python { .api }
92
def _fix_plugins(contents_text: str, settings: Settings) -> str:
93
"""Apply plugin-based AST transformations."""
94
95
def _fix_tokens(contents_text: str) -> str:
96
"""Apply token-level transformations."""
97
98
class Settings(NamedTuple):
99
min_version: Version = (3,)
100
keep_percent_format: bool = False
101
keep_mock: bool = False
102
keep_runtime_typing: bool = False
103
```
104
105
[Core Transformation Engine](./core-engine.md)
106
107
### Plugin System
108
109
Extensible plugin architecture for registering AST-based syntax transformations.
110
111
```python { .api }
112
def register(tp: type[AST_T]) -> Callable[[ASTFunc[AST_T]], ASTFunc[AST_T]]:
113
"""Register transformation function for AST node type."""
114
115
def visit(funcs: ASTCallbackMapping, tree: ast.Module, settings: Settings) -> dict[Offset, list[TokenFunc]]:
116
"""Visit AST and collect transformation callbacks."""
117
118
class State(NamedTuple):
119
settings: Settings
120
from_imports: dict[str, set[str]]
121
in_annotation: bool = False
122
```
123
124
[Plugin System](./plugin-system.md)
125
126
### AST Utilities
127
128
Helper functions for working with Python AST nodes during transformations.
129
130
```python { .api }
131
def ast_parse(contents_text: str) -> ast.Module:
132
"""Parse Python source into AST."""
133
134
def ast_to_offset(node: ast.expr | ast.stmt) -> Offset:
135
"""Convert AST node position to token offset."""
136
137
def is_name_attr(node: ast.AST, imports: dict[str, set[str]], mods: tuple[str, ...], names: Container[str]) -> bool:
138
"""Check if node matches imported name or attribute."""
139
```
140
141
[AST Utilities](./ast-utilities.md)
142
143
### Token Manipulation
144
145
Comprehensive token-level manipulation utilities for precise code transformations.
146
147
```python { .api }
148
def parse_call_args(tokens: list[Token], i: int) -> tuple[list[tuple[int, int]], int]:
149
"""Parse function call arguments from tokens."""
150
151
def replace_call(tokens: list[Token], start: int, end: int, args: list[tuple[int, int]], tmpl: str, *, parens: Sequence[int] = ()) -> None:
152
"""Replace function call with template."""
153
154
class Block(NamedTuple):
155
"""Code block boundaries in tokens."""
156
start: int
157
colon: int
158
block: int
159
end: int
160
line: bool
161
```
162
163
[Token Manipulation](./token-manipulation.md)
164
165
### String Processing
166
167
Specialized utilities for processing and transforming string literals and format strings.
168
169
```python { .api }
170
def parse_format(s: str) -> list[DotFormatPart]:
171
"""Parse format string into component parts."""
172
173
def unparse_parsed_string(parsed: list[DotFormatPart]) -> str:
174
"""Convert parsed format parts back to string."""
175
176
def is_codec(encoding: str, name: str) -> bool:
177
"""Check if encoding matches codec name."""
178
```
179
180
[String Processing](./string-processing.md)
181
182
## Types
183
184
```python { .api }
185
# Version and callback types
186
Version = tuple[int, ...]
187
TokenFunc = Callable[[int, list[Token]], None]
188
ASTFunc = Callable[[State, AST_T, ast.AST], Iterable[tuple[Offset, TokenFunc]]]
189
190
# String format processing
191
DotFormatPart = tuple[str, Optional[str], Optional[str], Optional[str]]
192
193
# Token manipulation structures
194
class Victims(NamedTuple):
195
starts: list[int]
196
ends: list[int]
197
first_comma_index: int | None
198
arg_index: int
199
```