API Reference¶
-
class
parver.
Version
(release, v=False, epoch=None, pre_tag=None, pre=None, post=UNSET, dev=UNSET, local=None, pre_sep1=None, pre_sep2=None, post_sep1=UNSET, post_sep2=UNSET, dev_sep=UNSET, post_tag=UNSET)[source]¶ Parameters: - release (int or 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 (str) – Pre-release identifier, typically a, b, or rc. Required to signify a pre-release.
- pre (int) – Pre-release number. May be None to signify an implicit pre-release number.
- post (int) – Post-release number. May be None to signify an implicit post release number.
- dev (int) – Developmental release number. May be None to signify an implicit development release number.
- local – Local version segment.
- pre_sep1 (str) – Specify an alternate separator before the pre-release segment. The normal form is None.
- pre_sep2 (str) – Specify an alternate separator between the identifier and
number. The normal form is
'.'
. - post_sep1 (str) – Specify an alternate separator before the post release
segment. The normal form is
'.'
. - post_sep2 (str) – Specify an alternate separator between the identifier and
number. The normal form is
'.'
. - dev_sep (str) – Specify an alternate separator before the development
release segment. The normal form is
'.'
. - post_tag (str) – 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=None) >>> 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, the1.2.3
part of the version number, including trailing zeroes but not including the epoch or any prerelease/development/postrelease suffixes
-
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()
, andis_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, orNone
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.
-
classmethod
parse
(version, strict=False)[source]¶ Parameters: Raises: ParseError – If version is not valid for the given value of strict. >>> Version.parse('1.dev') <Version '1.dev'> >>> Version.parse('1.dev', strict=True) Traceback (most recent call last): ... parver._parse.ParseError: Expected int at position (1, 6) => '1.dev*'.
-
base_version
()[source]¶ 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.
-
is_prerelease
¶ A boolean value indicating whether this
Version
instance represents a pre-release and/or development release.
-
is_release_candidate
¶ A boolean value indicating whether this
Version
instance represents a release candidate pre-release.
-
is_devrelease
¶ A boolean value indicating whether this
Version
instance represents a development release.
-
clear
(pre=False, post=False, dev=False)[source]¶ Like
replace()
, but has the ability to remove pre-release, post release, and development release segments.See also:
base_version()
.
-
replace
(**kwargs)[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 newVersion
instance manually.Warning
Be careful!
Version
treats None as an implicit zero, so pre-release, post release and development releases cannot be cleared using this method:>>> Version.parse('1.3.post0').replace(post=None) <Version '1.3.post'> >>> Version.parse('1.3').replace(post=None) <Version '1.3.post'>
Use
clear()
instead:>>> Version.parse('1.3.post0').clear(post=True) <Version '1.3'>
-
bump_release
(*, index)[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.
Raises: - TypeError – index is not an integer.
- ValueError – index is negative.
>>> 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)[source]¶ 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: Raises: - TypeError – index is not an integer.
- ValueError – index is negative.
>>> 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.
-
set_release
(*, index, value)[source]¶ Return a new
Version
instance with the release number at the given index set to value.Parameters: Raises: - TypeError – index is not an integer.
- ValueError – index is negative.
>>> 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()
.
-
bump_pre
(tag=None)[source]¶ Return a new
Version
instance with the pre-release number bumped.Parameters: tag (str) – Pre-release tag. Required if not already set.
Raises: - ValueError – Trying to call
bump_pre(tag=None)
on aVersion
instance that is not already a pre-release. - ValueError – Calling the method with a tag not equal to the
current
post_tag
. Seereplace()
instead.
>>> Version.parse('1.4').bump_pre('a') <Version '1.4a0'> >>> Version.parse('1.4b1').bump_pre() <Version '1.4b2'>
- ValueError – Trying to call
-
bump_post
(tag=UNSET)[source]¶ 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. >>> 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'>