0
# Versioningit Class
1

2
Object-oriented interface providing fine-grained control over the version calculation pipeline. This class allows step-by-step execution, detailed reporting, and advanced customization of the versioning process.
3

4
## Capabilities
5

6
### Class Construction
7

8
Create Versioningit instances from project directories or configuration objects.
9

10
```python { .api }
11
class Versioningit:
12
    project_dir: Path
13
    default_version: Optional[str]
14
    vcs: VersioningitMethod
15
    tag2version: VersioningitMethod
16
    next_version: VersioningitMethod
17
    format: VersioningitMethod
18
    template_fields: VersioningitMethod
19
    write: Optional[VersioningitMethod]
20
    onbuild: Optional[VersioningitMethod]
21

22
    @classmethod
23
    def from_project_dir(
24
        cls, project_dir: str | Path = os.curdir, config: Optional[dict] = None
25
    ) -> Versioningit:
26
        """
27
        Construct a Versioningit object for the project rooted at project_dir.
28

29
        Parameters:
30
        - project_dir: Project root directory (default: current directory)
31
        - config: Configuration dict or None to read from configuration file
32

33
        Returns:
34
        Versioningit: Configured instance ready for version calculation
35

36
        Raises:
37
        - NoConfigFileError: if config is None and no configuration file exists
38
        - NoConfigSectionError: if configuration file has no versioningit section  
39
        - ConfigError: if configuration values are invalid
40
        """
41

42
    @classmethod
43
    def from_config(cls, project_dir: str | Path, config: Config) -> Versioningit:
44
        """
45
        Construct a Versioningit object from a parsed configuration object.
46
        """
47
```
48

49
### Version Calculation
50

51
Execute the version calculation pipeline with optional file writing.
52

53
```python { .api }
54
def get_version(self, write: bool = False, fallback: bool = True) -> str:
55
    """
56
    Determine the version for the project.
57

58
    Parameters:
59
    - write: Whether to update file specified in write configuration
60
    - fallback: Whether to read from PKG-INFO if not under version control
61

62
    Returns:
63
    str: The calculated version string
64

65
    Raises:
66
    - NotVCSError: if fallback is False and not under version control
67
    - NotSdistError: if fallback is True, not under VCS, and no PKG-INFO
68
    - ConfigError: if configuration values are invalid
69
    - MethodError: if a method returns wrong type
70
    """
71

72
def run(
73
    self, write: bool = False, fallback: bool = True
74
) -> Report | FallbackReport:
75
    """
76
    Run all pipeline steps and return detailed report with intermediate values.
77

78
    Parameters:
79
    - write: Whether to update file specified in write configuration
80
    - fallback: Whether to read from PKG-INFO if not under version control
81

82
    Returns:
83
    Report | FallbackReport: Detailed execution report with all calculated values
84

85
    Raises:
86
    - NotVCSError: if fallback is False and not under version control
87
    - NotSdistError: if fallback is True, not under VCS, and no PKG-INFO
88
    - ConfigError: if configuration values are invalid
89
    - MethodError: if a method returns wrong type
90
    """
91
```
92

93
### Individual Step Execution
94

95
Execute individual pipeline steps for debugging or custom workflows.
96

97
```python { .api }
98
def do_vcs(self) -> VCSDescription:
99
    """
100
    Run the vcs step to query version control system.
101

102
    Returns:
103
    VCSDescription: Repository state information
104

105
    Raises:
106
    - MethodError: if method does not return VCSDescription
107
    """
108

109
def do_tag2version(self, tag: str) -> str:
110
    """
111
    Run the tag2version step to extract version from tag.
112

113
    Parameters:
114
    - tag: VCS tag string
115

116
    Returns:
117
    str: Version string extracted from tag
118

119
    Raises:
120
    - MethodError: if method does not return str
121
    """
122

123
def do_next_version(self, version: str, branch: Optional[str]) -> str:
124
    """
125
    Run the next-version step to calculate next version.
126

127
    Parameters:
128
    - version: Base version string
129
    - branch: Current branch name or None
130

131
    Returns:
132
    str: Calculated next version
133

134
    Raises:
135
    - MethodError: if method does not return str
136
    """
137

138
def do_format(
139
    self, description: VCSDescription, base_version: str, next_version: str
140
) -> str:
141
    """
142
    Run the format step to apply version formatting.
143

144
    Parameters:
145
    - description: VCS repository state
146
    - base_version: Version extracted from tag
147
    - next_version: Calculated next version
148

149
    Returns:
150
    str: Formatted version string
151

152
    Raises:
153
    - MethodError: if method does not return str
154
    """
155

156
def do_template_fields(
157
    self,
158
    version: str,
159
    description: Optional[VCSDescription],
160
    base_version: Optional[str],
161
    next_version: Optional[str],
162
) -> dict:
163
    """
164
    Run the template-fields step to generate template variables.
165

166
    Parameters:
167
    - version: Final version string
168
    - description: VCS repository state or None
169
    - base_version: Version from tag or None
170
    - next_version: Calculated next version or None
171

172
    Returns:
173
    dict: Template fields for write and onbuild steps
174

175
    Raises:
176
    - MethodError: if method does not return dict
177
    """
178

179
def do_write(self, template_fields: dict[str, Any]) -> None:
180
    """
181
    Run the write step to update version file.
182

183
    Parameters:
184
    - template_fields: Variables for template substitution
185
    """
186

187
def do_onbuild(
188
    self,
189
    file_provider: OnbuildFileProvider,
190
    is_source: bool,
191
    template_fields: dict[str, Any],
192
) -> None:
193
    """
194
    Run the onbuild step to modify build artifacts.
195

196
    Parameters:
197
    - file_provider: Interface for accessing build files
198
    - is_source: True for sdist, False for wheel
199
    - template_fields: Variables for template substitution
200
    """
201
```
202

203
## Usage Examples
204

205
### Basic Class Usage
206

207
```python
208
from versioningit import Versioningit
209

210
# Create instance and get version
211
vgit = Versioningit.from_project_dir()
212
version = vgit.get_version()
213
print(f"Version: {version}")
214

215
# Get detailed report
216
report = vgit.run()
217
print(f"Version: {report.version}")
218
print(f"Base version: {report.base_version}")
219
print(f"Next version: {report.next_version}")
220
print(f"Using default: {report.using_default_version}")
221
```
222

223
### Step-by-Step Execution
224

225
```python
226
from versioningit import Versioningit
227

228
vgit = Versioningit.from_project_dir()
229

230
# Execute individual steps
231
try:
232
    description = vgit.do_vcs()
233
    print(f"Tag: {description.tag}")
234
    print(f"State: {description.state}")
235
    print(f"Branch: {description.branch}")
236
    
237
    base_version = vgit.do_tag2version(description.tag)
238
    print(f"Base version: {base_version}")
239
    
240
    next_version = vgit.do_next_version(base_version, description.branch)
241
    print(f"Next version: {next_version}")
242
    
243
    if description.state == "exact":
244
        final_version = base_version
245
    else:
246
        final_version = vgit.do_format(description, base_version, next_version)
247
    
248
    print(f"Final version: {final_version}")
249
    
250
    template_fields = vgit.do_template_fields(
251
        final_version, description, base_version, next_version
252
    )
253
    print(f"Template fields: {template_fields}")
254
    
255
except Exception as e:
256
    print(f"Error in pipeline: {e}")
257
```
258

259
### Custom Configuration
260

261
```python
262
config = {
263
    "default-version": "0.0.0",
264
    "vcs": {"method": "git"},
265
    "tag2version": {"method": "basic", "rmprefix": "v"},
266
    "next-version": {"method": "smallest"},
267
    "format": {
268
        "distance": "{version}.dev{distance}+{vcs}{rev}",
269
        "dirty": "{version}+dirty"
270
    },
271
    "template-fields": {"method": "basic"},
272
    "write": {
273
        "file": "version.txt",
274
        "template": "{version}"
275
    }
276
}
277

278
vgit = Versioningit.from_project_dir(config=config)
279
version = vgit.get_version(write=True)
280
```
281

282
### Error Handling and Fallback
283

284
```python
285
from versioningit import Versioningit, NotVCSError
286

287
vgit = Versioningit.from_project_dir()
288

289
try:
290
    # Try without fallback first
291
    version = vgit.get_version(fallback=False)
292
    print(f"VCS version: {version}")
293
except NotVCSError:
294
    # Fallback to PKG-INFO
295
    try:
296
        report = vgit.run(fallback=True)
297
        if isinstance(report, FallbackReport):
298
            print(f"PKG-INFO version: {report.version}")
299
        else:
300
            print(f"VCS version: {report.version}")
301
    except Exception as e:
302
        print(f"Could not determine version: {e}")
303
```