0
# Configuration Management
1

2
Configuration loading, validation, and merging functionality for poetry-dynamic-versioning settings from pyproject.toml files. Handles complex configuration hierarchies with comprehensive validation and default value management.
3

4
## Capabilities
5

6
### Configuration Loading
7

8
Load configuration from pyproject.toml files with automatic path resolution and hierarchy traversal. Supports both local configuration objects and path-based loading with intelligent fallback to default values.
9

10
```python { .api }
11
def _get_config(local: Mapping) -> _Config:
12
    """
13
    Parse and merge configuration from a local configuration mapping.
14
    
15
    Parameters:
16
    - local: Raw configuration data from pyproject.toml
17
    
18
    Returns:
19
    _Config: Merged configuration with defaults and validation
20
    """
21

22
def _get_config_from_path(start: Optional[Path] = None) -> Mapping:
23
    """
24
    Load configuration starting from a given path, searching up the directory tree.
25
    
26
    Parameters:
27
    - start: Starting directory path (defaults to current working directory)
28
    
29
    Returns:
30
    Mapping: Configuration dictionary from found pyproject.toml or defaults
31
    """
32
```
33

34
### Configuration Validation
35

36
Comprehensive validation system that checks configuration structure, detects unknown keys, and validates nested configuration sections with detailed error reporting.
37

38
```python { .api }
39
def _validate_config(config: Optional[Mapping] = None) -> Sequence[str]:
40
    """
41
    Validate configuration structure and return error messages.
42
    
43
    Parameters:
44
    - config: Configuration to validate (auto-detects from pyproject.toml if None)
45
    
46
    Returns:
47
    Sequence[str]: List of validation error messages (empty if valid)
48
    """
49

50
def _validate_config_section(
51
    config: Mapping, 
52
    default: Mapping, 
53
    path: Sequence[str]
54
) -> Sequence[str]:
55
    """
56
    Validate a specific configuration section against its default structure.
57
    
58
    Parameters:
59
    - config: Configuration section to validate
60
    - default: Default/expected structure for comparison
61
    - path: Configuration path for error reporting
62
    
63
    Returns:
64
    Sequence[str]: List of validation errors for this section
65
    """
66
```
67

68
### Default Configuration
69

70
Provide complete default configuration structure with all supported options and their default values, forming the base for configuration merging operations.
71

72
```python { .api }
73
def _default_config() -> Mapping:
74
    """
75
    Get the complete default configuration structure.
76
    
77
    Returns:
78
    Mapping: Full default configuration with all options and default values
79
    """
80
```
81

82
### Configuration Merging
83

84
Deep merge configuration dictionaries with intelligent handling of nested structures, ensuring user configurations properly override defaults while preserving unspecified default values.
85

86
```python { .api }
87
def _deep_merge_dicts(base: Mapping, addition: Mapping) -> Mapping:
88
    """
89
    Recursively merge two configuration dictionaries.
90
    
91
    Parameters:
92
    - base: Base configuration dictionary
93
    - addition: Additional configuration to merge in (takes precedence)
94
    
95
    Returns:
96
    Mapping: Merged configuration dictionary
97
    """
98
```
99

100
## Configuration Structure
101

102
The configuration system supports extensive customization through the `[tool.poetry-dynamic-versioning]` section:
103

104
### Core Configuration Options
105

106
```python { .api }
107
# Core enable/disable and VCS settings
108
enable: bool = False
109
vcs: str = "any"  # any, git, mercurial, darcs, bazaar, subversion, fossil, pijul
110
dirty: bool = False
111
pattern: Optional[str] = None
112
pattern_prefix: Optional[str] = None
113
latest_tag: bool = False
114

115
# Version formatting and style
116
style: Optional[str] = None  # pep440, semver, pvp
117
metadata: Optional[bool] = None
118
format: Optional[str] = None  
119
format_jinja: Optional[str] = None
120
format_jinja_imports: Sequence[_JinjaImport] = []
121

122
# Version bumping
123
bump: Union[bool, _Bump] = False
124
tagged_metadata: bool = False
125

126
# VCS-specific options
127
full_commit: bool = False
128
tag_branch: Optional[str] = None
129
tag_dir: str = "tags"
130
strict: bool = False
131
fix_shallow_repository: bool = False
132
ignore_untracked: bool = False
133
commit_length: Optional[int] = None
134
commit_prefix: Optional[str] = None
135
escape_with: Optional[str] = None
136
```
137

138
### File Substitution Configuration
139

140
```python { .api }
141
# File substitution settings
142
substitution: _Substitution = {
143
    "files": ["*.py", "*/__init__.py", "*/__version__.py", "*/_version.py"],
144
    "patterns": [
145
        r"(^__version__\s*(?::.*?)?=\s*['\"])[^'\"]*(['\"])",
146
        {
147
            "value": r"(^__version_tuple__\s*(?::.*?)?=\s*\()[^)]*(\))",
148
            "mode": "tuple"
149
        }
150
    ],
151
    "folders": []
152
}
153

154
# Per-file configuration
155
files: Mapping[str, _File] = {}
156

157
# File-based version source
158
from_file: _FromFile = {
159
    "source": None,
160
    "pattern": None
161
}
162
```
163

164
## Usage Examples
165

166
### Basic Configuration Loading
167

168
```python
169
from poetry_dynamic_versioning import _get_config_from_path, _validate_config
170
from pathlib import Path
171

172
# Load configuration for current project
173
config = _get_config_from_path()
174

175
# Validate configuration
176
errors = _validate_config()
177
if errors:
178
    for error in errors:
179
        print(f"Configuration error: {error}")
180
```
181

182
### Advanced Configuration Validation
183

184
```python
185
import tomlkit
186
from poetry_dynamic_versioning import _get_config, _validate_config
187

188
# Load and parse pyproject.toml
189
with open("pyproject.toml", "rb") as f:
190
    pyproject = tomlkit.parse(f.read().decode("utf-8"))
191

192
# Get merged configuration with validation
193
config = _get_config(pyproject)
194
errors = _validate_config(pyproject)
195

196
if not errors:
197
    print("Configuration is valid")
198
    print(f"VCS: {config['vcs']}")
199
    print(f"Pattern: {config['pattern']}")
200
```
201

202
### Configuration Merging
203

204
```python
205
from poetry_dynamic_versioning import _default_config, _deep_merge_dicts
206

207
# Get defaults
208
defaults = _default_config()
209

210
# Custom configuration
211
custom = {
212
    "tool": {
213
        "poetry-dynamic-versioning": {
214
            "enable": True,
215
            "vcs": "git",
216
            "style": "semver",
217
            "substitution": {
218
                "files": ["src/**/*.py"]
219
            }
220
        }
221
    }
222
}
223

224
# Merge configurations
225
merged = _deep_merge_dicts(defaults, custom)
226
final_config = merged["tool"]["poetry-dynamic-versioning"]
227
```