Semantic versioning made easy for Python
Project description
🐊 Semmy
Semantic versioning made easy for Python.
Features
With semmy
you can...
- Parse semantic version domain objects from valid strings
- Check if two versions are equal
- Check if version is greater (newer) or lesser (older) than other version
- Check if version is a pre-release
- Bump (pre-)major, (pre-)minor, and (pre-)patch versions
Prerequisites
- Python >=3.8 or later
Install
poetry add semmy
Alternatively, for older projects.
pip install semmy
pip freeze > requirements.txt
Usage
Below are the most common use cases. Please, check the unit tests for complete examples.
Importing
>>> from semmy import Semver
Initializing a raw object
Plain objects are easy to initialize given three semantic version components.
>>> Semver(1, 2, 3)
Version (1.2.3)
Keyword arguments are supported, too.
>>> Semver(major=1, minor=2, patch=3)
Version (1.2.3)
Versions may contain pre-release tag and build number.
>>> Semver(1, 0, 0, pre_release="rc-1")
Version (1.0.0-rc-1)
>>> Semver(1, 0, 0, build="6c231887917e472da7f299c934b20f29")
Version (1.0.0+6c231887917e472da7f299c934b20f29)
Initializing from string
You can pass a string and have it transformed to a valid object.
>>> Semver.from_string("1.0.0")
Version (1.0.0)
Exporting as tuple
Versions can be exported as integer tuples.
>>> Semver(1, 2, 3).as_tuple()
(1, 2, 3)
Validating input
I recommend using Semver.from_string()
whenever possible as it includes a strict input validation.
For invalid inputs, instance of SemverException
is raised, which should be caught.
>>> from semmy import Semver, SemverException
>>> try:
... Semver.from_string("not-a-version")
... except SemverException as e:
... print(e)
...
Version string not-a-version is not a valid semantic version
Comparing versions
Two versions are ordered by comparing their major, minor, and patch numbers respectively.
>>> Semver.from_string("1.2.3") == Semver(1, 2, 3)
True
>>> Semver.from_string("1.1.0") > Semver(1, 0, 0)
True
>>> Semver.from_string("0.9.0") < Semver(0, 9, 1)
True
You may also want to sort a list of versions where Python's tuple ordering is helpful.
>>> versions: list[Semver] = [
... Semver(1, 2, 3),
... Semver(2, 0, 0),
... Semver(0, 1, 0),
... ]
>>>
>>> sorted(versions, key=lambda v: v.as_tuple(), reverse=True)
[Version (2.0.0), Version (1.2.3), Version (0.1.0)]
Bumping versions
Typically, you want to bump major version for breaking changes, minor version for new features, and patch version for new fixes. These are supported.
>>> Semver(0, 1, 0).bump_major()
Version (1.0.0)
>>> Semver(1, 0, 0).bump_minor()
Version (1.1.0)
>>> Semver(1, 1, 0).bump_patch()
Version (1.1.1)
Contributing
See here for instructions.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.