0
# Configuration Management
1

2
Comprehensive configuration system supporting multiple file formats with validation, environment variable overrides, and automatic discovery. Provides both high-level configuration management and low-level configuration file operations.
3

4
## Capabilities
5

6
### Configuration Loading
7

8
Primary functions for loading and managing bump-my-version configuration from various sources.
9

10
```python { .api }
11
def get_configuration(
12
    config_file: Optional[str] = None,
13
    **overrides: Any
14
) -> Config:
15
    """
16
    Load configuration from files and apply overrides.
17
    
18
    Discovers configuration files automatically or uses specified file,
19
    validates settings, and applies environment variable and keyword overrides.
20
    
21
    Args:
22
        config_file: Specific configuration file path (optional)
23
        **overrides: Configuration values to override
24
        
25
    Returns:
26
        Validated Config object with all settings
27
        
28
    Raises:
29
        ConfigurationError: Invalid configuration or file not found
30
    """
31

32
def set_config_defaults(
33
    parsed_config: Dict[str, Any],
34
    **overrides: Any
35
) -> Dict[str, Any]:
36
    """
37
    Apply default values and overrides to parsed configuration.
38
    
39
    Args:
40
        parsed_config: Raw configuration dictionary
41
        **overrides: Values to override
42
        
43
    Returns:
44
        Configuration dictionary with defaults applied
45
    """
46

47
def check_current_version(config: Config) -> str:
48
    """
49
    Validate and return current version from configuration.
50
    
51
    Args:
52
        config: Configuration object
53
        
54
    Returns:
55
        Current version string
56
        
57
    Raises:
58
        ConfigurationError: Current version not found or invalid
59
    """
60
```
61

62
### Configuration Model
63

64
Main configuration class with comprehensive validation and settings management.
65

66
```python { .api }
67
class Config(BaseSettings):
68
    """
69
    Main configuration class with Pydantic validation.
70
    
71
    Contains all bump-my-version settings with automatic validation,
72
    environment variable support, and default value management.
73
    """
74
    
75
    # Version settings
76
    current_version: str
77
    parse: str = r"(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)"
78
    serialize: List[str] = ["{major}.{minor}.{patch}"]
79
    search: str = "{current_version}"
80
    replace: str = "{new_version}"
81
    regex: bool = False
82
    ignore_missing_version: bool = False
83
    
84
    # File settings
85
    files: List[FileChange] = []
86
    
87
    # SCM settings
88
    commit: bool = False
89
    tag: bool = False
90
    sign_tags: bool = False
91
    tag_name: str = "v{new_version}"
92
    tag_message: str = "Bump version: {current_version} → {new_version}"  
93
    allow_dirty: bool = False
94
    message: str = "Bump version: {current_version} → {new_version}"
95
    commit_args: str = ""
96
    
97
    # Hook settings
98
    setup_hooks: List[str] = []
99
    pre_commit_hooks: List[str] = []
100
    post_commit_hooks: List[str] = []
101
    
102
    # Version component settings
103
    parts: Dict[str, VersionComponentSpec] = {}
104
    
105
    @property
106
    def version_config(self) -> VersionConfig:
107
        """Get VersionConfig object for version operations."""
108
    
109
    @property
110
    def scm_info(self) -> Optional[SCMInfo]:
111
        """Get SCM information for current repository."""
112

113
class FileChange(BaseModel):
114
    """
115
    Configuration for file modification operations.
116
    
117
    Defines how version strings should be found and replaced
118
    in specific files with customizable patterns and options.
119
    """
120
    
121
    filename: str
122
    glob: Optional[str] = None
123
    key_path: Optional[str] = None
124
    search: Optional[str] = None
125
    replace: Optional[str] = None
126
    regex: bool = False
127
    ignore_missing_version: bool = False
128
    ignore_missing_file: bool = False
129

130
class VersionComponentSpec(BaseModel):
131
    """
132
    Specification for version component behavior.
133
    
134
    Defines how individual version components should increment,
135
    their valid values, and special behaviors like calendar versioning.
136
    """
137
    
138
    type: str = "numeric"
139
    values: Optional[List[str]] = None
140
    optional_value: Optional[str] = None
141
    first_value: Optional[str] = None
142
    independent: bool = False
143
    always_increment: bool = False
144
    calver_format: Optional[str] = None
145

146
class GlobalDefaults(BaseModel):
147
    """Default configuration values."""
148
    
149
    current_version: str = "0.1.0"
150
    parse: str = r"(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)"
151
    serialize: List[str] = ["{major}.{minor}.{patch}"]
152
    search: str = "{current_version}"
153
    replace: str = "{new_version}"
154
```
155

156
### File Discovery and Reading
157

158
Functions for locating and reading configuration files from various sources.
159

160
```python { .api }
161
def find_config_file(explicit_file: Optional[str] = None) -> Optional[Path]:
162
    """
163
    Locate configuration file using standard search order.
164
    
165
    Searches for configuration files in the following order:
166
    1. Explicit file parameter
167
    2. pyproject.toml (with [tool.bumpversion] section)
168
    3. .bumpversion.toml
169
    4. .bumpversion.cfg (legacy)
170
    5. setup.cfg (legacy, with [bumpversion] section)
171
    
172
    Args:
173
        explicit_file: Specific file path to use
174
        
175
    Returns:
176
        Path to configuration file or None if not found
177
    """
178

179
def read_config_file(config_file: Optional[str] = None) -> Dict[str, Any]:
180
    """
181
    Read and parse configuration from file.
182
    
183
    Supports TOML and INI format files with automatic format detection
184
    and legacy configuration migration.
185
    
186
    Args:
187
        config_file: Configuration file path
188
        
189
    Returns:
190
        Dictionary of configuration values
191
        
192
    Raises:
193
        ConfigurationError: File not found or invalid format
194
    """
195

196
def read_toml_file(file_path: Path) -> Dict[str, Any]:
197
    """
198
    Read TOML configuration file.
199
    
200
    Args:
201
        file_path: Path to TOML file
202
        
203
    Returns:
204
        Configuration dictionary from TOML file
205
    """
206

207
def update_config_file(
208
    config_file: Path,
209
    current_version: str,
210
    new_version: str,
211
    is_new_version: bool
212
) -> None:
213
    """
214
    Update configuration file with new version.
215
    
216
    Args:
217
        config_file: Path to configuration file
218
        current_version: Current version string
219
        new_version: New version string
220
        is_new_version: Whether this is a new version
221
    """
222
```
223

224
### PEP 621 Support
225

226
Support for modern Python project metadata and version management.
227

228
```python { .api }
229
def get_pep621_info(config_file: Optional[str] = None) -> Optional[PEP621Info]:
230
    """
231
    Extract PEP 621 project metadata from pyproject.toml.
232
    
233
    Reads project version and metadata according to PEP 621 specification
234
    for modern Python project configuration.
235
    
236
    Args:
237
        config_file: Path to pyproject.toml file
238
        
239
    Returns:
240
        PEP621Info object with project metadata or None
241
    """
242

243
class PEP621Info:
244
    """
245
    Container for PEP 621 project metadata.
246
    
247
    Holds version information and project details from pyproject.toml
248
    according to Python packaging standards.
249
    """
250
    
251
    project_name: str
252
    version: Optional[str] = None
253
    dynamic_version: bool = False
254
    version_file: Optional[str] = None
255
    
256
    @property
257
    def has_version(self) -> bool:
258
        """Whether project has version information."""
259
    
260
    @property
261
    def is_dynamic_version(self) -> bool:
262
        """Whether version is marked as dynamic."""
263
```
264

265
### Configuration Creation
266

267
Interactive and automated configuration file generation.
268

269
```python { .api }
270
def create_configuration(destination: str, prompt: bool) -> TOMLDocument:
271
    """
272
    Create new configuration file interactively or with defaults.
273
    
274
    Generates bump-my-version configuration through interactive prompts
275
    or using default values for automated setup.
276
    
277
    Args:
278
        destination: Output file path
279
        prompt: Whether to use interactive prompts
280
        
281
    Returns:
282
        TOMLDocument with generated configuration
283
    """
284

285
def get_defaults_from_dest(destination: str) -> Tuple[Dict, TOMLDocument]:
286
    """
287
    Generate default configuration based on destination file.
288
    
289
    Args:
290
        destination: Target configuration file path
291
        
292
    Returns:
293
        Tuple of (defaults dictionary, TOML document)
294
    """
295
```
296

297
## Configuration File Formats 
298

299
### TOML Format (Recommended)
300

301
Modern TOML-based configuration in `pyproject.toml` or `.bumpversion.toml`:
302

303
```toml
304
[tool.bumpversion]
305
current_version = "1.0.0"
306
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
307
serialize = ["{major}.{minor}.{patch}"]
308
search = "{current_version}"
309
replace = "{new_version}"
310
regex = false
311
ignore_missing_version = false
312
tag = true
313
commit = true
314
message = "Bump version: {current_version} → {new_version}"
315

316
[[tool.bumpversion.files]]
317
filename = "setup.py"
318
search = "version='{current_version}'"
319
replace = "version='{new_version}'"
320

321
[[tool.bumpversion.files]]  
322
filename = "src/mypackage/__init__.py"
323

324
[tool.bumpversion.parts.dev]
325
values = ["release", "dev"]
326
```
327

328
### Legacy INI Format
329

330
Legacy configuration in `.bumpversion.cfg` or `setup.cfg`:
331

332
```ini
333
[bumpversion]
334
current_version = 1.0.0
335
commit = True
336
tag = True
337

338
[bumpversion:file:setup.py]
339
search = version='{current_version}'
340
replace = version='{new_version}'
341

342
[bumpversion:part:dev]
343
values = release,dev
344
```
345

346
## Environment Variables
347

348
Configuration values can be overridden using environment variables with `BMP_` prefix:
349

350
```bash
351
export BMP_CURRENT_VERSION="1.0.0"
352
export BMP_COMMIT="true"
353
export BMP_TAG="true"
354
export BMP_TAG_NAME="v{new_version}"
355
export BMP_MESSAGE="Release {new_version}"
356
```
357

358
## Usage Examples
359

360
### Basic Configuration Loading
361

362
```python
363
from bumpversion.config import get_configuration
364

365
# Load configuration automatically
366
config = get_configuration()
367

368
# Load specific configuration file
369
config = get_configuration(config_file="pyproject.toml")
370

371
# Load with overrides
372
config = get_configuration(
373
    current_version="2.0.0",
374
    commit=True,
375
    tag=True
376
)
377

378
print(f"Current version: {config.current_version}")
379
print(f"Will commit: {config.commit}")
380
print(f"Files to update: {len(config.files)}")
381
```
382

383
### Configuration Discovery
384

385
```python
386
from bumpversion.config.files import find_config_file, read_config_file
387

388
# Find configuration file
389
config_path = find_config_file()
390
if config_path:
391
    print(f"Found configuration: {config_path}")
392
    
393
    # Read configuration
394
    config_data = read_config_file(str(config_path))
395
    print(f"Current version: {config_data.get('current_version')}")
396
```
397

398
### Creating New Configuration
399

400
```python
401
from bumpversion.config.create import create_configuration
402

403
# Create configuration interactively
404
toml_doc = create_configuration(
405
    destination="pyproject.toml",
406
    prompt=True
407
)
408

409
# Create with defaults
410
toml_doc = create_configuration(
411
    destination=".bumpversion.toml", 
412
    prompt=False
413
)
414
```
415

416
### PEP 621 Integration
417

418
```python
419
from bumpversion.config.files import get_pep621_info
420

421
# Get PEP 621 project information
422
pep621_info = get_pep621_info("pyproject.toml")
423
if pep621_info and pep621_info.has_version:
424
    print(f"Project: {pep621_info.project_name}")
425
    print(f"Version: {pep621_info.version}")
426
    print(f"Dynamic version: {pep621_info.is_dynamic_version}")
427
```