API Reference¶

type parver.ImplicitZero = Literal['']¶: A version component that is implicitly zero and represented by "".

type parver.Separator = Literal['.', '-', '_']¶: A version separator.

type parver.NonEmptyTuple[T] = tuple[T, *tuple[T, ...]]¶: A tuple of one or more items

class parver.Version(*, v=None, epoch='', release, pre_sep1=None, pre_tag=None, pre_sep2=None, pre=None, post_sep1=UNSET, post_tag=UNSET, post_sep2=UNSET, post=None, dev_sep1=UNSET, dev_tag=None, dev_sep2=UNSET, dev=None, local=None)[source]¶

A PEP 440 version number.

Parameters:

v (Union[Literal['v', 'V'], bool, None]) – Optional preceding v character.
epoch (Union[ImplicitZero, int]) – Version epoch. Implicitly zero but hidden by default.
release (int | Iterable[int]) – Numbers for the release segment.
pre_sep1 (Optional[Separator]) – Specify an alternate separator before the pre-release segment. The normal form is None.
pre_tag (str | None) – Pre-release identifier, typically a, b, or rc. Required to signify a pre-release.
pre_sep2 (Optional[Separator]) – Specify an alternate separator between the identifier and number. The normal form is None.
pre (Union[ImplicitZero, int, None]) – Pre-release number. May be '' to signify an implicit pre-release number.
post_sep1 (Union[Separator, None, UNSET]) – Specify an alternate separator before the post release segment. The normal form is '.'.
post_tag (str | None | UNSET) – Specify alternate post release identifier rev or r. May be None to signify an implicit post release.
post_sep2 (Union[Separator, None, UNSET]) – Specify an alternate separator between the identifier and number. The normal form is None.
post (Union[ImplicitZero, int, None]) – Post-release number. May be '' to signify an implicit post release number.
dev_sep1 (Union[Separator, None, UNSET]) – Specify an alternate separator before the development release segment. The normal form is '.'.
dev_tag (str | None) – Specify the development release identifier. The normal form is dev.
dev_sep2 (Union[Separator, None, UNSET]) – Specify an alternate separator between the identifier and number. The normal form is None.
dev (Union[ImplicitZero, int, None]) – Developmental release number. May be '' to signify an implicit development release number.
local (str | None) – Local version segment.

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

v: Literal['v', 'V'] | None¶: The leading v or V prefix, or None if it has no prefix.

epoch: int¶: The version epoch. epoch_implicit may be True if this number is zero.

epoch_implicit: bool¶: Whether the epoch is omitted from the version string.

release: NonEmptyTuple[int]¶: A tuple of integers giving the components of the release segment; 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.

pre_tag: str | None¶: If this version represents a pre-release, this attribute will be the pre-release identifier. One of a, b, rc, c, alpha, beta, preview, or pre (but may not be lowercase!)

Warning

You should not use this attribute to check or compare pre-release identifiers. Use is_alpha, is_beta, and is_release_candidate instead.

pre: int | None¶: If this version 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.

pre_implicit: bool¶: Whether the pre-release number is omitted from the version string.

pre_sep1: Separator | None¶: The separator before the pre-release identifier.

pre_sep2: Separator | None¶: The separator between the pre-release identifier and number.

post_implicit: bool¶: Whether the post-release number is omitted from the version string.

post: int | None¶: If this version 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.

post_sep1: Separator | None¶: The separator before the post release identifier.

post_sep2: Separator | None¶: The separator between the post release identifier and number.

post_tag: str | None¶: If this version 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 (but may not be lowercase!).

dev_implicit: bool¶: Whether the development release number is omitted from the version string.

dev: int | None¶: If this version 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.

dev_sep1: Separator | None¶: The separator before the development release identifier.

dev_sep2: Separator | None¶: The separator between the development release identifier and number.

dev_tag: str | None¶: The development release identifier. The normal form is dev.

local: str | None¶: A string representing the local version portion of this version if it has one, or None otherwise.

classmethod parse(version, *, strict=False)[source]¶

Parse a version string.

Parameters:

version (str) – Version number as defined in PEP 440.
strict (bool) – Enable strict parsing of the canonical PEP 440 format.

Raises:

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

Return type:

Version

Example

>>> Version.parse("1.2a3")
<Version '1.2a3'>

property public: str¶: A string representing the public version portion of this Version instance (without the local segment).

property is_prerelease: bool¶: A boolean value indicating whether this Version instance represents a pre-release and/or development release.

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_release_candidate: bool¶: A boolean value indicating whether this Version instance represents a release candidate pre-release.

property is_postrelease: bool¶: A boolean value indicating whether this Version instance represents a post-release.

property is_devrelease: bool¶: A boolean value indicating whether this Version instance represents a development release.

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_sep1=UNSET, dev_sep2=UNSET, post_tag=UNSET, dev_tag=UNSET)[source]¶

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.

Return type:: Version

Example

>>> Version.parse("1.2").replace(post=1)
<Version '1.2.post1'>
>>> Version.parse("1.2").replace(pre_tag="a", pre=0)
<Version '1.2a0'>
>>> Version.parse("1-1").replace(post_tag="post")
<Version '1.post1'>

bump_epoch(*, by=1, width=None)[source]¶

Return a new Version instance with the epoch number bumped.

Parameters:

by (int) – How much to bump the number by.
width (int | None) – Minimum width for the resulting epoch number.

Raises:

TypeError – by is not an integer.

Return type:

Version

Example

>>> Version.parse("1.2").bump_epoch()
<Version '1!1.2'>
>>> Version.parse("04!1").bump_epoch()
<Version '05!1'>
>>> Version.parse("1").bump_epoch(width=2)
<Version '01!1'>

bump_release(*, index, width=None)[source]¶

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.
width (int | None) – Minimum width for the resulting release number at index.

Raises:

TypeError – index is not an integer.
ValueError – index is negative.

Return type:

Version

Example

>>> Version.parse("1.2").bump_release(index=1)
<Version '1.3'>
>>> Version.parse("1.02").bump_release(index=1)
<Version '1.03'>
>>> Version.parse("1.2").bump_release(index=1, width=2)
<Version '1.03'>

bump_release_to(*, index, value, width=None)[source]¶

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

Parameters:

index (int) – Index of the release number tuple to bump.
value (int) – Value to bump to. Subsequent indices will be set to zero.
width (int | None) – Minimum width for the resulting release number at index.

Raises:

TypeError – index is not an integer.
ValueError – index is negative.

Return type:

Version

Example

>>> Version.parse("2026.05").bump_release_to(index=1, value=6)
<Version '2026.06'>
>>> Version.parse("2026.05").bump_release_to(index=0, value=2027)
<Version '2027.00'>
>>> Version.parse("2026.12").bump_release_to(index=0, value=2027)
<Version '2027.0'>
>>> Version.parse("2027.0").bump_release_to(index=1, value=1, width=2)
<Version '2027.01'>

set_release(*, index, value, width=None)[source]¶

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.
value (int) – Value to set.
width (int | None) – Minimum width for the resulting release number at index.

Raises:

TypeError – index is not an integer.
ValueError – index is negative.

Return type:

Version

Warning

This method lets you produce a version number older than the input version. You may be looking for bump_release_to().

Example

>>> v = Version.parse("2024.01")
>>> v.set_release(index=0, value=2026).set_release(index=1, value=5)
<Version '2026.05'>
>>> Version.parse("1").set_release(index=1, value=6, width=2)
<Version '1.06'>

bump_pre(tag=None, *, by=1, width=None)[source]¶

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

Parameters:

tag (str | None) – Pre-release tag. Required if not already set.
by (int) – How much to bump the number by.
width (int | None) – Minimum width for the resulting pre-release number.

Raises:

ValueError – Trying to call bump_pre(tag=None) on a Version that is not already a pre-release.
ValueError – Calling with a tag not equal to the current pre_tag.
TypeError – by is not an integer.

Return type:

Version

Example

>>> Version.parse("1.2").bump_pre("a")
<Version '1.2a0'>
>>> Version.parse("1a04").bump_pre()
<Version '1a05'>
>>> Version.parse("1").bump_pre("b", width=2)
<Version '1b00'>

bump_post(tag=UNSET, *, by=1, width=None)[source]¶

Overloads:

self, tag (str | None), by (int), width (int | None) → Version
self, by (int), width (int | None) → Version

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

Parameters:

tag (str | None | UNSET) – 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.
width (int | None) – Minimum width for the resulting post-release number.

Raises:

TypeError – by is not an integer.

Example

>>> Version.parse("1.2").bump_post()
<Version '1.2.post0'>
>>> Version.parse("1.2").bump_post("rev")
<Version '1.2.rev0'>
>>> Version.parse("1-04").bump_post()
<Version '1-05'>
>>> Version.parse("1").bump_post(None, by=2, width=2)
<Version '1-01'>

bump_dev(tag=UNSET, *, by=1, width=None)[source]¶

Overloads:

self, tag (str), by (int), width (int | None) → Version
self, by (int), width (int | None) → Version

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

Parameters:

tag (str | UNSET) – Development release tag. Will preserve the current tag by default, or use ‘dev’ if the instance is not already a development release.
by (int) – How much to bump the number by.
width (int | None) – Minimum width for the resulting development release number.

Raises:

TypeError – by is not an integer.

Example

>>> Version.parse("1.2").bump_dev()
<Version '1.2.dev0'>
>>> Version.parse("1.2").bump_dev("DEV")
<Version '1.2.DEV0'>
>>> Version.parse("1.dev04").bump_dev()
<Version '1.dev05'>
>>> Version.parse("1").bump_dev(width=2)
<Version '1.dev00'>

normalize()[source]¶

Return a new Version instance with normalized values.

Normalizes pre-release tags, local version, and removes the v prefix.

Return type:: Version

Example

>>> Version.parse("v1.02-BETA_3+LOCAL").normalize()
<Version '1.2b3+local'>

base_version()[source]¶

Return a new Version instance for the base version.

The base version is the public version without any pre or post release markers.

Return type:: Version

Example

>>> Version.parse("1.2a3.post4.dev5+local").base_version()
<Version '1.2'>

truncate(*, min_length=1)[source]¶

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

Parameters:

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

Raises:

TypeError – min_length is not an integer.
ValueError – min_length is not positive.

Return type:

Version

Example

>>> Version.parse("1.0.0").truncate()
<Version '1'>
>>> Version.parse("1.0.1").bump_release(index=0).truncate(min_length=2)
<Version '2.0'>

class parver.ParseError[source]¶

Bases: ValueError

Raised when parsing an invalid version number.

class parver.NoLeadingNumberError(*, version=None, index=0)[source]¶

Bases: ParseError

Raised when a version or epoch segment does not start with a number.

>>> Version.parse("1!")
Traceback (most recent call last):
...
parver.NoLeadingNumberError: Expected a release number at position 2, found end of input

class parver.UnexpectedInputError(*, version, index, expected)[source]¶

Bases: ParseError

Raised when the parser finds input that is not valid at its position.

>>> Version.parse("1.")
Traceback (most recent call last):
...
parver.UnexpectedInputError: Expected a release number, a pre-release tag, a post-release tag, or 'dev' at position 2, found end of input

class parver.LocalEmptyError(*, precursor)[source]¶

Bases: ParseError

Raised when a local version marker is not followed by a segment.

>>> Version.parse("1+")
Traceback (most recent call last):
...
parver.LocalEmptyError: Expected a local version segment after '+'

class parver.StrictParseError[source]¶

Bases: ParseError

Base class for strict mode parse errors.

class parver.StrictPreTagError(*, version, index, tag)[source]¶

Bases: UnexpectedInputError, StrictParseError

Raised when strict mode rejects a non-canonical pre-release tag.

>>> Version.parse("1.2alpha1", strict=True)
Traceback (most recent call last):
...
parver.StrictPreTagError: Pre-release tag 'alpha' is not allowed in strict mode; use 'a'

class parver.StrictSegmentError(*, version, index, message)[source]¶

Bases: UnexpectedInputError, StrictParseError

Raised when strict mode rejects otherwise valid non-strict syntax.

>>> Version.parse("1.2-1", strict=True)
Traceback (most recent call last):
...
parver.StrictSegmentError: Implicit post-release shorthand '-1' is not allowed in strict mode; use '.post1'

class parver.VPrefixNotAllowedError[source]¶

Bases: StrictParseError

Raised when ‘v’ prefix is used in strict mode.

>>> Version.parse("v1", strict=True)
Traceback (most recent call last):
...
parver.VPrefixNotAllowedError: The 'v' prefix is not allowed in strict mode

class parver.LeadingZerosError(number, context=None)[source]¶

Bases: StrictParseError

Raised when a number has leading zeros in strict mode.

>>> Version.parse("1.02", strict=True)
Traceback (most recent call last):
...
parver.LeadingZerosError: Release number '02' has leading zeros in strict mode; use '2'

class parver.ImplicitNumberError(context=None, *, version=None, index=0)[source]¶

Bases: StrictParseError

Raised when an implicit number is used where strict mode requires one.

>>> Version.parse("1.2a", strict=True)
Traceback (most recent call last):
...
parver.ImplicitNumberError: Pre-release number is required in strict mode; use '0' (found end of input)

class parver.InvalidLocalError(local, reason=None, *, replacement=None)[source]¶

Bases: StrictParseError

Raised when a local version segment is invalid in strict mode.

>>> Version.parse("1+ABC", strict=True)
Traceback (most recent call last):
...
parver.InvalidLocalError: Local version segment 'ABC' is not allowed in strict mode: must be lowercase alphanumeric; use 'abc'