Registry / serialization / semantic-version

semantic-version

library2.10.0pypypi✓ verified 25d ago

This Python library provides tools to handle Semantic Versioning (SemVer) strictly following the 2.0.0 scheme. It offers classes for parsing, comparing, and manipulating version numbers and defining requirement specifications. As of version 2.10.0, it is actively maintained with a stable release cadence.

serialization

pip install semantic-version

github ↗package ↗

INSTALL

IMPORT

SIG · SEMANTIC-VERSION

semantic-version

serializationpythonv2.10.0

Install

1.6s avg

Import

115ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.10.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.120s · 17.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.110s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Version

✓ from semantic_version import Version

SimpleSpec

✓ from semantic_version import SimpleSpec

Used for simple, PyPI-inspired version range specifications.

NpmSpec

✓ from semantic_version import NpmSpec

Used for NPM-style version range specifications.

compare, match, validate

✓ from semantic_version import compare, match, validate

Module-level functions for version comparison, specification matching, and validation.

This example demonstrates how to create Version objects, access their components, perform comparisons, and use SimpleSpec to check if a version falls within a specified range.

from semantic_version import Version, SimpleSpec # Create a Version object v = Version('1.2.3-alpha+build.123') print(f"Version: {v}") print(f"Major: {v.major}, Minor: {v.minor}, Patch: {v.patch}") print(f"Prerelease: {v.prerelease}, Build: {v.build}") # Compare versions v1 = Version('1.0.0') v2 = Version('1.0.1') print(f"Is {v1} < {v2}? {v1 < v2}") # Define and use a SimpleSpec spec = SimpleSpec('>=1.0.0,<2.0.0') print(f"Does {v1} match spec '>1.0.0,<2.0.0'? {v1 in spec}") print(f"Does {v2} match spec '>1.0.0,<2.0.0'? {v2 in spec}") print(f"Does Version('2.0.0') match spec '>1.0.0,<2.0.0'? {Version('2.0.0') in spec}")

Debug

Known issues

gotchaThe library strictly adheres to Semantic Versioning 2.0.0. Attempting to parse or validate strings that do not conform to this specification will raise a `ValueError`.

fix

Ensure version strings are SemVer 2.0.0 compliant (e.g., '1.0.0', '1.2.3-alpha.1', '1.0.0+build.20230101'). Do not include a 'v' prefix.

affects: All versions

gotchaBuild metadata (the part after `+`, e.g., `+build.123`) is ignored when determining version precedence. This means `Version('1.0.0+abc') == Version('1.0.0+xyz')` is `True`. The `compare()` function may return `NotImplemented` if versions only differ by build metadata.

fix

Be aware that build metadata is purely for informational purposes and does not affect the order or equality of versions. If distinct versions are needed, ensure differences are in major, minor, patch, or pre-release components.

affects: All versions

gotchaPre-release identifiers (the part after `-`, e.g., `-alpha`) are compared lexicographically as ASCII strings, not numerically. Also, pre-release versions have lower precedence than their corresponding release version (e.g., `1.0.0-alpha < 1.0.0`).

fix

Understand that '1.0.0-alpha.1' comes before '1.0.0-alpha.2', but '1.0.0-beta' comes after '1.0.0-alpha' due to ASCII sorting. Case also matters (e.g., '1.0.0-alpha' < '1.0.0-Beta').

affects: All versions

gotchaUsing `Version(version_string, partial=True)` alters comparison behavior. If a component (minor, patch, prerelease, or build) was absent from the partial Version (represented with `None`), it is considered equal for comparison purposes. For instance, `Version('1.0', partial=True)` means 'any version beginning with 1.0'.

fix

Only use `partial=True` when intentionally desiring this flexible comparison behavior for incomplete version strings, such as matching a major.minor prefix.

affects: All versions

gotchaThe `SimpleSpec` and `NpmSpec` classes implement different version range specification schemes. `SimpleSpec` is intuitive and inspired by PyPI, while `NpmSpec` strictly follows NPM's complex rules (e.g., `~` and `^` operators have specific meanings).

fix

Choose the appropriate `Spec` class based on the desired range syntax. Familiarize yourself with the specifics of `NpmSpec` if integrating with systems that use NPM-style version ranges.

affects: All versions

breakingThe library's version range specification evaluation, particularly with `SimpleSpec` or default behavior, incorrectly evaluates strict inequality operators (`>` or `<`) at version boundaries. A version `X.Y.Z` might erroneously be considered to satisfy a spec requiring `>X.Y.Z` or `<X.Y.Z`.

fix

When defining version specifications, be aware that strict inequality operators (`>` and `<`) may not correctly exclude the boundary version. For strict exclusion, carefully test boundary conditions. If inclusive behavior is desired, explicitly use operators like `>=` or `<=`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'semantic_version'

The `semantic-version` package is not installed in the current Python environment.

fix

pip install semantic-version

ValueError: Invalid version string '1.2'

The input string provided to `semantic_version.Version()` does not strictly adhere to the Semantic Versioning 2.0.0 specification, which requires a MAJOR.MINOR.PATCH format.

fix

Ensure the version string is in the `MAJOR.MINOR.PATCH` format (e.g., '1.2.0'), or use `Version.coerce()` for more lenient parsing.

ImportError: cannot import name 'SemanticVersion' from 'semantic_version'

The main class for representing a semantic version in the `semantic-version` library is named `Version`, not `SemanticVersion`.

fix

Use `from semantic_version import Version` instead.

TypeError: '<' not supported between instances of 'Version' and 'str'

You are attempting to compare a `semantic_version.Version` object directly with a plain string, which is not directly supported by comparison operators.

fix

Convert the string to a `semantic_version.Version` object before comparison, e.g., `version_obj > Version('1.0.0')`.

ValueError: Invalid requirement string '~1.0'

The input string for `semantic_version.Requirement()` does not follow the valid syntax for a requirement specification (e.g., the tilde operator requires a patch version).

fix

Provide a valid requirement string, such as `~=1.0.0` or `>=1.0.0,<2.0.0`.

Upgrade

Version history

2.10.0latest on PyPI · released May 26, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

Resources

githubhttps://github.com/rbarrois/python-semanticversion ↗

packagehttps://pypi.org/project/semantic-version/ ↗