Metadata-Version: 2.4
Name: semantic-versions
Version: 1.0.0
Summary: Parse, compare and match versions per the Semantic Versions specification (semver.xyz)
License-Expression: Apache-2.0
Project-URL: Homepage, https://semver.xyz/libraries/#python
Project-URL: Repository, https://github.com/vltpkg/semantic-versions
Project-URL: Specification, https://semver.xyz/spec/
Keywords: semver,semantic versioning,version,range,npm
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: bench
Requires-Dist: node-semver; extra == "bench"
Requires-Dist: semver; extra == "bench"
Dynamic: license-file

# semantic-versions

The Python implementation of [**Semantic Versions**](https://semver.xyz): parse,
validate, compare and range-match version numbers, with builds that participate
in precedence.

It is a port of the JavaScript reference implementation
([`semantic-versions`](https://www.npmjs.com/package/semantic-versions) on npm)
and behaves identically: both pass the same
[conformance suite](https://github.com/vltpkg/semantic-versions/tree/main/conformance),
and they agree on every version, range and resolution in the benchmark corpus.
Pure Python 3.10+, typed, no dependencies.

## Install

```sh
pip install semantic-versions
```

## Usage

```python
import semantic_versions as sv

v = sv.parse("1.2.3-beta.4+build.7")
assert (v.major, v.minor, v.patch, v.pre, v.build) == (1, 2, 3, "beta.4", "build.7")

# Builds participate in precedence: a build ranks above its plain release.
assert sv.parse("1.0.0") < sv.parse("1.0.0+build.1")

assert sv.satisfies("1.4.0", "^1.2.3")
assert sv.satisfies("1.0.0-rc.1", "^1.0.0-rc")      # pre-release channel
assert not sv.satisfies("1.0.0-beta", "^1.0.0-rc")  # a different channel
assert sv.satisfies("1.4.2+win.x64", "^1.0.0+win")  # build channel
assert sv.valid_range("~>1.2") == ">=1.2.0 <1.3.0-0"

# Contexts scope a version or range to an identity.
react = sv.Range("npm:react@^18")
assert sv.parse("npm:react@18.2.0") in react
assert sv.parse("pypi:react@18.2.0") not in react

assert sv.max_satisfying(["1.0.0", "1.9.0", "2.0.0"], "^1") == "1.9.0"
assert sv.sort(["2.0.0", "1.0.0+b", "1.0.0"]) == ["1.0.0", "1.0.0+b", "2.0.0"]
assert sv.valid("v1.2.3") is None  # no coercion
```

`parse` raises `InvalidVersion` and `Range()` raises `InvalidRange` (both
`ValueError`s); `valid`, `valid_range`, `satisfies` and friends return `None` or
`False` instead.

## How this differs from `node-semver` and `semver`

- **Builds participate in precedence** (`1.0.0 < 1.0.0+build`), and a build on a
  comparator is a [channel filter](https://semver.xyz/spec/#build-channels).
- **Pre-releases are range-driven**: a pre-release on a comparator is a
  [prefix channel](https://semver.xyz/spec/#pre-release-channels) scoped to its
  tuple; `X.Y.Z-*` and `*-*` opt in explicitly.
- **Contexts**: `npm:react@18.2.0`, `npm:@babel/core@^7`.
- **No coercion**: `v1.2.3` and `1.2` are errors.
- **npm-style ranges** (`>=1.2.0 <2.0.0`, `||`, `1.x`, `~`, `^`, `~>`, hyphen ranges), which python-semver does not have.

## Performance and conformance

Compared with [`node-semver`](https://pypi.org/project/node-semver/) and [`semver`](https://pypi.org/project/semver/) on real versions and dependency ranges from the npm registry. Method and raw
results: [`benchmarks/`](https://github.com/vltpkg/semantic-versions/tree/main/benchmarks).
All implementations: [semver.xyz/libraries](https://semver.xyz/libraries/).

<!-- benchmarks:start -->
<!-- Generated by benchmarks/report.mjs from benchmarks/results/. Do not edit by hand. -->

### Speed

| Operation | `semantic-versions@1.0.0` | `node-semver@0.9.1` | `semver@3.1.2` | semantic-versions vs node-semver |
| --- | ---: | ---: | ---: | --- |
| Parse a version | **920 ns** | 1.44 µs | 1.38 µs | **1.6× faster** |
| Sort versions | **657 ns** | 9.90 µs | 5.89 µs | **15× faster** |
| Parse a range | **4.30 µs** | 16.0 µs | — | **3.7× faster** |
| range.test(version) | **247 ns** | 1.76 µs | — | **7.1× faster** |
| Resolve a range | **39.9 µs** | 267.3 µs | — | **6.7× faster** |

<sub>Median time per operation (lower is better) on 5,398 published versions and 1,996 dependency ranges from the npm registry. CPython 3.13.18 · Intel(R) Xeon(R) Processor @ 2.30GHz · linux x86_64 · 2026-11-19. `semver`: python-semver has no npm-style ranges (only single comparisons such as >=1.2.3), so it is compared on versions only.</sub>

### Conformance

| Semantic Versions feature | `semantic-versions` | `node-semver` | `semver` |
| --- | :---: | :---: | :---: |
| Version grammar <br><sub>Valid and invalid versions per the BNF</sub> | ✓ 81/81 | ◐ 80/81 | ◐ 80/81 |
| No coercion <br><sub>Rejects `v1.2.3`, `=1.2.3`, `1.2.3pre`, …</sub> | ✓ 11/11 | ◐ 10/11 | ✓ 7/7 |
| Precedence <br><sub>Major, minor, patch and pre-release ordering</sub> | ✓ 32/32 | ✓ 32/32 | ✓ 32/32 |
| Build precedence <br><sub>A build ranks above its release: `1.0.0 < 1.0.0+b`</sub> | ✓ 10/10 | ◐ 1/10 | ◐ 1/10 |
| Ranges <br><sub>Comparators, `\|\|`, x-ranges, `~`, `^`, hyphen ranges</sub> | ✓ 199/199 | ◐ 174/199 | — n/a |
| Approximate ranges <br><sub>The pessimistic operator `~>`</sub> | ✓ 17/17 | ◐ 13/17 | — n/a |
| Pre-release channels <br><sub>`^1.0.0-rc` admits `rc.*`, never `beta`</sub> | ✓ 44/44 | ◐ 33/44 | — n/a |
| Pre-release wildcards <br><sub>`X.Y.Z-*` and `*-*` opt in explicitly</sub> | ✓ 14/14 | ◐ 2/14 | — n/a |
| Build channels <br><sub>`^1.0.0+win` admits `+win.*` builds only</sub> | ✓ 24/24 | ◐ 12/24 | — n/a |
| Contexts <br><sub>`npm:react@18.2.0`, `npm:react@^18`</sub> | ✓ 15/15 | ◐ 3/15 | ✗ 0/8 |
| **All cases** | **447/447** | **360/447** | **120/138** |

<sub>Cases from the shared conformance suite in [`conformance/`](https://github.com/vltpkg/semantic-versions/tree/main/conformance), drawn from the specification. ✓ all pass · ◐ some pass · ✗ none pass.</sub>

<!-- benchmarks:end -->

## Develop

```sh
python -m unittest discover -s tests       # conformance suite
pip install node-semver semver && python bench/compare.py
```

## License

Apache-2.0. The specification is at [semver.xyz](https://semver.xyz/spec/).
