Version Calculation¶
PEP 440 defines a Python Package’s version using the following grammar.
version ::= [epoch
"!"]public
["+"local
] epoch ::=digit
+ public ::=release
[pre
][post
][dev
] release ::=digit
+ ("."release
)* pre ::= "pre"digit
+ post ::= "post"digit
+ dev ::= "dev"digit
+ local ::= (letter
|digit
)+ ("."local
)*
Public Version¶
The public portion of the version identifier is managed by your package. The
best practice for managing the public version is to simply embed it within your
package as a top-level attribute named __version__
or version
. You
should use the version attribute to calculate the value passed to as the
version
keyword to setuptools.setup()
.
# setup.py
import setuptools
import mypackage
setup(
name='mypackage',
version=mypackage.__version__,
# ...
)
This extension searches for a git tag matching the public portion of the
version
keyword and uses it as the basis for constructing the post and
development release segements.
Pre Release Segment¶
This extension does not define a value for the pre-release segment.
Post Release Segment¶
This extension defines the post-release segment as the number of merges since the tag associated with your package’s version.
Development Release Segment¶
This extension defines the development release segment as the number of commits since the last merge.
Local Segment¶
This extension defines the local identifier as the first seven characters
of the most recent commit. The local identifier is only included if the
--committish
flag is included and either the post or development
segment is defined.