0
# Refurb
1

2
A Python code analysis tool that specializes in modernizing and refurbishing Python codebases by detecting opportunities to make code more elegant, readable, and Pythonic. Built on Mypy for robust type analysis, Refurb identifies patterns where code can be simplified using modern Python features and idioms.
3

4
## Package Information
5

6
- **Package Name**: refurb
7
- **Language**: Python
8
- **Installation**: `pip install refurb`
9

10
## Core Imports
11

12
```python
13
import refurb
14
```
15

16
For the main CLI interface:
17

18
```python
19
from refurb.main import main, run_refurb
20
```
21

22
For plugin development:
23

24
```python
25
from refurb.error import Error
26
from refurb.settings import Settings
27
from refurb.visitor import RefurbVisitor
28
from refurb.checks.common import is_equivalent, stringify
29
```
30

31
## Basic Usage
32

33
### Command Line Usage
34

35
```bash
36
# Analyze files or directories
37
refurb src/
38

39
# Ignore specific error codes
40
refurb --ignore FURB105,FURB123 src/
41

42
# Enable additional checks
43
refurb --enable FURB999 src/
44

45
# Load custom checks
46
refurb --load my_custom_checks src/
47

48
# Output as GitHub annotations
49
refurb --format github src/
50

51
# Get explanation for an error
52
refurb --explain FURB105
53

54
# Generate boilerplate for new check
55
refurb gen
56
```
57

58
### Programmatic Usage
59

60
```python
61
from refurb.main import run_refurb
62
from refurb.settings import load_settings
63

64
# Load settings from command line args
65
settings = load_settings(["src/", "--ignore", "FURB105"])
66

67
# Run refurb analysis
68
errors = run_refurb(settings)
69

70
# Process results
71
for error in errors:
72
    if isinstance(error, str):
73
        print(f"Error: {error}")
74
    else:
75
        print(f"{error.filename}:{error.line}:{error.column} [{error.prefix}{error.code}]: {error.msg}")
76
```
77

78
## Architecture
79

80
Refurb uses a multi-phase architecture built on Mypy's AST and type analysis:
81

82
- **Settings System**: Handles CLI parsing and configuration file loading
83
- **Check Loader**: Discovers and loads built-in and plugin checks 
84
- **Mypy Integration**: Leverages Mypy's type checker for AST parsing and type information
85
- **Visitor Pattern**: Traverses AST nodes to run applicable checks
86
- **Error System**: Collects, filters, and formats analysis results
87

88
The tool includes 94 built-in checks organized into 20+ categories, covering everything from basic readability improvements to advanced standard library usage patterns. A comprehensive plugin system allows custom checks to be easily integrated.
89

90
## Capabilities
91

92
### Command Line Interface
93

94
Primary interface for code analysis with comprehensive options for configuration, error filtering, output formatting, and integration with development workflows.
95

96
```python { .api }
97
def main(args: list[str]) -> int:
98
    """
99
    Main CLI entry point.
100
    
101
    Parameters:
102
    - args: Command line arguments
103
    
104
    Returns:
105
    Exit code (0 for success, 1 for errors)
106
    """
107

108
def usage() -> None:
109
    """Display comprehensive help information."""
110

111
def version() -> str:
112
    """Get version information for refurb and mypy."""
113
```
114

115
[Command Line Interface](./cli.md)
116

117
### Core Analysis Engine
118

119
The heart of refurb's code analysis, managing the integration with Mypy, check execution, and error collection.
120

121
```python { .api }
122
def run_refurb(settings: Settings) -> Sequence[Error | str]:
123
    """
124
    Execute refurb analysis on specified files.
125
    
126
    Parameters:
127
    - settings: Configuration object containing all analysis options
128
    
129
    Returns:
130
    Sequence of Error objects or error strings
131
    """
132
```
133

134
[Core Analysis](./analysis.md)
135

136
### Error System
137

138
Comprehensive error handling including error definitions, classification, filtering, and formatting for various output targets.
139

140
```python { .api }
141
class Error:
142
    """Base error class for all refurb findings."""
143
    line: int
144
    column: int
145
    msg: str
146
    filename: str | None
147
    line_end: int | None
148
    column_end: int | None
149

150
class ErrorCode:
151
    """Error code identifier."""
152
    id: int
153
    prefix: str
154
    path: str | None
155

156
class ErrorCategory:
157
    """Error category for grouping related checks."""
158
    value: str
159
    path: str | None
160
```
161

162
[Error System](./errors.md)
163

164
### Settings and Configuration
165

166
Powerful configuration system supporting CLI arguments, TOML configuration files, and path-specific amendment rules.
167

168
```python { .api }
169
class Settings:
170
    """Main configuration class containing all analysis options."""
171
    files: list[str]
172
    ignore: set[ErrorClassifier]
173
    enable: set[ErrorClassifier]
174
    disable: set[ErrorClassifier]
175
    load: list[str]
176
    # ... extensive configuration options
177

178
def load_settings(args: list[str]) -> Settings:
179
    """Parse CLI args and config files into Settings object."""
180
```
181

182
[Configuration](./configuration.md)
183

184
### Plugin Development Framework
185

186
Complete framework for developing custom checks with AST analysis utilities, type checking helpers, and visitor patterns.
187

188
```python { .api }
189
class RefurbVisitor:
190
    """Main visitor for running checks on AST nodes."""
191
    def __init__(self, checks: defaultdict[type[Node], list[Check]], settings: Settings): ...
192
    def run_check(self, node: Node, check: Check) -> None: ...
193

194
def load_checks(settings: Settings) -> defaultdict[type[Node], list[Check]]:
195
    """Load and filter checks based on settings."""
196
```
197

198
[Plugin Development](./plugins.md)
199

200
### AST Analysis Utilities
201

202
Comprehensive utilities for AST node analysis, type checking, and code pattern matching used by built-in checks and available for custom checks.
203

204
```python { .api }
205
def is_equivalent(lhs: Node | None, rhs: Node | None) -> bool:
206
    """Compare AST nodes for equivalence."""
207

208
def stringify(node: Node) -> str:
209
    """Convert AST node to string representation."""
210

211
def get_mypy_type(node: Node) -> Type | SymbolNode | None:
212
    """Get Mypy type information for AST node."""
213

214
def is_same_type(ty: Type | SymbolNode | None, *expected: TypeLike) -> bool:
215
    """Check if type matches any of the expected types."""
216
```
217

218
[AST Utilities](./ast-utilities.md)
219

220
## Built-in Check Categories
221

222
Refurb includes 94 comprehensive checks organized into focused categories:
223

224
- **builtin** (21 checks): Core Python builtin improvements
225
- **readability** (22 checks): Code readability and clarity
226
- **pathlib** (15 checks): Modern path manipulation 
227
- **string** (7 checks): String operation optimizations
228
- **flow** (4 checks): Control flow improvements
229
- **logical** (3 checks): Logical expression simplification
230
- **itertools** (2 checks), **math** (2 checks), **regex** (2 checks): Standard library optimizations
231
- **datetime** (2 checks), **hashlib** (2 checks): Specialized improvements
232
- Plus additional categories for collections, contextlib, decimal, function, functools, iterable, pattern matching, secrets, shlex, and third-party FastAPI support
233

234
## Types
235

236
```python { .api }
237
from typing import Callable, Sequence
238
from collections import defaultdict
239
from mypy.nodes import Node
240

241
# Type aliases for check system
242
Check = Callable[[Node, list[Error]], None] | Callable[[Node, list[Error], Settings], None]
243
Checks = defaultdict[type[Node], list[Check]]
244
ErrorClassifier = ErrorCategory | ErrorCode
245
```