philiprehberger-semver 0.3.0

Parse, compare, bump, and validate semantic version strings

philiprehberger-semver

Parse, compare, bump, and validate semantic version strings.

Installation

pip install philiprehberger-semver

Usage

from philiprehberger_semver import parse, bump, compare, satisfies, is_valid, sort_versions, next_pre, latest, latest_stable

Parsing

v = parse("1.2.3-beta.1+build.42")
v.major  # 1
v.minor  # 2
v.patch  # 3
v.pre    # "beta.1"
v.build  # "build.42"
str(v)   # "1.2.3-beta.1+build.42"

A leading v prefix is accepted:

parse("v2.0.0")  # Version(major=2, minor=0, patch=0)

Bumping

bump("1.2.3", "major")  # "2.0.0"
bump("1.2.3", "minor")  # "1.3.0"
bump("1.2.3", "patch")  # "1.2.4"

Comparing

compare("1.2.3", "1.3.0")  # -1
compare("2.0.0", "2.0.0")  #  0
compare("3.0.0", "2.9.9")  #  1

Range matching

satisfies("1.5.0", ">=1.0.0 <2.0.0")  # True
satisfies("1.2.5", "^1.2.3")           # True  (>=1.2.3 <2.0.0)
satisfies("1.2.5", "~1.2.3")           # True  (>=1.2.3 <1.3.0)
satisfies("1.3.0", "~1.2.3")           # False

Validation

is_valid("1.2.3")        # True
is_valid("not-a-version") # False

Sorting

sort_versions(["2.0.0", "1.0.0", "1.1.0"])  # ["1.0.0", "1.1.0", "2.0.0"]

Range expansion

Get the lower (inclusive) and upper (exclusive) bounds of a range:

from philiprehberger_semver import expand_range

expand_range("^1.2.3")      # (Version(1,2,3), Version(2,0,0))
expand_range("~1.2.3")      # (Version(1,2,3), Version(1,3,0))
expand_range(">=1.0.0")     # (Version(1,0,0), None)
expand_range(">=1 <2")      # (Version(1,0,0), Version(2,0,0))

Pre-release generation

next_pre("1.2.3")         # "1.2.4-rc.1"
next_pre("1.2.4-rc.1")    # "1.2.4-rc.2"
next_pre("1.2.3", "beta") # "1.2.4-beta.1"

Finding the latest version

from philiprehberger_semver import latest, latest_stable

latest(["1.0.0", "2.0.0", "1.5.0"])               # Version(2, 0, 0)
latest([])                                         # None

latest_stable(["1.0.0", "2.0.0-rc1", "1.5.0"])    # Version(1, 5, 0)
latest_stable(["2.0.0-rc1", "2.0.0-rc2"])         # None

API

Function	Description
parse(version)	Parse a semver string into a Version object
bump(version, part)	Bump major, minor, or patch and return the new version string
compare(a, b)	Compare two version strings, returns -1, 0, or 1
satisfies(version, range_str)	Check if a version satisfies a range (>=, <, ^, ~)
is_valid(version)	Check if a string is valid semver
sort_versions(versions)	Sort a list of version strings in ascending order
next_pre(version, prefix)	Generate the next pre-release version string
expand_range(range_str)	Return (lower_inclusive, upper_exclusive) bounds of a range
latest(versions)	Return the highest Version from an iterable, or None if empty
latest_stable(versions)	Return the highest non-prerelease Version, or None if none exist

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT