Skip to main content

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.

Source Distribution

semmy-1.0.0.tar.gz (5.1 kB view details)

Uploaded Source

Built Distribution

semmy-1.0.0-py3-none-any.whl (4.7 kB view details)

Uploaded Python 3

File details

Details for the file semmy-1.0.0.tar.gz.

File metadata

  • Download URL: semmy-1.0.0.tar.gz
  • Upload date:
  • Size: 5.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.12 CPython/3.9.9 Darwin/21.1.0

File hashes

Hashes for semmy-1.0.0.tar.gz
Algorithm Hash digest
SHA256 81e06e8c6b653f3219b4e1e80fab6f013b74c8349f4625d831ee4a0f2b66803a
MD5 2a9135919513a6e86b14e7fb63ba11e5
BLAKE2b-256 944aad4d12f33714786f2307e607aafcb73298bc20139aa83454516af46d8248

See more details on using hashes here.

File details

Details for the file semmy-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: semmy-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 4.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.12 CPython/3.9.9 Darwin/21.1.0

File hashes

Hashes for semmy-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 e44e4928e2bab8cf68e05528b18824d8159e613a4976c4b9899db9e04707b1f0
MD5 4a7b359f2f0e7fd0a086fedf4a04d725
BLAKE2b-256 13eec971a9124a73f8ee9001487056c74818faac2645584b17e3ea0ceb74e103

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page