0
# Dunamai
1

2
A Python library and command-line tool for generating dynamic, standards-compliant version strings from version control system tags. Dunamai enables automated version identification for CI/CD pipelines and nightly builds by deriving version information directly from VCS tags, eliminating manual version management.
3

4
```python
5
# Type imports for API documentation
6
import datetime
7
from pathlib import Path
8
from typing import Set, Optional, Union, Tuple, Sequence, Callable
9
```
10

11
## Package Information
12

13
- **Package Name**: dunamai
14
- **Package Type**: pypi
15
- **Language**: Python
16
- **Installation**: `pip install dunamai`
17

18
## Core Imports
19

20
```python
21
import dunamai
22
```
23

24
Common import patterns:
25

26
```python
27
from dunamai import Version, Style, Vcs
28
```
29

30
For specific functionality:
31

32
```python
33
from dunamai import (
34
    Version, Style, Vcs,
35
    get_version, check_version, bump_version,
36
    serialize_pep440, serialize_semver, serialize_pvp
37
)
38
```
39

40
## Basic Usage
41

42
```python
43
from dunamai import Version, Style
44

45
# Auto-detect VCS and get version from current repository
46
version = Version.from_any_vcs()
47
print(version.serialize())  # e.g., "1.2.3.post7.dev0+g29045e8"
48

49
# Get version from specific VCS
50
version = Version.from_git()
51
print(version.serialize(style=Style.SemVer))  # e.g., "1.2.3-post.7+g29045e8"
52

53
# Create version manually
54
version = Version("1.2.3", stage=("rc", 1), distance=5, commit="g29045e8")
55
print(version.serialize())  # "1.2.3rc1.post5.dev0+g29045e8"
56

57
# Validate version strings
58
from dunamai import check_version, Style
59
check_version("1.2.3", Style.SemVer)  # Validates against Semantic Versioning
60
```
61

62
## Architecture
63

64
Dunamai provides a comprehensive version management system with several key components:
65

66
- **Version Control Integration**: Supports 7 VCS systems (Git, Mercurial, Darcs, Subversion, Bazaar, Fossil, Pijul)
67
- **Multiple Version Standards**: PEP 440, Semantic Versioning, Haskell Package Versioning Policy
68
- **Dynamic Generation**: Extracts version from VCS tags with distance and commit information
69
- **CLI Tool**: Command-line interface for static version generation in any language project
70
- **Flexible Serialization**: Custom format strings and built-in standard formats
71

72
## Capabilities
73

74
### Version Creation and Parsing
75

76
Core functionality for creating Version objects from VCS repositories or parsing existing version strings.
77

78
```python { .api }
79
class Version:
80
    def __init__(
81
        self,
82
        base: str,
83
        *,
84
        stage: Optional[Tuple[str, Optional[int]]] = None,
85
        distance: int = 0,
86
        commit: Optional[str] = None,
87
        dirty: Optional[bool] = None,
88
        tagged_metadata: Optional[str] = None,
89
        epoch: Optional[int] = None,
90
        branch: Optional[str] = None,
91
        timestamp: Optional[datetime.datetime] = None,
92
        concerns: Optional[Set[Concern]] = None,
93
        vcs: Vcs = Vcs.Any
94
    ) -> None
95

96
@classmethod
97
def parse(cls, version: str, pattern: Union[str, Pattern] = Pattern.Default) -> "Version"
98
```
99

100
[Version Creation and Parsing](./version-creation.md)
101

102
### VCS Integration
103

104
Extract version information from any supported version control system with automatic detection or explicit VCS selection.
105

106
```python { .api }
107
@classmethod
108
def from_any_vcs(
109
    cls,
110
    pattern: Union[str, Pattern] = Pattern.Default,
111
    latest_tag: bool = False,
112
    tag_dir: str = "tags",
113
    tag_branch: Optional[str] = None,
114
    full_commit: bool = False,
115
    strict: bool = False,
116
    path: Optional[Path] = None,
117
    pattern_prefix: Optional[str] = None,
118
    ignore_untracked: bool = False,
119
    commit_length: Optional[int] = None,
120
) -> "Version"
121

122
@classmethod
123
def from_git(cls, **kwargs) -> "Version"
124

125
@classmethod  
126
def from_mercurial(cls, **kwargs) -> "Version"
127
```
128

129
[VCS Integration](./vcs-integration.md)
130

131
### Version Serialization
132

133
Convert Version objects to standards-compliant version strings with extensive formatting options.
134

135
```python { .api }
136
def serialize(
137
    self,
138
    metadata: Optional[bool] = None,
139
    dirty: bool = False,
140
    format: Optional[Union[str, Callable[["Version"], str]]] = None,
141
    style: Optional[Style] = None,
142
    bump: bool = False,
143
    tagged_metadata: bool = False,
144
    commit_prefix: Optional[str] = None,
145
    escape_with: Optional[str] = None,
146
) -> str
147

148
def serialize_pep440(
149
    base: str,
150
    stage: Optional[str] = None,
151
    revision: Optional[int] = None,
152
    post: Optional[int] = None,
153
    dev: Optional[int] = None,
154
    epoch: Optional[int] = None,
155
    metadata: Optional[Sequence[Union[str, int]]] = None,
156
) -> str
157
```
158

159
[Version Serialization](./version-serialization.md)
160

161
### Utility Functions
162

163
Helper functions for version manipulation, validation, and dynamic version detection.
164

165
```python { .api }
166
def bump_version(base: str, index: int = -1, increment: int = 1) -> str
167

168
def check_version(version: str, style: Style = Style.Pep440) -> None
169

170
def get_version(
171
    name: str,
172
    first_choice: Optional[Callable[[], Optional[Version]]] = None,
173
    third_choice: Optional[Callable[[], Optional[Version]]] = None,
174
    fallback: Version = Version("0.0.0"),
175
    ignore: Optional[Sequence[Version]] = None,
176
    parser: Callable[[str], Version] = Version,
177
) -> Version
178
```
179

180
[Utility Functions](./utility-functions.md)
181

182
### Command Line Interface
183

184
Command-line tool for version generation and validation in any programming language.
185

186
```bash
187
# Auto-detect VCS and generate version
188
dunamai from any
189

190
# Use specific VCS with custom format
191
dunamai from git --format "v{base}+{distance}.{commit}"
192

193
# Validate version strings
194
dunamai check 1.2.3 --style semver
195
```
196

197
[Command Line Interface](./cli-interface.md)
198

199
## Types
200

201
```python { .api }
202
class Style(Enum):
203
    Pep440 = "pep440"
204
    SemVer = "semver" 
205
    Pvp = "pvp"
206

207
class Vcs(Enum):
208
    Any = "any"
209
    Git = "git"
210
    Mercurial = "mercurial"
211
    Darcs = "darcs"
212
    Subversion = "subversion"
213
    Bazaar = "bazaar"
214
    Fossil = "fossil"
215
    Pijul = "pijul"
216

217
class Pattern(Enum):
218
    Default = "default"
219
    DefaultUnprefixed = "default-unprefixed"
220

221
class Concern(Enum):
222
    ShallowRepository = "shallow-repository"
223
```