0
# Pylama
1

2
Pylama is a comprehensive Python code audit and quality assurance tool that aggregates multiple popular linters and checkers into a single unified interface. It provides extensive configuration options, multiple output formats, and seamless integration into development workflows including CI/CD pipelines, pytest testing, and version control hooks.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import pylama
14
```
15

16
For programmatic usage:
17

18
```python
19
from pylama.main import check_paths, shell
20
from pylama.core import run
21
from pylama.config import parse_options
22
from pylama.errors import Error
23
```
24

25
For plugin development:
26

27
```python
28
from pylama.lint import LinterV2
29
from pylama.context import RunContext
30
```
31

32
## Basic Usage
33

34
### Command Line Usage
35

36
```python
37
# Check current directory
38
import subprocess
39
subprocess.run(['pylama', '.'])
40

41
# Check specific files with custom options
42
subprocess.run(['pylama', '--linters=pycodestyle,pyflakes', 'myfile.py'])
43

44
# Generate JSON output
45
subprocess.run(['pylama', '--format=json', '.'])
46
```
47

48
### Programmatic Usage
49

50
```python
51
from pylama.main import check_paths
52
from pylama.config import parse_options
53

54
# Parse options and check files
55
options = parse_options(['--linters=pycodestyle,pyflakes', 'myfile.py'])
56
errors = check_paths(['myfile.py'], options)
57

58
# Process errors
59
for error in errors:
60
    print(f"{error.filename}:{error.lnum} - {error.message}")
61
```
62

63
### Pytest Integration
64

65
```python
66
# pytest automatically discovers the pylama plugin
67
# Run tests with pylama checking
68
import subprocess
69
subprocess.run(['pytest', '--pylama'])
70
```
71

72
## Architecture
73

74
Pylama follows a plugin-based architecture that enables extensibility and modularity:
75

76
- **Core Engine**: Manages file processing, error collection, and result formatting
77
- **Configuration System**: Handles multiple config file formats and command-line options
78
- **Plugin Framework**: Standardized interface for integrating diverse linters and checkers
79
- **Context Management**: Provides execution context with resource management and error tracking
80
- **Error Processing**: Deduplicates errors across linters and provides flexible output formatting
81

82
This design allows pylama to serve as a unified front-end for the Python quality assurance ecosystem, supporting both built-in linters (pycodestyle, pyflakes, mccabe, pydocstyle, pylint, mypy, radon, eradicate, vulture) and custom plugin development.
83

84
## Capabilities
85

86
### Main Interface Functions
87

88
Core functions for running code analysis programmatically and via command line interface.
89

90
```python { .api }
91
def shell(args: List[str] = None, error: bool = True):
92
    """Main console entry point for pylama command."""
93

94
def check_paths(
95
    paths: Optional[List[str]],
96
    options: Namespace,
97
    code: str = None,
98
    rootdir: Path = None,
99
) -> List[Error]:
100
    """Check multiple file paths for code quality issues."""
101

102
def run(
103
    path: str,
104
    code: str = None,
105
    rootdir: Path = CURDIR,
106
    options: Namespace = None
107
) -> List[Error]:
108
    """Run code checkers on a single file."""
109
```
110

111
[Main Interface](./main-interface.md)
112

113
### Configuration Management
114

115
Comprehensive configuration system supporting multiple file formats and extensive customization options.
116

117
```python { .api }
118
def parse_options(
119
    args: List[str] = None,
120
    config: bool = True,
121
    rootdir: Path = CURDIR,
122
    **overrides
123
) -> Namespace:
124
    """Parse command line arguments and configuration files."""
125

126
def get_config(user_path: str = None, rootdir: Path = None) -> inirama.Namespace:
127
    """Load configuration from available config files."""
128

129
def setup_parser() -> ArgumentParser:
130
    """Create argument parser with all command line options."""
131

132
def setup_logger(options: Namespace):
133
    """Setup logging based on options."""
134
```
135

136
[Configuration](./configuration.md)
137

138
### Error Handling and Processing
139

140
Error representation, deduplication, and formatting capabilities.
141

142
```python { .api }
143
class Error:
144
    """Represents a single linting error."""
145
    def __init__(
146
        self,
147
        source: str = "pylama",
148
        col: int = 1,
149
        lnum: int = 1,
150
        type: str = None,
151
        text: str = "unknown error",
152
        filename: str = "",
153
        number: str = ""
154
    ): ...
155

156
def remove_duplicates(errors: List[Error]) -> Generator[Error, None, None]:
157
    """Remove duplicate errors from different linters."""
158

159
def display_errors(errors: List[Error], options: Namespace):
160
    """Format and display errors using specified format."""
161
```
162

163
[Error Processing](./error-processing.md)
164

165
### Plugin Development Framework
166

167
Framework for creating custom linters and extending pylama functionality.
168

169
```python { .api }
170
class LinterV2(Linter):
171
    """Base class for modern linter plugins."""
172
    name: Optional[str] = None
173
    
174
    def run_check(self, ctx: RunContext):
175
        """Check code using RunContext."""
176

177
class RunContext:
178
    """Execution context for linter operations."""
179
    def __init__(self, filename: str, source: str = None, options: Namespace = None): ...
180
    def get_params(self, lname: str) -> dict: ...
181
    def push(self, source: str, **err_info): ...
182
```
183

184
[Plugin Development](./plugin-development.md)
185

186
### Pytest Integration
187

188
Seamless integration with pytest for automated code quality checking during testing.
189

190
```python { .api }
191
def pytest_addoption(parser):
192
    """Add --pylama option to pytest."""
193

194
def pytest_collect_file(path, parent):
195
    """Collect Python files for pylama checking."""
196

197
class PylamaError(Exception):
198
    """Exception raised when pylama checks fail."""
199

200
class PylamaItem(pytest.Item):
201
    """Pytest test item for pylama checks."""
202
```
203

204
[Pytest Integration](./pytest-integration.md)
205

206
### Asynchronous Processing
207

208
High-performance parallel processing capabilities for large codebases.
209

210
```python { .api }
211
def check_async(
212
    paths: List[str],
213
    code: str = None,
214
    options: Namespace = None,
215
    rootdir: Path = None
216
) -> List[Error]:
217
    """Check files asynchronously using process pool."""
218
```
219

220
[Async Processing](./async-processing.md)
221

222
### Version Control Hooks
223

224
Pre-commit and post-commit hooks for Git and Mercurial integration.
225

226
```python { .api }
227
def git_hook(error: bool = True):
228
    """Git pre-commit hook implementation."""
229

230
def hg_hook(_, repo, node=None, **kwargs):
231
    """Mercurial commit hook implementation."""
232

233
def install_hook(path: str):
234
    """Auto-detect VCS and install appropriate hook."""
235
```
236

237
[VCS Hooks](./vcs-hooks.md)
238

239
## Types
240

241
```python { .api }
242
from argparse import Namespace
243
from pathlib import Path
244
from typing import Generator, Any, List, Optional, Dict, Set, Tuple
245

246
class Error:
247
    """Linting error representation."""
248
    filename: str
249
    lnum: int
250
    col: int
251
    message: str  # Error message text
252
    etype: str
253
    source: str
254
    number: str
255
    
256
    def to_dict(self) -> Dict[str, Any]: ...
257
    def format(self, template: str) -> str: ...
258

259
class RunContext:
260
    """Execution context for linter operations."""
261
    errors: List[Error]
262
    options: Optional[Namespace]
263
    skip: bool
264
    ignore: Set[str]
265
    select: Set[str]
266
    linters: List[str]
267
    filename: str
268
    
269
    def get_params(self, lname: str) -> Dict[str, Any]: ...
270
    def push(self, source: str, **err_info): ...
271

272
class LinterV2:
273
    """Modern linter base class."""
274
    name: Optional[str]
275
    
276
    def run_check(self, ctx: RunContext): ...
277

278
# Configuration constants
279
DEFAULT_LINTERS: Tuple[str, str, str]  # ("pycodestyle", "pyflakes", "mccabe")
280
CONFIG_FILES: List[str]  # Supported config file names
281
DEFAULT_FORMAT: str  # Default error message format
282
MESSAGE_FORMATS: Dict[str, str]  # Available message formats
283
```