0
# setuptools-scm
1

2
A comprehensive Python library that automatically extracts package versions from Git or Mercurial metadata instead of requiring manual version declarations. setuptools-scm eliminates the need to maintain version numbers in source code by reading them directly from version control system tags and commits, while also providing files to setuptools for inclusion in source distributions.
3

4
## Package Information
5

6
- **Package Name**: setuptools-scm
7
- **Language**: Python
8
- **Installation**: `pip install setuptools-scm`
9
- **Requirements**: Python 3.8+, setuptools 61+
10

11
## Core Imports
12

13
```python
14
import setuptools_scm
15
```
16

17
Standard imports for version retrieval:
18

19
```python
20
from setuptools_scm import get_version, Configuration, ScmVersion
21
```
22

23
## Basic Usage
24

25
```python
26
from setuptools_scm import get_version
27

28
# Get version from current directory
29
version = get_version()
30
print(version)  # e.g., "1.2.3" or "1.2.3.dev4+g1234567"
31

32
# Get version from specific directory
33
version = get_version(root="/path/to/repo")
34

35
# Get version with custom schemes
36
version = get_version(
37
    version_scheme="guess-next-dev",
38
    local_scheme="node-and-date"
39
)
40

41
# Configuration-based approach
42
from setuptools_scm import Configuration
43

44
config = Configuration(
45
    root=".",
46
    version_scheme="guess-next-dev",
47
    local_scheme="node-and-date",
48
    fallback_version="0.0.0"
49
)
50
version = setuptools_scm._get_version(config)
51
```
52

53
### pyproject.toml Integration
54

55
```toml
56
[build-system]
57
requires = ["setuptools>=64", "setuptools-scm>=8"]
58
build-backend = "setuptools.build_meta"
59

60
[project]
61
dynamic = ["version"]
62

63
[tool.setuptools_scm]
64
# Optional configuration
65
version_file = "src/mypackage/_version.py"
66
```
67

68
### CLI Usage
69

70
```bash
71
# Get version from current directory
72
python -m setuptools_scm
73

74
# Get version from specific directory
75
python -m setuptools_scm --root /path/to/repo
76

77
# Get version without dev suffix
78
python -m setuptools_scm --strip-dev
79
```
80

81
## Architecture
82

83
setuptools-scm uses a plugin-based architecture with three main layers:
84

85
- **Configuration Layer**: Manages settings, file paths, and version schemes
86
- **SCM Parser Layer**: Extracts version information from Git, Mercurial, or fallback sources
87
- **Version Scheme Layer**: Transforms raw SCM data into formatted version strings using configurable schemes
88
- **Integration Layer**: Provides hooks for setuptools, build systems, and file generation
89

90
The library supports customization through entry points, allowing users to define custom version schemes, local schemes, and SCM parsers while maintaining compatibility with modern Python packaging standards (PEP 518/621).
91

92
## Capabilities
93

94
### Core Version Retrieval
95

96
Primary functions for extracting and formatting version information from SCM repositories, with support for custom schemes and extensive configuration options.
97

98
```python { .api }
99
def get_version(
100
    root: PathT = ".",
101
    version_scheme: VERSION_SCHEME = "guess-next-dev",
102
    local_scheme: VERSION_SCHEME = "node-and-date",
103
    write_to: PathT | None = None,
104
    write_to_template: str | None = None,
105
    version_file: PathT | None = None,
106
    version_file_template: str | None = None,
107
    relative_to: PathT | None = None,
108
    tag_regex: str | Pattern[str] = DEFAULT_TAG_REGEX,
109
    parentdir_prefix_version: str | None = None,
110
    fallback_version: str | None = None,
111
    fallback_root: PathT = ".",
112
    parse: Any | None = None,
113
    git_describe_command: CMD_TYPE | None = None,
114
    dist_name: str | None = None,
115
    version_cls: Any | None = None,
116
    normalize: bool = True,
117
    search_parent_directories: bool = False
118
) -> str
119

120
def _get_version(
121
    config: Configuration,
122
    force_write_version_files: bool | None = None
123
) -> str | None
124

125
class Configuration:
126
    relative_to: PathT | None = None
127
    root: PathT = "."
128
    version_scheme: VERSION_SCHEME = "guess-next-dev"
129
    local_scheme: VERSION_SCHEME = "node-and-date"
130
    tag_regex: Pattern[str] = DEFAULT_TAG_REGEX
131
    parentdir_prefix_version: str | None = None
132
    fallback_version: str | None = None
133
    fallback_root: PathT = "."
134
    write_to: PathT | None = None
135
    write_to_template: str | None = None
136
    version_file: PathT | None = None
137
    version_file_template: str | None = None
138
    parse: Any | None = None
139
    git_describe_command: CMD_TYPE | None = None
140
    dist_name: str | None = None
141
    version_cls: type = Version
142
    search_parent_directories: bool = False
143
    
144
    @classmethod
145
    def from_file(
146
        cls, 
147
        name: PathT = "pyproject.toml", 
148
        dist_name: str | None = None, 
149
        **kwargs
150
    ) -> "Configuration"
151
    
152
    @classmethod
153
    def from_data(cls, relative_to: PathT, data: dict[str, Any]) -> "Configuration"
154

155
class ScmVersion:
156
    tag: Version | NonNormalizedVersion | str
157
    config: Configuration
158
    distance: int = 0
159
    node: str | None = None
160
    dirty: bool = False
161
    preformatted: bool = False
162
    branch: str | None = None
163
    node_date: date | None = None
164
    
165
    @property
166
    def exact(self) -> bool
167
    
168
    def format_with(self, fmt: str, **kw: object) -> str
169
    def format_choice(self, clean_format: str, dirty_format: str, **kw: object) -> str
170
```
171

172
[Core API](./core-api.md)
173

174
### Version Schemes and Local Schemes
175

176
Configurable strategies for transforming SCM metadata into version strings, supporting semantic versioning, calendar versioning, and custom patterns.
177

178
```python { .api }
179
# Version schemes (via entry points)
180
def guess_next_dev_version(version: ScmVersion) -> str
181
def no_guess_dev_version(version: ScmVersion) -> str  
182
def only_version(version: ScmVersion) -> str
183
def postrelease_version(version: ScmVersion) -> str
184
def simplified_semver_version(version: ScmVersion) -> str
185
def calver_by_date(version: ScmVersion) -> str
186

187
# Local schemes (via entry points)  
188
def get_local_node_and_date(version: ScmVersion) -> str
189
def get_local_node_and_timestamp(version: ScmVersion) -> str
190
def get_local_dirty_tag(version: ScmVersion) -> str
191
def get_no_local_node(version: ScmVersion) -> str
192
```
193

194
[Version and Local Schemes](./version-schemes.md)
195

196
### Command Line Interface
197

198
Complete CLI tool for version retrieval, debugging, and integration with build systems and CI/CD pipelines.
199

200
```python { .api }
201
def main(args: list[str] | None = None) -> int
202
```
203

204
Command line options include `--root`, `--config`, `--strip-dev`, `--format`, `--query`, and more.
205

206
[CLI Interface](./cli.md)
207

208
### Build System Integration
209

210
Seamless integration with setuptools, modern build systems, and packaging tools through entry points and configuration.
211

212
```python { .api }
213
def find_files(path: str = "") -> list[str]
214
def dump_version(
215
    root: str,
216
    version: str, 
217
    write_to: str,
218
    template: str | None = None,
219
    scm_version: ScmVersion | None = None
220
) -> None
221
```
222

223
Entry points for setuptools hooks, file finders, and SCM parsers enable automatic version inference and file inclusion.
224

225
[Integration](./integration.md)
226

227
## Types
228

229
```python { .api }
230
from re import Pattern
231
from datetime import date, datetime
232
from typing import Any, Callable, Sequence
233
from os import PathLike
234

235
# Type Aliases
236
PathT = PathLike[str] | str
237
CMD_TYPE = Sequence[PathT] | str
238
VERSION_SCHEME = str | Callable[["ScmVersion"], str]
239

240
class Version:
241
    """Standard packaging Version class"""
242
    
243
class NonNormalizedVersion(Version):
244
    """A non-normalizing version handler that preserves original version strings"""
245
    def __init__(self, version: str) -> None
246
    def __str__(self) -> str
247
    def __repr__(self) -> str
248

249
# Constants
250
DEFAULT_VERSION_SCHEME: str = "guess-next-dev"
251
DEFAULT_LOCAL_SCHEME: str = "node-and-date"
252
DEFAULT_TAG_REGEX: Pattern[str]  # Regex for parsing version tags
253
```