0
# Core Version Operations
1

2
Main functions for determining and calculating versions from version control systems. These functions provide the primary interface for most use cases, with automatic configuration loading and fallback support.
3

4
## Capabilities
5

6
### Version Determination
7

8
Get the current version for a project based on VCS tags and configuration.
9

10
```python { .api }
11
def get_version(
12
    project_dir: str | Path = os.curdir,
13
    config: Optional[dict] = None,
14
    write: bool = False,
15
    fallback: bool = True,
16
) -> str:
17
    """
18
    Determine the version for the project at project_dir.
19

20
    Parameters:
21
    - project_dir: Path to project root (default: current directory)
22
    - config: Configuration dict or None to read from pyproject.toml/versioningit.toml
23
    - write: Whether to write version to file specified in configuration
24
    - fallback: Whether to read from PKG-INFO if not under version control
25

26
    Returns:
27
    str: The calculated version string
28

29
    Raises:
30
    - NotVCSError: if fallback is False and project_dir is not under version control
31
    - NotSdistError: if fallback is True, not under VCS, and no PKG-INFO file
32
    - NoConfigFileError: if config is None and no configuration file exists
33
    - NoConfigSectionError: if configuration file has no versioningit section
34
    - ConfigError: if configuration values are invalid
35
    - MethodError: if a method returns wrong type
36
    """
37
```
38

39
### Next Version Calculation
40

41
Calculate the next version after the current VCS-tagged version.
42

43
```python { .api }
44
def get_next_version(
45
    project_dir: str | Path = os.curdir, 
46
    config: Optional[dict] = None
47
) -> str:
48
    """
49
    Determine the next version after the current VCS-tagged version.
50

51
    Parameters:
52
    - project_dir: Path to project root (default: current directory)
53
    - config: Configuration dict or None to read from configuration file
54

55
    Returns:
56
    str: The calculated next version string
57

58
    Raises:
59
    - NotVCSError: if project_dir is not under version control
60
    - NoConfigFileError: if config is None and no configuration file exists  
61
    - NoConfigSectionError: if configuration file has no versioningit section
62
    - ConfigError: if configuration values are invalid
63
    - MethodError: if a method returns wrong type
64
    """
65
```
66

67
### PKG-INFO Version Extraction
68

69
Extract version from PKG-INFO file in source distributions.
70

71
```python { .api }
72
def get_version_from_pkg_info(project_dir: str | Path) -> str:
73
    """
74
    Return the Version field from the PKG-INFO file in project_dir.
75

76
    Parameters:
77
    - project_dir: Path to directory containing PKG-INFO file
78

79
    Returns:
80
    str: Version string from PKG-INFO file
81

82
    Raises:
83
    - NotSdistError: if there is no PKG-INFO file
84
    - ValueError: if PKG-INFO file does not contain a Version field
85
    """
86
```
87

88
## Usage Examples
89

90
### Basic Version Retrieval
91

92
```python
93
from versioningit import get_version
94

95
# Get version using default configuration
96
version = get_version()
97
print(f"Current version: {version}")
98

99
# Get version for specific project directory
100
version = get_version("/path/to/project")
101

102
# Get version and write to configured file
103
version = get_version(write=True)
104
```
105

106
### Custom Configuration
107

108
```python
109
config = {
110
    "vcs": {
111
        "method": "git",
112
        "match": ["v*.*.*"],
113
        "exclude": ["*rc*", "*dev*"]
114
    },
115
    "tag2version": {
116
        "method": "basic",
117
        "rmprefix": "v"
118
    },
119
    "next-version": {
120
        "method": "minor"
121
    },
122
    "format": {
123
        "distance": "{version}.post{distance}+{vcs}{rev}",
124
        "dirty": "{version}+d{build_date:%Y%m%d}",
125
        "distance-dirty": "{version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
126
    },
127
    "write": {
128
        "file": "src/mypackage/_version.py",
129
        "template": '__version__ = "{version}"'
130
    }
131
}
132

133
version = get_version(config=config, write=True)
134
```
135

136
### Next Version Calculation
137

138
```python
139
from versioningit import get_next_version
140

141
# Calculate next version
142
current = get_version()  # e.g., "1.2.3"
143
next_ver = get_next_version()  # e.g., "1.3.0" (depending on next-version method)
144

145
print(f"Current: {current}, Next: {next_ver}")
146
```
147

148
### Error Handling
149

150
```python
151
from versioningit import get_version, NotVCSError, NoConfigFileError
152

153
try:
154
    version = get_version(fallback=False)
155
except NotVCSError:
156
    print("Project is not under version control")
157
except NoConfigFileError:
158
    print("No pyproject.toml or versioningit.toml file found")
159
```
160

161
### Fallback Scenarios
162

163
```python
164
# With fallback enabled (default), will read from PKG-INFO if not under VCS
165
version = get_version(fallback=True)
166

167
# Disable fallback to ensure version comes from VCS
168
try:
169
    version = get_version(fallback=False)
170
except NotVCSError:
171
    print("Must be run from VCS repository")
172
```