0
# Configuration Management
1

2
Comprehensive configuration system supporting multiple file formats, command-line options, and extensive customization for all aspects of code checking. Pylama provides flexible configuration through INI files, TOML files, and command-line arguments with hierarchical precedence.
3

4
## Capabilities
5

6
### Option Parsing
7

8
Parse and merge configuration from multiple sources with proper precedence handling.
9

10
```python { .api }
11
def parse_options(
12
    args: List[str] = None,
13
    config: bool = True,
14
    rootdir: Path = CURDIR,
15
    **overrides
16
) -> Namespace:
17
    """
18
    Parse command line arguments and configuration files.
19
    
20
    Args:
21
        args: Command line arguments. If None, uses sys.argv[1:]
22
        config: Whether to load configuration files. If False, only uses command line args
23
        rootdir: Root directory for config file search and path resolution
24
        **overrides: Override specific configuration values
25
        
26
    Returns:
27
        Namespace: Parsed configuration with all options set
28
        
29
    Configuration precedence (highest to lowest):
30
    1. Command line arguments
31
    2. Specified config file or auto-discovered config
32
    3. Home directory config (~/.pylama.ini)
33
    4. Default values
34
    
35
    Supported config files: pylama.ini, pyproject.toml, setup.cfg, tox.ini, pytest.ini
36
    """
37
```
38

39
### Configuration Loading
40

41
Load configuration from various file formats with format-specific parsing.
42

43
```python { .api }
44
def get_config(user_path: str = None, rootdir: Path = None) -> inirama.Namespace:
45
    """
46
    Load configuration from available config files.
47
    
48
    Args:
49
        user_path: Specific config file path
50
        rootdir: Directory to search for config files
51
        
52
    Returns:
53
        inirama.Namespace: Parsed configuration sections
54
        
55
    Searches for config files in order of precedence:
56
    - User-specified path
57
    - pylama.ini, pyproject.toml, setup.cfg, tox.ini, pytest.ini in rootdir
58
    - ~/.pylama.ini in home directory
59
    """
60

61
def get_config_ini(ini_path: str) -> inirama.Namespace:
62
    """
63
    Load INI-format configuration file.
64
    
65
    Args:
66
        ini_path: Path to INI configuration file
67
        
68
    Returns:
69
        inirama.Namespace: Parsed INI configuration
70
    """
71

72
def get_config_toml(toml_path: str) -> inirama.Namespace:
73
    """
74
    Load TOML-format configuration file.
75
    
76
    Args:
77
        toml_path: Path to TOML configuration file
78
        
79
    Returns:
80
        inirama.Namespace: Parsed TOML configuration
81
        
82
    Requires 'toml' package for TOML parsing.
83
    Configuration should be under [tool.pylama] section.
84
    """
85
```
86

87
### Argument Parser Setup
88

89
Create command-line argument parser with all available options.
90

91
```python { .api }
92
def setup_parser() -> ArgumentParser:
93
    """
94
    Create argument parser with all command line options.
95
    
96
    Returns:
97
        ArgumentParser: Configured parser with all pylama options
98
        
99
    Includes options for:
100
    - Linter selection and configuration
101
    - File filtering and path handling
102
    - Output formatting and verbosity
103
    - Performance and concurrency settings
104
    - Integration features (hooks, pytest)
105
    """
106
```
107

108
### Configuration Discovery
109

110
Find default configuration files in standard locations.
111

112
```python { .api }
113
def get_default_config_file(rootdir: Path = None) -> Optional[str]:
114
    """
115
    Find default configuration file in standard locations.
116
    
117
    Args:
118
        rootdir: Directory to search for config files
119
        
120
    Returns:
121
        Optional[str]: Path to found config file or None
122
        
123
    Search order:
124
    1. pylama.ini
125
    2. pyproject.toml  
126
    3. setup.cfg
127
    4. tox.ini
128
    5. pytest.ini
129
    """
130
```
131

132
### Utility Functions
133

134
Helper functions for configuration processing and validation.
135

136
```python { .api }
137
def parse_linters(linters: str) -> List[str]:
138
    """
139
    Parse linter specification string into list.
140
    
141
    Args:
142
        linters: Comma-separated linter names
143
        
144
    Returns:
145
        List[str]: List of linter names
146
    """
147

148
def split_csp_str(val: Union[str, Collection[str]]) -> Set[str]:
149
    """
150
    Split comma-separated string into unique values.
151
    
152
    Args:
153
        val: String or collection to split
154
        
155
    Returns:
156
        Set[str]: Set of unique values
157
    """
158

159
def prepare_sorter(val: Union[str, Collection[str]]) -> Optional[Dict[str, int]]:
160
    """
161
    Prepare error sorting function from configuration.
162
    
163
    Args:
164
        val: Sort specification string or collection
165
        
166
    Returns:
167
        Optional[Dict[str, int]]: Sorting configuration or None for default
168
    """
169

170
def setup_logger(options: Namespace):
171
    """
172
    Configure logging based on options.
173
    
174
    Args:
175
        options: Configuration options with verbosity settings
176
        
177
    Sets up console logging with appropriate level based on:
178
    - options.verbose: Detailed output
179
    - options.quiet: Minimal output
180
    """
181

182
def fix_pathname_sep(val: str) -> str:
183
    """
184
    Fix pathname separators for cross-platform compatibility.
185
    
186
    Args:
187
        val: Path string with potentially wrong separators
188
        
189
    Returns:
190
        str: Path with correct separators for current platform
191
    """
192
```
193

194
## Configuration Options
195

196
### Core Options
197

198
```python
199
# Linter configuration
200
linters: List[str] = ["pycodestyle", "pyflakes", "mccabe"]  # Active linters
201
ignore: Set[str] = set()  # Error codes to ignore
202
select: Set[str] = set()  # Error codes to select (if specified, ignore others)
203
skip: List[str] = []  # File patterns to skip
204

205
# File handling
206
paths: List[str] = ["."]  # Paths to check
207
format: str = "default"  # Output format (default, json, pylint, pycodestyle)
208
sort: str = ""  # Sort order for errors
209

210
# Performance
211
async: bool = False  # Use asynchronous processing
212
concurrent: bool = False  # Enable concurrent processing
213

214
# Line length
215
max_line_length: int = 79  # Maximum line length
216

217
# Output control
218
verbose: int = 0  # Verbosity level (0-2)
219
quiet: bool = False  # Suppress output
220
```
221

222
### Linter-Specific Options
223

224
Each linter can have its own configuration section:
225

226
```ini
227
[pylama:pycodestyle]
228
max_line_length = 100
229
ignore = E501,W503
230

231
[pylama:pylint] 
232
ignore = R,C0111,W0613
233
disable = missing-docstring
234

235
[pylama:mypy]
236
ignore_missing_imports = True
237
```
238

239
## Usage Examples
240

241
### Basic Configuration
242

243
```python
244
from pylama.config import parse_options
245

246
# Use default configuration
247
options = parse_options([])
248
print(f"Default linters: {options.linters}")
249
print(f"Default format: {options.format}")
250
```
251

252
### Command Line Configuration
253

254
```python
255
from pylama.config import parse_options
256

257
# Parse specific command line options
258
args = [
259
    '--linters=pycodestyle,pyflakes,mccabe',
260
    '--ignore=E501,W503',
261
    '--format=json',
262
    '--max-line-length=100',
263
    '--async',
264
    'src/',
265
    'tests/'
266
]
267
options = parse_options(args)
268

269
print(f"Linters: {options.linters}")
270
print(f"Ignore: {options.ignore}")
271
print(f"Paths: {options.paths}")
272
```
273

274
### File-Based Configuration
275

276
```python
277
from pylama.config import get_config
278
from pathlib import Path
279

280
# Load from specific config file
281
config = get_config("/path/to/pylama.ini")
282

283
# Load from project directory
284
config = get_config(rootdir=Path("./myproject"))
285

286
# Access configuration sections
287
pylama_config = config.get("pylama", {})
288
pycodestyle_config = config.get("pylama:pycodestyle", {})
289
```
290

291
### Custom Configuration File
292

293
Example pylama.ini:
294

295
```ini
296
[pylama]
297
linters = pycodestyle,pyflakes,mccabe,pylint
298
ignore = D203,D213,E501
299
skip = migrations/*,venv/*
300
format = pylint
301
async = 1
302

303
[pylama:pycodestyle]
304
max_line_length = 120
305

306
[pylama:pylint]
307
ignore = C0111,R0903,W0613
308
```
309

310
Example pyproject.toml:
311

312
```toml
313
[tool.pylama]
314
linters = ["pycodestyle", "pyflakes", "mccabe"]
315
ignore = ["E501", "W503"]
316
skip = ["migrations/*", "build/*"]
317
format = "json"
318

319
[tool.pylama.linter.pycodestyle]
320
max_line_length = 100
321

322
[tool.pylama.linter.pylint]
323
disable = ["missing-docstring", "too-few-public-methods"]
324
```
325

326
## Constants
327

328
```python { .api }
329
DEFAULT_LINTERS: Tuple[str, str, str] = ("pycodestyle", "pyflakes", "mccabe")
330

331
CONFIG_FILES: List[str] = [
332
    "pylama.ini", 
333
    "pyproject.toml", 
334
    "setup.cfg", 
335
    "tox.ini", 
336
    "pytest.ini"
337
]
338

339
CURDIR: Path  # Current working directory
340
HOMECFG: Path  # Home directory config file path (~/.pylama.ini)
341
DEFAULT_SECTION: str = "pylama"  # Default configuration section name
342
```