semantic_version

semantic_version is a Python implementation of the SemVer 2.0.0 specification. It provides a Version class for parsing and comparing version strings (major.minor.patch plus prerelease/build metadata) and a SimpleSpec/NpmSpec class for expressing version ranges and constraints, similar to npm’s semver range syntax.

The library is used internally by other packaging and dependency-resolution tools to compare and sort versions correctly according to the SemVer ordering rules (numeric vs. alphanumeric prerelease identifiers, build metadata exclusion from comparisons, etc.) rather than relying on naive string or tuple comparison. It also ships an optional Django model field (VersionField) for storing semantic versions directly in a database column.

What You Get

• A Version class that parses and compares version strings per the SemVer 2.0.0 ordering rules
• SimpleSpec and NpmSpec classes for expressing version constraints and ranges (e.g. >=1.2,<2.0)
• Coercion helpers (Version.coerce()) for normalizing loosely SemVer-like strings into strict versions
• An optional Django VersionField for storing and querying semantic versions in models

Common Use Cases

• Comparing and sorting package or release versions correctly, including prerelease and build metadata
• Validating that an installed dependency’s version satisfies a required version range
• Building package managers, plugin systems, or CI tooling that need SemVer-aware version matching
• Storing and querying semantic version values directly in a Django model field

Under The Hood

Architecture The library is intentionally small: base.py implements the Version class (parsing, comparison operators, and string formatting per SemVer 2.0.0) and the SimpleSpec/NpmSpec classes (parsing range expressions and testing whether a Version satisfies them), while __init__.py re-exports the public API. django_fields.py is an optional, separately-importable module adding a Django VersionField/SpecField so semantic versions can be stored and filtered as model fields without pulling Django in as a hard dependency for non-Django users.

Tech Stack Pure Python with zero runtime dependencies (the Django integration is opt-in and only imports Django when that module is used). Packaged with a plain setup.py/setup.cfg, tested via tox across multiple Python versions.

Code Quality The tests/ directory covers Version parsing edge cases (prerelease ordering, build metadata, coercion of malformed strings) and spec/range matching, run through tox. The library has been stable for years — the API and comparison semantics haven’t needed significant changes since it strictly implements a fixed external spec (SemVer 2.0.0), which explains the low recent commit activity despite continued heavy download volume.

API Design The API mirrors familiar version-handling idioms: Version('1.2.3') < Version('1.3.0') works via standard Python comparison operators, SimpleSpec('>=1.0,<2.0').match(version) reads naturally, and Version.coerce() gracefully handles version strings that aren’t strictly SemVer-compliant. This keeps integration into existing packaging/dependency code straightforward without needing a bespoke comparison DSL.