0
# Prospector
1

2
Prospector is a comprehensive Python code analysis tool that aggregates results from multiple static analysis tools including Pylint, pycodestyle, pyflakes, mccabe complexity checker, pydocstyle, and others into a unified report. It provides intelligent defaults and profiles that adapt to different coding styles and frameworks, automatically detecting project dependencies to configure appropriate analysis rules.
3

4
## Package Information
5

6
- **Package Name**: prospector
7
- **Language**: Python  
8
- **Installation**: `pip install prospector`
9
- **Optional Dependencies**: `prospector[with_bandit]`, `prospector[with_mypy]`, `prospector[with_pyright]`, `prospector[with_pyroma]`, `prospector[with_ruff]`, `prospector[with_vulture]`, `prospector[with_everything]`
10

11
## Core Imports
12

13
```python
14
from prospector.run import Prospector, main
15
from prospector.config import ProspectorConfig
16
from prospector.message import Message, Location
17
from prospector.finder import FileFinder
18
```
19

20
For accessing tools and formatters:
21

22
```python
23
from prospector import tools
24
from prospector.formatters import FORMATTERS
25
from prospector.tools.base import ToolBase
26
```
27

28
## Basic Usage
29

30
### Command Line Usage
31

32
```bash
33
# Analyze current directory
34
prospector
35

36
# Analyze specific path
37
prospector path/to/code
38

39
# Use specific tools
40
prospector --tool pylint --tool pyflakes
41

42
# Use specific profile
43
prospector --profile my_profile
44

45
# Output as JSON
46
prospector --output-format json
47
```
48

49
### Programmatic Usage
50

51
```python
52
from prospector.config import ProspectorConfig
53
from prospector.run import Prospector
54

55
# Create configuration
56
config = ProspectorConfig()
57

58
# Run analysis
59
prospector = Prospector(config)
60
prospector.execute()
61

62
# Get results
63
messages = prospector.get_messages()
64
summary = prospector.get_summary()
65

66
# Print results
67
prospector.print_messages()
68
```
69

70
## Architecture
71

72
Prospector follows a plugin-based architecture with several key components:
73

74
- **Prospector**: Main orchestrator that coordinates tool execution and message processing
75
- **ProspectorConfig**: Configuration management system that handles command-line arguments, profiles, and tool settings
76
- **Tools**: Plugin system where each static analysis tool (pylint, pyflakes, etc.) implements the ToolBase interface
77
- **Messages**: Standardized representation of analysis results with Location information  
78
- **Formatters**: Output formatting system supporting multiple formats (JSON, text, XML, etc.)
79
- **Profiles**: Configuration profiles that define tool settings and enable/disable rules
80
- **FileFinder**: File discovery system that identifies Python modules and packages to analyze
81

82
This modular design allows Prospector to integrate diverse analysis tools while providing a consistent interface and unified output format.
83

84
## Capabilities
85

86
### Main Analysis Runner
87

88
Core functionality for running code analysis with the main Prospector class. This handles tool orchestration, configuration management, and result aggregation.
89

90
```python { .api }
91
class Prospector:
92
    def __init__(self, config: ProspectorConfig) -> None: ...
93
    def execute(self) -> None: ...
94
    def get_messages(self) -> list[Message]: ...
95
    def get_summary(self) -> Optional[dict[str, Any]]: ...
96
    def print_messages(self) -> None: ...
97

98
def main() -> None: ...
99
```
100

101
[Analysis Runner](./analysis-runner.md)
102

103
### Configuration Management
104

105
Comprehensive configuration system that handles command-line arguments, profiles, tool settings, and environment detection.
106

107
```python { .api }
108
class ProspectorConfig:
109
    def __init__(self, workdir: Optional[Path] = None): ...
110
    def get_tools(self, found_files: FileFinder) -> list[tools.ToolBase]: ...
111
    def make_exclusion_filter(self) -> Callable[[Path], bool]: ...
112
    def get_output_report(self) -> list[tuple[str, list[str]]]: ...
113
```
114

115
[Configuration](./configuration.md)
116

117
### Message and Location System
118

119
Standardized data structures for representing analysis results and source code locations.
120

121
```python { .api }
122
class Message:
123
    def __init__(self, source: str, code: str, location: Location, message: str, 
124
                 doc_url: Optional[str] = None, is_fixable: bool = False): ...
125

126
class Location:
127
    def __init__(self, path: Optional[Union[Path, str]], module: Optional[str], 
128
                 function: Optional[str], line: Optional[int], character: Optional[int],
129
                 line_end: Optional[int] = None, character_end: Optional[int] = None): ...
130
```
131

132
[Messages](./messages.md)
133

134
### File Discovery
135

136
File and module discovery system that identifies Python code to be analyzed.
137

138
```python { .api }
139
class FileFinder:
140
    def __init__(self, *provided_paths: Path, 
141
                 exclusion_filters: Optional[Iterable[Callable[[Path], bool]]] = None): ...
142
    @property
143
    def python_modules(self) -> list[Path]: ...
144
    @property  
145
    def python_packages(self) -> list[Path]: ...
146
    @property
147
    def files(self) -> set[Path]: ...
148
    def make_syspath(self) -> list[Path]: ...
149
```
150

151
[File Finding](./file-finding.md)
152

153
### Tool Framework
154

155
Plugin system for integrating static analysis tools with base classes and tool registry.
156

157
```python { .api }
158
class ToolBase(ABC):
159
    @abstractmethod
160
    def configure(self, prospector_config: "ProspectorConfig", found_files: FileFinder) -> Optional[tuple]: ...
161
    @abstractmethod  
162
    def run(self, found_files: FileFinder) -> list[Message]: ...
163

164
TOOLS: dict[str, type[ToolBase]]
165
DEFAULT_TOOLS: tuple[str, ...]
166
```
167

168
[Tools](./tools.md)
169

170
### Output Formatters
171

172
Output formatting system supporting multiple formats including JSON, text, XML, and IDE integrations.
173

174
```python { .api }
175
class Formatter(ABC):
176
    @abstractmethod
177
    def render(self, summary: bool = True, messages: bool = True, profile: bool = False) -> str: ...
178

179
FORMATTERS: dict[str, type[Formatter]]
180
```
181

182
[Formatters](./formatters.md)
183

184
### Profile Management
185

186
Configuration profile system for managing tool settings, rules, and project-specific configurations.
187

188
```python { .api }
189
class ProspectorProfile:
190
    @staticmethod
191
    def load(name: Union[str, Path], profile_path: list[Path], 
192
             forced_inherits: Optional[list[str]] = None) -> ProspectorProfile: ...
193
    def is_tool_enabled(self, tool_name: str) -> Optional[bool]: ...
194
```
195

196
[Profiles](./profiles.md)
197

198
### Exceptions
199

200
Custom exception classes for error handling and diagnostics.
201

202
```python { .api }
203
class FatalProspectorException(Exception):
204
    def __init__(self, message: str): ...
205

206
class CouldNotHandleEncoding(Exception):
207
    def __init__(self, path: Path): ...
208

209
class PermissionMissing(Exception):
210
    def __init__(self, path: Path): ...
211
```
212

213
[Exceptions](./exceptions.md)