Welcome to version.py’s documentation!¶
Version: 0.2.6
Documentation: https://versionpy.readthedocs.io
Source: https://github.com/gregschmit/version.py
PyPI: https://pypi.org/project/version-py/
The Problem: I don’t like manually incrementing versions very often, and I
want a hook in my program for people to get the correct version whether they
have the git
source or if they install it from PYPI.
The Solution: If you include this script in your package and perform some
relatively minor adjustments to your setup.py
, every time you build
sdist
/bdist_wheel
, the version will be “stamped” into your distribution,
so users will know from the software itself which version they have. If your
users downloaded your software with git
, then the version.py
will
get the version from git
.
Installation¶
pip install version-py
Writing your module’s version.py
:¶
python3 -m version_py -o /path/to/repo/package
For almost all cases, this file should be one directory below your
``setup.py``. This file should be a part of your actual package, and typically
your setup.py
is one directory above your package.
Configuring git
to auto-version:¶
To start versioning at 0.1.x, just do git tag -a v0.1 -m 'version 0.1'
. Each
commit will increment the PATCH level by 1 according to this module’s
get_version()
. When you want to increment the MINOR, just do
git tag -a v0.2 -m 'version 0.2'
.
Configuring your setup.py
to use version.py
:¶
In your setup.py
you should stamp the directory so when you generate your
package sdist/bdist, the VERSION_STAMP
exists (since your sdist/bdist won’t
have the .git
directory telling the user which version they have):
from my_module_name import version
version.stamp_directory('./my_module_name')
You should also get the version from get_version
and ensure your
VERSION_STAMP
gets included in your sdists/bdists, like:
...
setup(
name='my-module-name',
version=version.get_version(),
packages=find_packages(),
include_package_data=True,
package_data={'my_module_name': ['VERSION_STAMP']},
...
)
At the end of your setup.py
you should un-stamp the directory:
...
version.unstamp_directory('./my_module_name')
Finally, source distributions don’t listen to package_data
instructions, so
you need to include the following in a MANIFEST.in
file in the same
directory as setup.py
:
include */VERSION_STAMP
Contributing¶
Email gschmi4@uic.edu if you want to contribute. You must only contribute code that you have authored or otherwise hold the copyright to, and you must make any contributions to this project available under the MIT license.
To collaborators: don’t push using the --force
option.