0
# Data Models
1

2
Core data structures for representing VCS state, version calculation results, and intermediate values throughout the pipeline. These models provide structured access to all information generated during version calculation.
3

4
## Capabilities
5

6
### VCS Description
7

8
Represents the state of a version control repository including tag information, repository state, and additional metadata.
9

10
```python { .api }
11
@dataclass
12
class VCSDescription:
13
    """A description of the state of a version control repository."""
14
    
15
    tag: str
16
    """
17
    The name of the most recent tag in the repository (possibly after
18
    applying any match or exclusion rules based on user parameters) from
19
    which the current repository state is descended.
20
    """
21
    
22
    state: str  
23
    """
24
    The relationship of the repository's current state to the tag. If the
25
    repository state is exactly the tagged state, this field equals "exact";
26
    otherwise, it will be a string used as a key in the format subtable.
27
    Recommended values are "distance", "dirty", and "distance-dirty".
28
    """
29
    
30
    branch: Optional[str]
31
    """
32
    The name of the repository's current branch, or None if it cannot be
33
    determined or does not apply.
34
    """
35
    
36
    fields: dict[str, Any]
37
    """
38
    A dict of additional information about the repository state to make
39
    available to the format method. Custom vcs methods are advised to
40
    adhere closely to the set of fields used by the built-in methods.
41
    """
42
```
43

44
### Version Calculation Report
45

46
Comprehensive report containing the final version and all intermediate values calculated during a versioningit run.
47

48
```python { .api }
49
@dataclass
50
class Report:
51
    """
52
    A report of the intermediate & final values calculated during a
53
    versioningit run.
54
    """
55
    
56
    version: str
57
    """The final version."""
58
    
59
    description: Optional[VCSDescription]
60
    """
61
    A description of the state of the version control repository; None if
62
    the "vcs" step failed.
63
    """
64
    
65
    base_version: Optional[str]
66
    """
67
    A version string extracted from the VCS tag; None if the "tag2version"
68
    step or a previous step failed.
69
    """
70
    
71
    next_version: Optional[str]
72
    """
73
    A "next version" calculated by the "next-version" step; None if the
74
    step or a previous one failed.
75
    """
76
    
77
    template_fields: dict[str, Any]
78
    """
79
    A dict of fields for use in templating by the "write" and "onbuild"
80
    steps.
81
    """
82
    
83
    using_default_version: bool
84
    """
85
    True iff an error occurred during version calculation, causing a
86
    default-version setting to be used.
87
    """
88
```
89

90
### Fallback Report
91

92
Simple report for versions extracted from PKG-INFO files in source distributions.
93

94
```python { .api }
95
@dataclass
96
class FallbackReport:
97
    """
98
    A report of the version extracted from a PKG-INFO file in an sdist.
99
    """
100
    
101
    version: str
102
    """The version."""
103
```
104

105

106
## Usage Examples
107

108
### Working with VCSDescription
109

110
```python
111
from versioningit import Versioningit
112

113
vgit = Versioningit.from_project_dir()
114
description = vgit.do_vcs()
115

116
print(f"Most recent tag: {description.tag}")
117
print(f"Repository state: {description.state}")
118
print(f"Current branch: {description.branch}")
119
print(f"Additional fields: {description.fields}")
120

121
# Check repository state
122
if description.state == "exact":
123
    print("Repository is at exact tag")
124
elif description.state == "distance":
125
    print(f"Repository is {description.fields.get('distance', '?')} commits ahead")
126
elif description.state == "dirty":
127
    print("Repository has uncommitted changes")
128
elif description.state == "distance-dirty":
129
    print("Repository has commits ahead and uncommitted changes")
130
```
131

132
### Working with Reports
133

134
```python
135
from versioningit import Versioningit, Report, FallbackReport
136

137
vgit = Versioningit.from_project_dir()
138
report = vgit.run()
139

140
if isinstance(report, FallbackReport):
141
    print(f"Version from PKG-INFO: {report.version}")
142
elif isinstance(report, Report):
143
    print(f"Final version: {report.version}")
144
    
145
    if report.using_default_version:
146
        print("Used default version due to error")
147
    
148
    if report.description:
149
        print(f"VCS tag: {report.description.tag}")
150
        print(f"VCS state: {report.description.state}")
151
    
152
    if report.base_version:
153
        print(f"Base version from tag: {report.base_version}")
154
    
155
    if report.next_version:
156
        print(f"Calculated next version: {report.next_version}")
157
    
158
    print("Template fields available:")
159
    for key, value in report.template_fields.items():
160
        print(f"  {key}: {value}")
161
```
162

163

164
### Accessing Template Fields
165

166
```python
167
from versioningit import Versioningit
168

169
vgit = Versioningit.from_project_dir()
170
report = vgit.run()
171

172
# Template fields are used for file writing and onbuild
173
fields = report.template_fields
174

175
# Common fields available
176
print(f"Version: {fields.get('version')}")
177
print(f"Base version: {fields.get('base_version')}")
178
print(f"Next version: {fields.get('next_version')}")
179
print(f"Branch: {fields.get('branch')}")
180
print(f"Version tuple: {fields.get('version_tuple')}")
181
print(f"Normalized version: {fields.get('normalized_version')}")
182

183
# VCS-specific fields (when available)
184
print(f"VCS type: {fields.get('vcs')}")
185
print(f"Revision: {fields.get('rev')}")
186
print(f"Distance: {fields.get('distance')}")
187
print(f"Build date: {fields.get('build_date')}")
188
```
189

190
### Error States in Reports
191

192
```python
193
from versioningit import Versioningit
194

195
# Configure with default version for error handling
196
config = {"default-version": "0.0.0.dev0"}
197
vgit = Versioningit.from_project_dir(config=config)
198

199
report = vgit.run()
200

201
if report.using_default_version:
202
    print(f"Used default version: {report.version}")
203
    
204
    # Check what failed
205
    if report.description is None:
206
        print("VCS step failed")
207
    elif report.base_version is None:
208
        print("Tag2version step failed")
209
    elif report.next_version is None:
210
        print("Next-version step failed")
211
else:
212
    print(f"Successfully calculated version: {report.version}")
213
```