pytoolbox.comparison module

class pytoolbox.comparison.SlotsEqualityMixin

Bases: object

Implement the comparison operators based on the slots. Both the name of the slots retrieved with pytoolbox.types.get_slots() and theirs values are tested for equality.

pytoolbox.comparison.unified_diff(before: str, after: str, *, colorize: bool = True, **kwargs) → str

Colorization is not guaranteed (your environment may disable it). Use pytoolbox.console.toggle_colors appropriately to ensure it.

pytoolbox.comparison.compare_versions(a: str, b: str, operator: str) → bool | None

pytoolbox.comparison.satisfy_version_constraints(version: str | None, constraints: tuple[str, ...], *, default='<undefined>') → bool

Ensure given version fulfill the constraints (if any).

Constraints are given in the form ‘<operator> <version>’, Exemple:

>>> satisfy_version_constraints('v1.5.2', ['>= v1.5', '< v2'])
True
>>> satisfy_version_constraints('v0.7', ['>= v1.5', '< v2'])
False
>>> satisfy_version_constraints(None, ['>= v1.5', '< v2'])
False
>>> satisfy_version_constraints('main', ['!= main'])
False
>>> satisfy_version_constraints(None, ['== <undefined>'])
True
>>> satisfy_version_constraints(None, ['!= master'], default='master')
False

class pytoolbox.comparison.Version(version: str)

Bases: packaging.version._BaseVersion

This class abstracts handling of a project’s versions.

A Version instance is comparison aware and can be compared and sorted using the standard Python interfaces.

>>> v1 = Version("1.0a5")
>>> v2 = Version("1.0")
>>> v1
<Version('1.0a5')>
>>> v2
<Version('1.0')>
>>> v1 < v2
True
>>> v1 == v2
False
>>> v1 > v2
False
>>> v1 >= v2
False
>>> v1 <= v2
True

__init__(version: str) → None

Initialize a Version object.

Parameters:version – The string representation of a version which will be parsed and normalized before use. Raises:InvalidVersion – If the version does not conform to PEP 440 in any way then this exception will be raised.

epoch

The epoch of the version.

>>> Version("2.0.0").epoch
0
>>> Version("1!2.0.0").epoch
1

release

The components of the “release” segment of the version.

>>> Version("1.2.3").release
(1, 2, 3)
>>> Version("2.0.0").release
(2, 0, 0)
>>> Version("1!2.0.0.post0").release
(2, 0, 0)

Includes trailing zeroes but not the epoch or any pre-release / development / post-release suffixes.

pre

The pre-release segment of the version.

>>> print(Version("1.2.3").pre)
None
>>> Version("1.2.3a1").pre
('a', 1)
>>> Version("1.2.3b1").pre
('b', 1)
>>> Version("1.2.3rc1").pre
('rc', 1)

post

The post-release number of the version.

>>> print(Version("1.2.3").post)
None
>>> Version("1.2.3.post1").post
1

dev

The development number of the version.

>>> print(Version("1.2.3").dev)
None
>>> Version("1.2.3.dev1").dev
1

local

The local version segment of the version.

>>> print(Version("1.2.3").local)
None
>>> Version("1.2.3+abc").local
'abc'

public

The public portion of the version.

>>> Version("1.2.3").public
'1.2.3'
>>> Version("1.2.3+abc").public
'1.2.3'
>>> Version("1.2.3+abc.dev1").public
'1.2.3'

base_version

The “base version” of the version.

>>> Version("1.2.3").base_version
'1.2.3'
>>> Version("1.2.3+abc").base_version
'1.2.3'
>>> Version("1!1.2.3+abc.dev1").base_version
'1!1.2.3'

The “base version” is the public version of the project without any pre or post release markers.

is_prerelease

Whether this version is a pre-release.

>>> Version("1.2.3").is_prerelease
False
>>> Version("1.2.3a1").is_prerelease
True
>>> Version("1.2.3b1").is_prerelease
True
>>> Version("1.2.3rc1").is_prerelease
True
>>> Version("1.2.3dev1").is_prerelease
True

is_postrelease

Whether this version is a post-release.

>>> Version("1.2.3").is_postrelease
False
>>> Version("1.2.3.post1").is_postrelease
True

is_devrelease

Whether this version is a development release.

>>> Version("1.2.3").is_devrelease
False
>>> Version("1.2.3.dev1").is_devrelease
True

major

The first item of release or 0 if unavailable.

>>> Version("1.2.3").major
1

minor

The second item of release or 0 if unavailable.

>>> Version("1.2.3").minor
2
>>> Version("1").minor
0

micro

The third item of release or 0 if unavailable.

>>> Version("1.2.3").micro
3
>>> Version("1").micro
0

pytoolbox.comparison.try_parse_version(version: str) → str | Version