razerm/parver

Parse and manipulate version numbers.

parver

parver allows parsing and manipulation of PEP 440 version numbers.

Example

>>> Version.parse('1.3').bump_dev()
<Version '1.3.dev0'>
>>> v = Version.parse('v1.2.alpha-3')
>>> v.is_alpha
True
>>> v.pre
3
>>> v
<Version 'v1.2.alpha-3'>
>>> v.normalize()
<Version '1.2a3'>

parver's Issues

bump_dev decreases the version number

Version.parse('1.2').bump_dev() returns a version equal to Version.parse('1.2.dev0'), but Version.parse('1.2.dev0') < Version.parse('1.2').

DeprecationWarning from @attr.s(cmp=False)

The following line is causing deprecation warning:

parver/src/parver/_version.py

Line 116 in b6a8526

@attr.s(frozen=True, repr=False, cmp=False)

Python39\lib\site-packages\parver\_version.py:116: DeprecationWarning: The usage of `cmp` is deprecated and will be removed on or after 2021-06-01.  Please use `eq` and `order` instead.
    @attr.s(frozen=True, repr=False, cmp=False)

Confusion on whether dev and prerelease bumps of a version are meant to be greater than the latter

In the following example for dev and prerelease bumping:

>>> from parver import Version
>>> v = Version.parse("1.1.0")
>>> v
<Version '1.1.0'>
>>> v.bump_dev()
<Version '1.1.0.dev0'>
>>> v < v.bump_dev()
False
>>> v.bump_pre("beta")
<Version '1.1.0beta0'>
>>> v < v.bump_pre("beta")
False
>>> v.is_prerelease
False

bumping dev or prelease just attaches the prerelease or dev suffix at the end of the version.

The following is just my opinion:

If any version bumping is done, the new version should be greater than the previous one.
Bumping semantically means increasing the version number.

Once a release version is created, the next version should be greater than the current version whether it is a prerelease or a development release. 1.1.0 should now be 1.1.1.dev0 for bump_dev and 1.1.1beta0 for bump_pre("beta")

The implementation also checks out:

>>> Version.parse("1.1.0") < Version.parse("1.1.1.dev0")
True

I just want to clarify if this is the desired behaviour and not all bump methods have to produce a greater version. If that is the case, I will have to find workaround for release processes in my use cases.

Allow Version.replace to clear implicit zeros

Currently, the clear method has to be used:

>>> Version.parse('1.3.post0').replace(post=None)
<Version '1.3.post'>
>>> Version.parse('1.3.post0').clear(post=True)
<Version '1.3'>

There are a few possible solutions below. They would also apply to Version's constructor

IMPLICIT constant

✅Explicit
❎Name isn't very clear. "What other parameters can I pass this to?"

>>> from parver import IMPLICIT
>>> Version.parse('1.3.post0').replace(post=None)
<Version '1.3'>
>>> Version.parse('1.3.post0').replace(post=IMPLICIT)
<Version '1.3.post'>

IMPLICIT_ZERO constant

✅Explicit
✅It's clear that this is a stand in for zero.
❎It's long, but I don't think that's much of a problem.

>>> from parver import IMPLICIT_ZERO
>>> Version.parse('1.3.post0').replace(post=None)
<Version '1.3'>
>>> Version.parse('1.3.post0').replace(post=IMPLICIT_ZERO)
<Version '1.3.post'>

String constant

✅No separate import required when using from parver import Version.
❎Magic string seems odd. "What other strings can I pass here?"

>>> Version.parse('1.3.post0').replace(post=None)
<Version '1.3'>
>>> Version.parse('1.3.post0').replace(post='implicit')
<Version '1.3.post'>

Empty string

✅No separate import required when using from parver import Version.
✅Matches the visual output.
❎Slightly less magic than a string constant, but could be confusing?

>>> Version.parse('1.3.post0').replace(post=None)
<Version '1.3'>
>>> Version.parse('1.3.post0').replace(post='')
<Version '1.3.post'>

Use False to clear.

✅No separate import required when using from parver import Version.
❎User has to be careful with None vs False.

>>> Version.parse('1.3.post0').replace(post=False)
<Version '1.3'>
>>> Version.parse('1.3.post0').replace(post=None)
<Version '1.3.post'>

---

I think I prefer IMPLICIT_ZERO constant or Empty string.

optional git support?

I have code that generates a dev version with local part like this:

0.2.0.dev170+0.1.0.gee210cc.20180614T16270

Which is “170 commits after the last release, which is 0.1.0, and the given hash (g…), and a dirty workdir modified last at the given date”. The dirty date is optional.

It is informative and automatic and unique and PEP compatible (which were my requirements).

Interested?

0.3.1: sphinx warnings

+ /usr/bin/python3 setup.py build_sphinx -b man
running build_sphinx
Running Sphinx v4.0.2
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [man]: all manpages
updating environment: [new config] 4 added, 0 changed, 0 removed
reading sources... [100%] usage
WARNING: autodoc: failed to import class 'Version' from module 'parver'; the following exception was raised:
No module named 'parver'
WARNING: autodoc: failed to import class 'ParseError' from module 'parver'; the following exception was raised:
No module named 'parver'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
writing... python-parver.3 { installation usage api } done
build succeeded, 2 warnings.