versions

Parsing, inspecting and specifying versions.

Installing

Python 3.8 or above is required.

pip

Installing the library with pip is quite simple:

$ pip install versions

Alternatively, the library can be installed from source:

$ git clone https://github.com/nekitdev/versions.git
$ cd versions
$ python -m pip install .

poetry

You can add versions as a dependency with the following command:

$ poetry add versions

Or by directly specifying it in the configuration like so:

[tool.poetry.dependencies]
versions = "^2.1.2"

Alternatively, you can add it directly from the source:

[tool.poetry.dependencies.versions]
git = "https://github.com/nekitdev/versions.git"

Examples

Versions

parse_version is used to parse versions:

from versions import parse_version

version = parse_version("1.0.0-dev.1+build.1")

print(version)  # 1.0.0-dev.1+build.1

Segments

All version segments can be fetched with their respective names:

>>> print(version.release)
1.0.0
>>> version.release.parts
(1, 0, 0)
>>> print(version.dev)
dev.1
>>> (version.dev.phase, version.dev.value)
("dev", 1)
>>> print(version.local)
build.1
>>> version.local.parts
("build", 1)

Comparison

Versions support total ordering:

>>> v1 = parse_version("1.0.0")
>>> v2 = parse_version("2.0.0")
>>> v1 == v2
False
>>> v1 != v2
True
>>> v1 >= v2
False
>>> v1 <= v2
True
>>> v1 > v2
False
>>> v1 < v2
True

Specification

versions also supports specifying version requirements and matching version against them.

Since versions support total ordering, they can be checked using version sets (via parse_version_set):

>>> from versions import parse_version, parse_version_set
>>> version_set = parse_version_set("^1.0.0")
>>> version_set
<VersionRange (>= 1.0.0, < 2.0.0)>
>>> version = parse_version("1.3.0")
>>> version.matches(version_set)
True
>>> another = parse_version("2.2.0")
>>> another.matches(version_set)
False

Alternatively, one can use specifiers, which are similar to version sets, except they retain the structure of specifications given (via parse_specifier):

>>> from versions import parse_specifier, parse_version
>>> specifier = parse_specifier("^1.0.0")
>>> specifier
<SpecifierOne (^1.0.0)>
>>> version = parse_version("1.3.0")
>>> version.matches(specifier)
True
>>> another = parse_version("2.2.0")
>>> another.matches(specifier)
False

Versioned

versions allows users to access versions of items that have the __version__ attribute:

>>> from versions import get_version
>>> import versions
>>> get_version(versions)
<Version (2.1.2)>

Documentation

You can find the documentation here.

Support

If you need support with the library, you can send an email or refer to the official Discord server.

Changelog

You can find the changelog here.

Security Policy

You can find the Security Policy of versions here.

Contributing

If you are interested in contributing to versions, make sure to take a look at the Contributing Guide, as well as the Code of Conduct.

License

versions is licensed under the MIT License terms. See License for details.