0
# Semantic Version
1

2
A comprehensive Python library for handling Semantic Versioning (SemVer 2.0.0) that enables developers to create, manipulate, compare, and validate version numbers according to the strict semantic versioning specification. It offers robust version parsing capabilities including coercion of version-like strings, supports version bumping operations (major, minor, patch), and provides flexible version requirement specifications through SimpleSpec and NpmSpec classes for filtering and selecting versions based on ranges.
3

4
## Package Information
5

6
- **Package Name**: semantic_version
7
- **Language**: Python
8
- **Installation**: `pip install semantic-version`
9

10
## Core Imports
11

12
```python
13
import semantic_version
14
```
15

16
Common patterns:
17

18
```python
19
from semantic_version import Version, SimpleSpec, NpmSpec
20
from semantic_version import compare, match, validate
21
from semantic_version import Spec, SpecItem  # Deprecated classes
22
```
23

24
## Basic Usage
25

26
```python
27
import semantic_version
28

29
# Create and work with versions
30
version = semantic_version.Version('1.2.3-alpha.1+build.456')
31
print(version.major)       # 1
32
print(version.minor)       # 2
33
print(version.patch)       # 3
34
print(version.prerelease)  # ('alpha', '1')
35
print(version.build)       # ('build', '456')
36

37
# Compare versions
38
v1 = semantic_version.Version('1.2.3')
39
v2 = semantic_version.Version('1.2.4')
40
print(v1 < v2)  # True
41

42
# Version bumping
43
next_version = v1.next_minor()
44
print(next_version)  # Version('1.3.0')
45

46
# Validate version strings
47
print(semantic_version.validate('1.2.3'))     # True
48
print(semantic_version.validate('invalid'))   # False
49

50
# Match versions against specifications
51
spec = semantic_version.SimpleSpec('>=1.0.0,<2.0.0')
52
print(semantic_version.Version('1.5.0') in spec)  # True
53

54
# Filter versions
55
versions = [
56
    semantic_version.Version('0.9.0'),
57
    semantic_version.Version('1.2.0'),
58
    semantic_version.Version('2.1.0')
59
]
60
compatible = list(spec.filter(versions))
61
print(compatible)  # [Version('1.2.0')]
62
```
63

64
## Architecture
65

66
The semantic_version library is built around several core concepts:
67

68
- **Version Objects**: Immutable representation of semantic versions with full SemVer 2.0.0 compliance
69
- **Specification Classes**: Flexible version requirement matching with multiple syntax support
70
- **Utility Functions**: Convenient functions for common operations like comparison and validation
71
- **Django Integration**: Model fields for seamless database storage and retrieval
72

73
## Capabilities
74

75
### Core Version Operations
76

77
Fundamental version creation, manipulation, and comparison functionality. The Version class provides complete SemVer 2.0.0 support with parsing, validation, comparison, and version bumping capabilities.
78

79
```python { .api }
80
class Version:
81
    def __init__(self, version_string=None, major=None, minor=None, patch=None, prerelease=None, build=None, partial=False): ...
82
    @classmethod
83
    def parse(cls, version_string, partial=False, coerce=False): ...
84
    @classmethod 
85
    def coerce(cls, version_string, partial=False): ...
86
    def next_major(self): ...
87
    def next_minor(self): ...
88
    def next_patch(self): ...
89
    def truncate(self, level='patch'): ...
90
    @property
91
    def precedence_key(self): ...
92

93
def compare(v1: str, v2: str) -> int: ...
94
def validate(version_string: str) -> bool: ...
95
```
96

97
[Version Operations](./version-operations.md)
98

99
### Specification Matching
100

101
Version requirement specifications for filtering and selecting versions based on ranges. Supports both simple syntax and NPM-style range specifications for flexible version matching.
102

103
```python { .api }
104
class SimpleSpec:
105
    def __init__(self, expression: str): ...
106
    def match(self, version): ...
107
    def filter(self, versions): ...
108
    def select(self, versions): ...
109

110
class NpmSpec:
111
    def __init__(self, expression: str): ...
112
    def match(self, version): ...
113
    def filter(self, versions): ...
114
    def select(self, versions): ...
115

116
def match(spec: str, version: str) -> bool: ...
117
```
118

119
[Specification Matching](./specification-matching.md)
120

121
### Django Integration
122

123
Django model fields for storing Version and specification objects in databases with automatic serialization/deserialization and migration support.
124

125
```python { .api }
126
class VersionField(models.CharField):
127
    def __init__(self, partial=False, coerce=False, **kwargs): ...
128

129
class SpecField(models.CharField):
130
    def __init__(self, syntax='simple', **kwargs): ...
131
```
132

133
[Django Integration](./django-integration.md)
134

135
### Advanced Specification Architecture
136

137
Internal classes that power the specification matching system. While primarily internal, understanding these can help with advanced usage and debugging.
138

139
```python { .api }
140
class BaseSpec:
141
    @classmethod
142
    def parse(cls, expression, syntax='simple'): ...
143
    def filter(self, versions): ...
144
    def match(self, version): ...
145
    def select(self, versions): ...
146

147
# Internal specification matching classes
148
class Range:
149
    def __init__(self, operator, target, prerelease_policy='natural', build_policy='implicit'): ...
150
    def match(self, version): ...
151

152
class Always:
153
    def match(self, version): ...  # Always returns True
154

155
class Never:
156
    def match(self, version): ...  # Always returns False
157
```
158

159
These classes form the internal architecture of version matching but are generally not needed for typical usage.
160

161
### Legacy Support (Deprecated)
162

163
Legacy classes and functionality maintained for backward compatibility but deprecated and scheduled for removal in future versions.
164

165
```python { .api }
166
class Spec:  # Deprecated, use SimpleSpec
167
    def __init__(self, *expressions): ...
168

169
class SpecItem:  # Deprecated
170
    def __init__(self, requirement_string: str): ...
171
```
172

173
These legacy components are deprecated and will be removed in future versions. Use SimpleSpec and NpmSpec instead.
174

175
## Types
176

177
```python { .api }
178
# Version component types
179
# tuple of (major, minor, patch, prerelease, build)
180
# where minor/patch can be None for partial versions (deprecated)
181
# prerelease and build are tuples of strings
182

183
# Specification syntax options
184
# 'simple' or 'npm'
185

186
# Version comparison result  
187
# -1 if first < second, 0 if equal, 1 if first > second
188
```