API Reference

class parver.Version(release, v=False, epoch='', pre_tag=None, pre=None, post=None, dev=None, local=None, pre_sep1=None, pre_sep2=None, post_sep1=UNSET, post_sep2=UNSET, dev_sep=UNSET, post_tag=UNSET)

Parameters:

• release (Tuple[int, ...]) – Numbers for the release segment.

• v (bool) – Optional preceding v character.

• epoch (int) – Version epoch. Implicitly zero but hidden by default.

• pre_tag (Optional[Literal['c', 'rc', 'alpha', 'a', 'beta', 'b', 'preview', 'pre']]) – Pre-release identifier, typically a, b, or rc. Required to signify a pre-release.

• pre (Optional[int]) – Pre-release number. May be '' to signify an implicit pre-release number.

• post (Optional[int]) – Post-release number. May be '' to signify an implicit post release number.

• dev (Optional[int]) – Developmental release number. May be '' to signify an implicit development release number.

• local (Optional[str]) – Local version segment.

• pre_sep1 (Optional[Literal['.', '-', '_']]) – Specify an alternate separator before the pre-release segment. The normal form is None.

• pre_sep2 (Optional[Literal['.', '-', '_']]) – Specify an alternate separator between the identifier and number. The normal form is '.'.

• post_sep1 (Optional[Literal['.', '-', '_']]) – Specify an alternate separator before the post release segment. The normal form is '.'.

• post_sep2 (Optional[Literal['.', '-', '_']]) – Specify an alternate separator between the identifier and number. The normal form is '.'.

• dev_sep (Optional[Literal['.', '-', '_']]) – Specify an alternate separator before the development release segment. The normal form is '.'.

• post_tag (Optional[Literal['post', 'rev', 'r']]) – Specify alternate post release identifier rev or r. May be None to signify an implicit post release.

Note

The attributes below are not equal to the parameters passed to the initialiser!

The main difference is that implicit numbers become 0 and set the corresponding _implicit attribute:

>>> v = Version(release=1, post='')
>>> str(v)
'1.post'
>>> v.post
0
>>> v.post_implicit
True

release

A tuple of integers giving the components of the release segment of this Version instance; that is, the 1.2.3 part of the version number, including trailing zeros but not including the epoch or any prerelease/development/postrelease suffixes

v

Whether this Version instance includes a preceding v character.

epoch

An integer giving the version epoch of this Version instance. epoch_implicit may be True if this number is zero.

pre_tag

If this Version instance represents a pre-release, this attribute will be the pre-release identifier. One of a, b, rc, c, alpha, beta, preview, or pre.

Note: you should not use this attribute to check or compare pre-release identifiers. Use is_alpha(), is_beta(), and is_release_candidate() instead.

pre

If this Version instance represents a pre-release, this attribute will be the pre-release number. If this instance is not a pre-release, the attribute will be None. pre_implicit may be True if this number is zero.

post

If this Version instance represents a postrelease, this attribute will be the postrelease number (an integer); otherwise, it will be None. post_implicit may be True if this number is zero.

dev

If this Version instance represents a development release, this attribute will be the development release number (an integer); otherwise, it will be None. dev_implicit may be True if this number is zero.

local

A string representing the local version portion of this Version instance if it has one, or None otherwise.

pre_sep1

The separator before the pre-release identifier.

pre_sep2

The seperator between the pre-release identifier and number.

post_sep1

The separator before the post release identifier.

post_sep2

The seperator between the post release identifier and number.

dev_sep

The separator before the develepment release identifier.

post_tag

If this Version instance represents a post release, this attribute will be the post release identifier. One of post, rev, r, or None to represent an implicit post release.

base_version()

Return a new Version instance for the base version of the current instance. The base version is the public version of the project without any pre or post release markers.

See also: clear() and replace().

Return type:

Version

bump_dev(*, by=1)

Return a new Version instance with the development release number bumped.

Parameters:

by (int) – How much to bump the number by.

Raises:

TypeError – by is not an integer.

Return type:

Version

>>> Version.parse('1.4').bump_dev()
<Version '1.4.dev0'>
>>> Version.parse('1.4_dev1').bump_dev()
<Version '1.4_dev2'>
>>> Version.parse('1.4.dev3').bump_dev(by=-1)
<Version '1.4.dev2'>

bump_epoch(*, by=1)

Return a new Version instance with the epoch number bumped.

Parameters:

by (int) – How much to bump the number by.

Raises:

TypeError – by is not an integer.

Return type:

Version

>>> Version.parse('1.4').bump_epoch()
<Version '1!1.4'>
>>> Version.parse('2!1.4').bump_epoch(by=-1)
<Version '1!1.4'>

bump_post(tag=UNSET, *, by=1)

Return a new Version instance with the post release number bumped.

Parameters:

• tag (str) – Post release tag. Will preserve the current tag by default, or use post if the instance is not already a post release.

• by (int) – How much to bump the number by.

Raises:

TypeError – by is not an integer.

Return type:

Version

>>> Version.parse('1.4').bump_post()
<Version '1.4.post0'>
>>> Version.parse('1.4.post0').bump_post(tag=None)
<Version '1.4-1'>
>>> Version.parse('1.4_post-1').bump_post(tag='rev')
<Version '1.4_rev-2'>
>>> Version.parse('1.4.post2').bump_post(by=-1)
<Version '1.4.post1'>

bump_pre(tag=None, *, by=1)

Return a new Version instance with the pre-release number bumped.

Parameters:

• tag (str) – Pre-release tag. Required if not already set.

• by (int) – How much to bump the number by.

Raises:

• ValueError – Trying to call bump_pre(tag=None) on a Version instance that is not already a pre-release.

• ValueError – Calling the method with a tag not equal to the current post_tag. See replace() instead.

• TypeError – by is not an integer.

Return type:

Version

>>> Version.parse('1.4').bump_pre('a')
<Version '1.4a0'>
>>> Version.parse('1.4b1').bump_pre()
<Version '1.4b2'>
>>> Version.parse('1.4b1').bump_pre(by=-1)
<Version '1.4b0'>

bump_release(*, index)

Return a new Version instance with the release number bumped at the given index.

Parameters:

index (int) – Index of the release number tuple to bump. It is not limited to the current size of the tuple. Intermediate indices will be set to zero.

Raises:

• TypeError – index is not an integer.

• ValueError – index is negative.

Return type:

Version

>>> v = Version.parse('1.4')
>>> v.bump_release(index=0)
<Version '2.0'>
>>> v.bump_release(index=1)
<Version '1.5'>
>>> v.bump_release(index=2)
<Version '1.4.1'>
>>> v.bump_release(index=3)
<Version '1.4.0.1'>

See also

For more control over the value that is bumped to, see bump_release_to().

For fine-grained control, set_release() may be used to set the value at a specific index without setting subsequenct indices to zero.

bump_release_to(*, index, value)

Return a new Version instance with the release number bumped at the given index to value. May be used for versioning schemes such as CalVer.

Parameters:

• index (int) – Index of the release number tuple to bump. It is not limited to the current size of the tuple. Intermediate indices will be set to zero.

• value (int) – Value to bump to. This may be any value, but subsequent indices will be set to zero like a normal version bump.

Raises:

• TypeError – index is not an integer.

• ValueError – index is negative.

Return type:

Version

>>> v = Version.parse('18.4')
>>> v.bump_release_to(index=0, value=20)
<Version '20.0'>
>>> v.bump_release_to(index=1, value=10)
<Version '18.10'>

For a project using CalVer with format YYYY.MM.MICRO, this method could be used to set the date parts:

>>> v = Version.parse('2018.4.1')
>>> v = v.bump_release_to(index=0, value=2018)
>>> v = v.bump_release_to(index=1, value=10)
>>> v
<Version '2018.10.0'>

See also

For typical use cases, see bump_release().

For fine-grained control, set_release() may be used to set the value at a specific index without setting subsequenct indices to zero.

property is_alpha: bool

A boolean value indicating whether this Version instance represents an alpha pre-release.

property is_beta: bool

A boolean value indicating whether this Version instance represents a beta pre-release.

property is_devrelease: bool

A boolean value indicating whether this Version instance represents a development release.

property is_postrelease: bool

A boolean value indicating whether this Version instance represents a post-release.

property is_prerelease: bool

A boolean value indicating whether this Version instance represents a pre-release and/or development release.

property is_release_candidate: bool

A boolean value indicating whether this Version instance represents a release candidate pre-release.

classmethod parse(version, strict=False)

Parameters:

• version (str) – Version number as defined in PEP 440.

• strict (bool) – Enable strict parsing of the canonical PEP 440 format.

Return type:

Version

Raises:

ParseError – If version is not valid for the given value of strict.

Parameters:

• version (str) –

• strict (bool) –

Return type:

Version

>>> Version.parse('1.dev')
<Version '1.dev'>
>>> Version.parse('1.dev', strict=True)
Traceback (most recent call last):
  ...
parver.ParseError: Expected int at position (1, 6) => '1.dev*'.

property public: str

A string representing the public version portion of this Version instance.

replace(release=UNSET, v=UNSET, epoch=UNSET, pre_tag=UNSET, pre=UNSET, post=UNSET, dev=UNSET, local=UNSET, pre_sep1=UNSET, pre_sep2=UNSET, post_sep1=UNSET, post_sep2=UNSET, dev_sep=UNSET, post_tag=UNSET)

Return a new Version instance with the same attributes, except for those given as keyword arguments. Arguments have the same meaning as they do when constructing a new Version instance manually.

Parameters:

• release (Union[int, Iterable[int], UnsetType]) –

• v (Union[bool, UnsetType]) –

• epoch (Union[Literal[''], int, ~parver._helpers.UnsetType]) –

• pre_tag (Union[Literal['c', 'rc', 'alpha', 'a', 'beta', 'b', 'preview', 'pre'], None, ~parver._helpers.UnsetType]) –

• pre (Union[Literal[''], int, None, ~parver._helpers.UnsetType]) –

• post (Union[Literal[''], int, None, ~parver._helpers.UnsetType]) –

• dev (Union[Literal[''], int, None, ~parver._helpers.UnsetType]) –

• local (Union[str, None, UnsetType]) –

• pre_sep1 (Union[Literal['.', '-', '_'], None, ~parver._helpers.UnsetType]) –

• pre_sep2 (Union[Literal['.', '-', '_'], None, ~parver._helpers.UnsetType]) –

• post_sep1 (Union[Literal['.', '-', '_'], None, ~parver._helpers.UnsetType]) –

• post_sep2 (Union[Literal['.', '-', '_'], None, ~parver._helpers.UnsetType]) –

• dev_sep (Union[Literal['.', '-', '_'], None, ~parver._helpers.UnsetType]) –

• post_tag (Union[Literal['post', 'rev', 'r'], None, ~parver._helpers.UnsetType]) –

Return type:

Version

set_release(*, index, value)

Return a new Version instance with the release number at the given index set to value.

Parameters:

• index (int) – Index of the release number tuple to set. It is not limited to the current size of the tuple. Intermediate indices will be set to zero.

• value (int) – Value to set.

Raises:

• TypeError – index is not an integer.

• ValueError – index is negative.

Return type:

Version

>>> v = Version.parse('1.2.3')
>>> v.set_release(index=0, value=3)
<Version '3.2.3'>
>>> v.set_release(index=1, value=4)
<Version '1.4.3'>

See also

For typical use cases, see bump_release().

truncate(*, min_length=1)

Return a new Version instance with trailing zeros removed from the release segment.

Parameters:

min_length (int) – Minimum number of parts to keep.

Return type:

Version

>>> Version.parse('0.1.0').truncate()
<Version '0.1'>
>>> Version.parse('1.0.0').truncate(min_length=2)
<Version '1.0'>
>>> Version.parse('1').truncate(min_length=2)
<Version '1.0'>

class parver.ParseError

Raised when parsing an invalid version number.