0
# Versioningit
1

2
A Python packaging plugin for automatically determining package versions based on version control repository tags. Unlike other tools, it allows easy customization of version formats and provides hooks for custom methods through entry points or project-specific functions.
3

4
## Package Information
5

6
- **Package Name**: versioningit
7
- **Language**: Python  
8
- **Installation**: `pip install versioningit`
9

10
## Core Imports
11

12
```python
13
import versioningit
14
```
15

16
Common usage imports:
17

18
```python
19
from versioningit import get_version, get_next_version, Versioningit
20
```
21

22
For setuptools integration:
23

24
```python
25
from versioningit import get_cmdclasses
26
```
27

28
## Basic Usage
29

30
```python
31
from versioningit import get_version, get_next_version
32

33
# Get current version from VCS tags
34
version = get_version()
35
print(f"Current version: {version}")
36

37
# Get next calculated version
38
next_version = get_next_version()
39
print(f"Next version: {next_version}")
40

41
# Use with custom configuration
42
config = {
43
    "vcs": {"method": "git"},
44
    "tag2version": {"method": "basic", "rmprefix": "v"},
45
    "format": {
46
        "distance": "{version}.post{distance}+{vcs}{rev}",
47
        "dirty": "{version}+d{build_date:%Y%m%d}"
48
    }
49
}
50
version = get_version(config=config)
51
```
52

53
## Architecture
54

55
Versioningit follows a step-based pipeline architecture with customizable methods:
56

57
- **VCS Step**: Query version control system for tag and repository state
58
- **Tag2Version Step**: Extract version string from VCS tag
59
- **Next-Version Step**: Calculate next version for development
60
- **Format Step**: Apply version formatting based on repository state
61
- **Template-Fields Step**: Generate fields for file templating
62
- **Write Step**: Optionally write version to files
63
- **Onbuild Step**: Insert version into build artifacts
64

65
Each step can be customized using built-in methods, entry points, or custom functions.
66

67
## Capabilities
68

69
### Core Version Operations
70

71
Main functions for determining and calculating versions from version control systems, with support for fallback scenarios and custom configurations.
72

73
```python { .api }
74
def get_version(
75
    project_dir: str | Path = os.curdir,
76
    config: Optional[dict] = None,
77
    write: bool = False,
78
    fallback: bool = True,
79
) -> str: ...
80

81
def get_next_version(
82
    project_dir: str | Path = os.curdir, 
83
    config: Optional[dict] = None
84
) -> str: ...
85

86
def get_version_from_pkg_info(project_dir: str | Path) -> str: ...
87
```
88

89
[Core Version Operations](./core-operations.md)
90

91
### Versioningit Class API
92

93
Object-oriented interface providing fine-grained control over the version calculation pipeline with step-by-step execution and reporting.
94

95
```python { .api }
96
class Versioningit:
97
    @classmethod
98
    def from_project_dir(
99
        cls, project_dir: str | Path = os.curdir, config: Optional[dict] = None
100
    ) -> Versioningit: ...
101
    
102
    def get_version(self, write: bool = False, fallback: bool = True) -> str: ...
103
    def run(self, write: bool = False, fallback: bool = True) -> Report | FallbackReport: ...
104
```
105

106
[Versioningit Class](./versioningit-class.md)
107

108
### Data Models and Reports
109

110
Core data structures for representing VCS state, version calculation results, and intermediate values throughout the pipeline.
111

112
```python { .api }
113
@dataclass
114
class VCSDescription:
115
    tag: str
116
    state: str
117
    branch: Optional[str]
118
    fields: dict[str, Any]
119

120
@dataclass
121
class Report:
122
    version: str
123
    description: Optional[VCSDescription]
124
    base_version: Optional[str]
125
    next_version: Optional[str]
126
    template_fields: dict[str, Any]
127
    using_default_version: bool
128
```
129

130
[Data Models](./data-models.md)
131

132
### Build Integration
133

134
Integration with build systems including setuptools command classes and onbuild hooks for inserting version information into build artifacts.
135

136
```python { .api }
137
def get_cmdclasses(
138
    bases: Optional[dict[str, type[Command]]] = None
139
) -> dict[str, type[Command]]: ...
140

141
def run_onbuild(
142
    *,
143
    build_dir: str | Path,
144
    is_source: bool,
145
    template_fields: dict[str, Any],
146
    project_dir: str | Path = os.curdir,
147
    config: Optional[dict] = None,
148
) -> None: ...
149
```
150

151
[Build Integration](./build-integration.md)
152

153
### Built-in Methods
154

155
Pre-built implementations for each pipeline step including VCS querying, version formatting, file writing, and onbuild processing.
156

157
```python { .api }
158
def basic_tag2version(*, tag: str, params: dict[str, Any]) -> str: ...
159
def basic_format(
160
    *,
161
    description: VCSDescription,
162
    base_version: str,
163
    next_version: str,
164
    params: dict[str, Any],
165
) -> str: ...
166
def basic_write(
167
    *,
168
    project_dir: str | Path,
169
    template_fields: dict[str, Any],
170
    params: dict[str, Any],
171
) -> None: ...
172
```
173

174
[Built-in Methods](./builtin-methods.md)
175

176
### Method System
177

178
Framework for loading and executing custom methods via entry points, module imports, or direct callables with parameter passing.
179

180
```python { .api }
181
@dataclass
182
class VersioningitMethod:
183
    method: Callable
184
    params: dict[str, Any]
185
    
186
    def __call__(self, **kwargs: Any) -> Any: ...
187

188
class MethodSpec(ABC):
189
    @abstractmethod
190
    def load(self, project_dir: str | Path) -> Callable: ...
191
```
192

193
[Method System](./method-system.md)
194

195
### Exception Handling
196

197
Comprehensive error hierarchy for handling configuration errors, VCS issues, and method validation problems.
198

199
```python { .api }
200
class Error(Exception): ...
201
class ConfigError(Error, ValueError): ...
202
class MethodError(Error): ...
203
class NotVCSError(Error): ...
204
class NoTagError(Error): ...
205
class InvalidTagError(Error, ValueError): ...
206
class InvalidVersionError(Error, ValueError): ...
207
```
208

209
[Exception Handling](./exceptions.md)
210

211
## Types
212

213
```python { .api }
214
from pathlib import Path
215
from typing import Any, Callable, Optional
216

217
# Type aliases for common parameters
218
ProjectDir = str | Path
219
ConfigDict = Optional[dict[str, Any]]
220
TemplateFields = dict[str, Any]
221
```