python-semver

python-semver is a small, focused library for working with Semantic Versioning (semver.org) strings in Python. Its Version class parses a MAJOR.MINOR.PATCH[-prerelease][+build] string into its component parts, compares versions correctly, and provides chainable bump_major/bump_minor/bump_patch methods that return new, immutable Version instances.

Beyond the Python API, the package installs a pysemver command-line tool for parsing, comparing, and bumping versions from shell scripts and CI pipelines, making it useful both as an importable library and as a standalone release-automation utility.

What You Get

• An immutable Version class with parse, compare, and rich comparison operator support
• Chainable bump_major/bump_minor/bump_patch/bump_prerelease/bump_build methods
• A pysemver CLI for parsing, comparing, and bumping versions from shell scripts and CI
• Prerelease and build-metadata handling per the semver.org spec
• Backwards-compatible module-level functions for codebases migrating from the legacy tuple-based API

Common Use Cases

• Validating and comparing version strings in package managers or release tooling
• Bumping version numbers programmatically as part of a CI/CD release pipeline
• Sorting a list of releases correctly, including prerelease and build metadata ordering
• Enforcing semantic-versioning compliance in custom build or publishing scripts

Under The Hood

Architecture The library centers on a single immutable Version class in src/semver/version.py (762 lines) that owns parsing, comparison, and bump logic; _deprecated.py isolates the legacy pre-2.10 tuple/dict-based function API so old call sites keep working without polluting the modern class-based surface, and cli.py wraps Version to expose pysemver as a thin command-line front end. Tech Stack Pure Python with setuptools as the only build dependency (PEP 517 via pyproject.toml), supporting Python 3.10+, with uv.lock present for reproducible dev-dependency resolution and Sphinx-based docs under docs/. Code Quality The tests/ directory splits coverage by concern (test_bump.py, test_compare.py, test_format.py, test_immutable.py, test_deprecated_functions.py, test_docstrings.py), including a dedicated docstring-doctest check, indicating deliberate attention to both behavior and documentation accuracy. API Design The Version class favors immutability and method chaining (Version.parse(...).bump_minor().bump_patch()), mirrors Python’s native comparison operators for intuitive sorting, and keeps the deprecated function-based API available under _deprecated.py so migrations from older versions don’t break silently.