0
# Version Creation and Parsing
1

2
Core functionality for creating Version objects from components or parsing existing version strings into structured objects.
3

4
## Capabilities
5

6
### Version Object Creation
7

8
Create a Version object with complete version information including base version, pre-release stage, distance from tags, and VCS metadata.
9

10
```python { .api }
11
class Version:
12
    def __init__(
13
        self,
14
        base: str,
15
        *,
16
        stage: Optional[Tuple[str, Optional[int]]] = None,
17
        distance: int = 0,
18
        commit: Optional[str] = None,
19
        dirty: Optional[bool] = None,
20
        tagged_metadata: Optional[str] = None,
21
        epoch: Optional[int] = None,
22
        branch: Optional[str] = None,
23
        timestamp: Optional[dt.datetime] = None,
24
        concerns: Optional[Set[Concern]] = None,
25
        vcs: Vcs = Vcs.Any
26
    ) -> None
27
```
28

29
**Parameters**:
30
- `base`: Release segment like "1.2.3"
31
- `stage`: Pre-release stage as (stage_name, revision) tuple (e.g., ("rc", 1))
32
- `distance`: Number of commits since the last tag
33
- `commit`: Commit hash/identifier
34
- `dirty`: True if working directory has uncommitted changes
35
- `tagged_metadata`: Metadata from the tag itself
36
- `epoch`: PEP 440 epoch number
37
- `branch`: Current branch name
38
- `timestamp`: Commit timestamp as datetime object
39
- `concerns`: Set of version concerns/warnings
40
- `vcs`: Source version control system
41

42
**Usage Examples**:
43

44
```python
45
from dunamai import Version, Vcs
46
import datetime as dt
47

48
# Basic version
49
version = Version("1.2.3")
50

51
# Pre-release version
52
version = Version("1.2.3", stage=("rc", 1))
53

54
# Development version with VCS info
55
version = Version(
56
    "1.2.3",
57
    stage=("dev", None),
58
    distance=7,
59
    commit="g29045e8",
60
    dirty=True,
61
    branch="feature/new-api",
62
    vcs=Vcs.Git
63
)
64

65
# Version with epoch and metadata
66
version = Version(
67
    "2.0.0",
68
    epoch=1,
69
    tagged_metadata="linux",
70
    timestamp=dt.datetime.now()
71
)
72
```
73

74
### Version String Parsing
75

76
Parse existing version strings into Version objects using pattern matching and heuristics.
77

78
```python { .api }
79
@classmethod
80
def parse(cls, version: str, pattern: Union[str, Pattern] = Pattern.Default) -> "Version"
81
```
82

83
**Parameters**:
84
- `version`: Version string to parse (e.g., "v1.2.3-rc1+g29045e8.dirty")
85
- `pattern`: Regular expression pattern or preset Pattern enum for parsing
86

87
**Returns**: Version object with parsed components
88

89
**Usage Examples**:
90

91
```python
92
from dunamai import Version, Pattern
93

94
# Parse with default pattern (supports 'v' prefix)
95
version = Version.parse("v1.2.3-rc1.post7.dev0+g29045e8")
96
print(version.base)      # "1.2.3"
97
print(version.stage)     # "rc"
98
print(version.revision)  # 1
99
print(version.distance)  # 7
100
print(version.commit)    # "g29045e8"
101

102
# Parse without 'v' prefix
103
version = Version.parse("1.2.3-alpha.2", Pattern.DefaultUnprefixed)
104

105
# Parse with custom pattern
106
custom_pattern = r"^(?P<base>\d+\.\d+\.\d+)(-(?P<stage>\w+)\.(?P<revision>\d+))?$"
107
version = Version.parse("1.2.3-beta.5", custom_pattern)
108
```
109

110
### Version Properties
111

112
Access individual components of a Version object.
113

114
**Properties**:
115
- `base: str` - Release segment
116
- `stage: Optional[str]` - Pre-release stage name
117
- `revision: Optional[int]` - Pre-release revision number
118
- `distance: int` - Commits since last tag
119
- `commit: Optional[str]` - Commit identifier
120
- `dirty: Optional[bool]` - Uncommitted changes flag
121
- `tagged_metadata: Optional[str]` - Tag metadata
122
- `epoch: Optional[int]` - PEP 440 epoch
123
- `branch: Optional[str]` - Branch name
124
- `timestamp: Optional[datetime]` - Commit timestamp
125
- `concerns: Optional[Set[Concern]]` - Version concerns
126
- `vcs: Vcs` - Source VCS
127

128
**Usage Examples**:
129

130
```python
131
from dunamai import Version
132

133
version = Version("1.2.3", stage=("rc", 1), distance=5, commit="g29045e8")
134

135
print(f"Base version: {version.base}")           # "1.2.3"
136
print(f"Pre-release: {version.stage}")           # "rc"
137
print(f"Revision: {version.revision}")           # 1
138
print(f"Distance: {version.distance}")           # 5
139
print(f"Commit: {version.commit}")               # "g29045e8"
140

141
# Check if this is a development version
142
is_dev = version.distance > 0
143
print(f"Development version: {is_dev}")          # True
144
```
145

146
### Version Comparison
147

148
Compare Version objects using standard comparison operators.
149

150
```python { .api }
151
def __eq__(self, other: Any) -> bool
152
def __lt__(self, other: Any) -> bool
153
```
154

155
**Usage Examples**:
156

157
```python
158
from dunamai import Version
159

160
v1 = Version("1.2.3")
161
v2 = Version("1.2.4") 
162
v3 = Version("1.2.3", stage=("rc", 1))
163

164
print(v1 < v2)    # True
165
print(v1 == v3)   # False (different stage)
166
print(v3 < v1)    # True (pre-release < release)
167

168
# Sort versions
169
versions = [
170
    Version("1.2.3"),
171
    Version("1.2.3", stage=("rc", 1)),
172
    Version("1.2.4")
173
]
174
sorted_versions = sorted(versions)
175
```
176

177
### Version String Representation
178

179
Convert Version objects to string representations.
180

181
```python { .api }
182
def __str__(self) -> str
183
def __repr__(self) -> str
184
```
185

186
**Usage Examples**:
187

188
```python
189
from dunamai import Version
190

191
version = Version("1.2.3", stage=("rc", 1), distance=5)
192

193
print(str(version))    # Uses serialize() - "1.2.3rc1.post5.dev0"
194
print(repr(version))   # Detailed representation showing all attributes
195
```