0
# Built-in Methods
1

2
Pre-built implementations for each pipeline step including VCS querying, version formatting, file writing, and onbuild processing. These methods provide sensible defaults and can be customized through configuration parameters.
3

4
## Capabilities
5

6
### Tag to Version Conversion
7

8
Convert VCS tags to version strings with prefix/suffix removal and regex processing.
9

10
```python { .api }
11
def basic_tag2version(*, tag: str, params: dict[str, Any]) -> str:
12
    """
13
    Implements the "basic" tag2version method for converting tags to versions.
14

15
    Parameters:
16
    - tag: The VCS tag string
17
    - params: Configuration parameters:
18
        - rmprefix (str, optional): Prefix to remove from tag
19
        - rmsuffix (str, optional): Suffix to remove from tag  
20
        - regex (str, optional): Regex to extract version from tag
21
        - require-match (bool, default False): Whether regex must match
22

23
    Returns:
24
    str: Version string extracted from tag (with leading 'v' stripped)
25

26
    Raises:
27
    - InvalidTagError: if require-match is True and regex doesn't match
28
    """
29
```
30

31
### Version Formatting
32

33
Apply formatting templates based on repository state and calculated versions.
34

35
```python { .api }
36
def basic_format(
37
    *,
38
    description: VCSDescription,
39
    base_version: str,
40
    next_version: str,
41
    params: dict[str, Any],
42
) -> str:
43
    """
44
    Implements the "basic" format method for version formatting.
45

46
    Parameters:
47
    - description: VCS repository state
48
    - base_version: Version extracted from tag
49
    - next_version: Calculated next version
50
    - params: Format templates keyed by repository state:
51
        - distance (str): Template for commits ahead of tag
52
        - dirty (str): Template for uncommitted changes
53
        - distance-dirty (str): Template for both conditions
54

55
    Returns:
56
    str: Formatted version string
57

58
    Raises:
59
    - ConfigError: if no format template found for repository state
60
    """
61

62
# Default format templates
63
DEFAULT_FORMATS = {
64
    "distance": "{version}.post{distance}+{vcs}{rev}",
65
    "dirty": "{version}+d{build_date:%Y%m%d}",
66
    "distance-dirty": "{version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}",
67
}
68
```
69

70
### File Writing
71

72
Write version information to files using configurable templates.
73

74
```python { .api }
75
def basic_write(
76
    *,
77
    project_dir: str | Path,
78
    template_fields: dict[str, Any],
79
    params: dict[str, Any],
80
) -> None:
81
    """
82
    Implements the "basic" write method for writing version to files.
83

84
    Parameters:
85
    - project_dir: Path to project root
86
    - template_fields: Variables for template substitution
87
    - params: Configuration parameters:
88
        - file (str): Relative path to file to write
89
        - encoding (str, default "utf-8"): File encoding
90
        - template (str, optional): Template string (auto-detected by extension)
91

92
    Raises:
93
    - ConfigError: if template not specified and file extension unknown
94
    """
95
```
96

97
### Template Fields Generation
98

99
Generate template variables for use in write and onbuild steps.
100

101
```python { .api }
102
def basic_template_fields(
103
    *,
104
    version: str,
105
    description: Optional[VCSDescription],
106
    base_version: Optional[str],
107
    next_version: Optional[str],
108
    params: dict[str, Any],
109
) -> dict[str, Any]:
110
    """
111
    Implements the "basic" template-fields method.
112

113
    Parameters:
114
    - version: Final version string
115
    - description: VCS repository state or None
116
    - base_version: Version from tag or None
117
    - next_version: Calculated next version or None
118
    - params: Configuration parameters:
119
        - version-tuple: Dict configuring version tuple generation:
120
            - pep440 (bool, default False): Use PEP 440 parsing
121
            - epoch (bool, optional): Include epoch in tuple
122
            - split-on (str, optional): Characters to split on (ignored if pep440=True)
123
            - double-quote (bool, default True): Use double quotes in tuple
124

125
    Returns:
126
    dict[str, Any]: Template fields including version, version_tuple, normalized_version, etc.
127
    """
128
```
129

130
### Next Version Calculation
131

132
Built-in methods for calculating the next version after the current tag.
133

134
```python { .api }
135
def next_minor_version(
136
    *,
137
    version: str,
138
    branch: Optional[str],
139
    params: dict[str, Any],
140
) -> str:
141
    """
142
    Implements the "minor" next-version method.
143
    Increments the minor version and sets patch to 0.
144

145
    Parameters:
146
    - version: Base version string
147
    - branch: Current branch name (unused)
148
    - params: Configuration parameters (none used)
149

150
    Returns:
151
    str: Next minor version (e.g., "1.2.3" -> "1.3.0")
152
    """
153

154
def next_smallest_version(
155
    *,
156
    version: str,
157
    branch: Optional[str],
158
    params: dict[str, Any],
159
) -> str:
160
    """
161
    Implements the "smallest" next-version method.
162
    Increments the smallest (rightmost) version component.
163

164
    Parameters:
165
    - version: Base version string
166
    - branch: Current branch name (unused)
167
    - params: Configuration parameters (none used)
168

169
    Returns:
170
    str: Next smallest version (e.g., "1.2.3" -> "1.2.4")
171
    """
172

173
def next_minor_release_version(
174
    *,
175
    version: str,
176
    branch: Optional[str],
177
    params: dict[str, Any],
178
) -> str:
179
    """
180
    Implements the "minor-release" next-version method.
181
    If version is a prerelease, returns base version; otherwise increments minor.
182

183
    Parameters:
184
    - version: Base version string
185
    - branch: Current branch name (unused)  
186
    - params: Configuration parameters (none used)
187

188
    Returns:
189
    str: Next minor or base version
190
    """
191

192
def next_smallest_release_version(
193
    *,
194
    version: str,
195
    branch: Optional[str],
196
    params: dict[str, Any],
197
) -> str:
198
    """
199
    Implements the "smallest-release" next-version method.
200
    If version is a prerelease, returns base version; otherwise increments smallest.
201

202
    Parameters:
203
    - version: Base version string
204
    - branch: Current branch name (unused)
205
    - params: Configuration parameters (none used)
206

207
    Returns:
208
    str: Next smallest or base version
209
    """
210

211
def null_next_version(
212
    *,
213
    version: str,
214
    branch: Optional[str],
215
    params: dict[str, Any],
216
) -> str:
217
    """
218
    Implements the "null" next-version method.
219
    Returns the same version unchanged.
220

221
    Parameters:
222
    - version: Base version string
223
    - branch: Current branch name (unused)
224
    - params: Configuration parameters (none used)
225

226
    Returns:
227
    str: Unchanged version
228
    """
229
```
230

231
### Onbuild Processing
232

233
Replace version strings in files during the build process.
234

235
```python { .api }
236
def replace_version_onbuild(
237
    *,
238
    file_provider: OnbuildFileProvider,
239
    is_source: bool,
240
    template_fields: dict[str, Any],
241
    params: dict[str, Any],
242
) -> None:
243
    """
244
    Implements the "replace-version" onbuild method.
245

246
    Parameters:
247
    - file_provider: Interface for accessing build files
248
    - is_source: True for sdist, False for wheel
249
    - template_fields: Variables for template substitution
250
    - params: Configuration parameters:
251
        - source-file (str): Path in source tree
252
        - build-file (str): Path in build/install tree
253
        - encoding (str, default "utf-8"): File encoding
254
        - regex (str): Regex to find version line (default: __version__ pattern)
255
        - require-match (bool, default False): Whether regex must match
256
        - replacement (str): Replacement template (default: '"{version}"')
257
        - append-line (str, optional): Line to append if no match found
258

259
    Raises:
260
    - ConfigError: if regex is invalid
261
    - RuntimeError: if require-match is True and no match found
262
    """
263
```
264

265
## Usage Examples
266

267
### Tag2Version Configuration
268

269
```python
270
# Basic prefix/suffix removal
271
config = {
272
    "tag2version": {
273
        "method": "basic",
274
        "rmprefix": "v",
275
        "rmsuffix": "-release"
276
    }
277
}
278
# v1.2.3-release -> 1.2.3
279

280
# Regex extraction
281
config = {
282
    "tag2version": {
283
        "method": "basic",
284
        "regex": r"release-(?P<version>.*)",
285
        "require-match": True
286
    }
287
}
288
# release-1.2.3 -> 1.2.3
289
```
290

291
### Format Configuration
292

293
```python
294
config = {
295
    "format": {
296
        "distance": "{version}.dev{distance}+g{rev}",
297
        "dirty": "{version}+dirty.{build_date:%Y%m%d}",
298
        "distance-dirty": "{version}.dev{distance}+g{rev}.dirty.{build_date:%Y%m%d}"
299
    }
300
}
301

302
# Examples:
303
# Exact tag: "1.2.3"
304
# 5 commits ahead: "1.2.3.dev5+g1234567"
305
# Dirty working tree: "1.2.3+dirty.20231201"
306
# Both: "1.2.3.dev5+g1234567.dirty.20231201"
307
```
308

309
### Write Configuration
310

311
```python
312
# Python file
313
config = {
314
    "write": {
315
        "file": "src/mypackage/_version.py",
316
        "template": '__version__ = "{version}"'
317
    }
318
}
319

320
# Text file
321
config = {
322
    "write": {
323
        "file": "VERSION",
324
        "template": "{version}"
325
    }
326
}
327

328
# Custom template with multiple fields
329
config = {
330
    "write": {
331
        "file": "src/mypackage/_build_info.py",
332
        "template": '''
333
__version__ = "{version}"
334
__version_tuple__ = {version_tuple}
335
__build_date__ = "{build_date}"
336
__git_revision__ = "{rev}"
337
'''
338
    }
339
}
340
```
341

342
### Template Fields Configuration
343

344
```python
345
# Basic version tuple
346
config = {
347
    "template-fields": {
348
        "method": "basic",
349
        "version-tuple": {
350
            "pep440": False,
351
            "split-on": ".",
352
            "double-quote": True
353
        }
354
    }
355
}
356
# "1.2.3" -> ("1", "2", "3")
357

358
# PEP 440 parsing
359
config = {
360
    "template-fields": {
361
        "method": "basic", 
362
        "version-tuple": {
363
            "pep440": True,
364
            "epoch": True,
365
            "double-quote": False
366
        }
367
    }
368
}
369
# "1!2.3.4a1" -> (1, 2, 3, 4, 'a', 1)
370
```
371

372
### Next Version Examples
373

374
```python
375
# minor: 1.2.3 -> 1.3.0
376
config = {"next-version": {"method": "minor"}}
377

378
# smallest: 1.2.3 -> 1.2.4  
379
config = {"next-version": {"method": "smallest"}}
380

381
# minor-release: 1.2.3a1 -> 1.2.3, 1.2.3 -> 1.3.0
382
config = {"next-version": {"method": "minor-release"}}
383

384
# smallest-release: 1.2.3a1 -> 1.2.3, 1.2.3 -> 1.2.4
385
config = {"next-version": {"method": "smallest-release"}}
386

387
# null: 1.2.3 -> 1.2.3 (unchanged)
388
config = {"next-version": {"method": "null"}}
389
```
390

391
### Onbuild Configuration
392

393
```python
394
# Replace __version__ in Python file
395
config = {
396
    "onbuild": {
397
        "method": "replace-version",
398
        "source-file": "src/mypackage/__init__.py",
399
        "build-file": "mypackage/__init__.py",
400
        "regex": r'^__version__ = .*$',
401
        "replacement": '__version__ = "{version}"'
402
    }
403
}
404

405
# Custom regex pattern
406
config = {
407
    "onbuild": {
408
        "method": "replace-version",
409
        "source-file": "version.h",
410
        "build-file": "version.h", 
411
        "regex": r'#define VERSION ".*"',
412
        "replacement": '#define VERSION "{version}"',
413
        "require-match": True
414
    }
415
}
416

417
# Append if no match found
418
config = {
419
    "onbuild": {
420
        "method": "replace-version",
421
        "source-file": "setup.cfg",
422
        "build-file": "setup.cfg",
423
        "regex": r'^version = .*$',
424
        "replacement": 'version = {version}',
425
        "append-line": 'version = {version}'
426
    }
427
}
428
```
429

430
### Complete Configuration Example
431

432
```python
433
config = {
434
    "default-version": "0.0.0.dev0",
435
    "vcs": {
436
        "method": "git",
437
        "match": ["v*.*.*"],
438
        "exclude": ["*rc*"]
439
    },
440
    "tag2version": {
441
        "method": "basic",
442
        "rmprefix": "v"
443
    },
444
    "next-version": {
445
        "method": "smallest"
446
    },
447
    "format": {
448
        "distance": "{version}.post{distance}+{vcs}{rev}",
449
        "dirty": "{version}+d{build_date:%Y%m%d}",
450
        "distance-dirty": "{version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
451
    },
452
    "template-fields": {
453
        "method": "basic",
454
        "version-tuple": {
455
            "pep440": True,
456
            "double-quote": False
457
        }
458
    },
459
    "write": {
460
        "file": "src/mypackage/_version.py",
461
        "template": '__version__ = "{version}"\n__version_tuple__ = {version_tuple}'
462
    },
463
    "onbuild": {
464
        "method": "replace-version",
465
        "source-file": "src/mypackage/__init__.py",
466
        "build-file": "mypackage/__init__.py"
467
    }
468
}
469
```