Package Versioning Helpers (bump)¶

Automated Python package version bumping

Summary¶

Included is a standalone function bump_version() - which when called, loads the file settings.VERSION_FILE , extracts the current version, bumps the requested part of the version, then replaces the version line inside of the file so that it contains the newly bumped version.

There’s also a setup.py command class BumpCommand which allows you to use bump_version() as a setup.py command, making it simple to increment your package’s version without having to manually edit the file.

If the package semver is detected, the version bumping helper bump_version() becomes available.

If the module distutils is detected, the setup.py command class BumpCommand also becomes available.

How to version your package for best compatibility¶

To avoid having to write your own version detection / replacement functions, we recommend placing your package version inside of a python module file, such as __init__.py - as the string variable VERSION

Example, mypackage/__init__.py

from mypackage.somemodule import x
from mypackage.othermodule import y

VERSION = '1.2.3'

If you cannot store your package version this way for some reason, then you can write a custom detection/replacement function and register it as the default.

See the docs for bump_version() to learn how to write a custom version detection/replacement function.

Using the BumpCommand distutils command in your setup.py¶

For BumpCommand to function, you must at least set privex.helpers.settings.VERSION_FILE to an absolute path to the file which contains your package version attribute.

If your package version isn’t defined as shown in the previous section on how to version your package, then you’ll also need to set up custom version detection/replacement functions. (see docs at bump_version())

Below is an example setup.py file, which configures the VERSION_FILE setting to point to mypackage/__init__.py relative to the folder setup.py is in, then calls setuptools.setup() with the package version and command dictionary.

from os import join, dirname, abspath
from setuptools import setup, find_packages
from privex.helpers import settings, BumpCommand
# If you placed your version in your package __init__ then you can import it for use in setup.py building
from mypackage import VERSION

# This results in an absolute path to the folder where this setup.py file is contained
BASE_DIR = dirname(abspath(__file__))

# The file which contains "VERSION = '1.2.3'"
settings.VERSION_FILE = join(BASE_DIR, 'mypackage', '__init__.py')

# Register BumpCommand as a command in your setup() function.
setup(
    version=VERSION,
    cmdclass={
        'bump': BumpCommand
    },
);

Basic usage of the bump command with setup.py¶

Once you’ve configured privex.helpers.settings.VERSION_FILE and registered the command class in the setup() function, you can now use the bump command from your setup.py and it will automatically bump your version.

Below is an example of basic usage. If you need more help on usage, type ./setup.py bump --help - or for detailed documentation on the command, see the class documentation BumpCommand

./setup.py bump --patch
# Bumping 'patch' version part
# Updating version stored in file @ /tmp/helpers/privex/helpers/__init__.py
# Package version has been bumped from 2.0.0 to 2.0.1 and written to the file
# /tmp/helpers/privex/helpers/__init__.py

./setup.py bump --minor
# ... version has been bumped from 2.0.0 to 2.1.0 and written to the file ...

Functions

`bump_version`([part, dry])	Bump semver version and replace version line inside of `settings.VERSION_FILE`
`default_current_ver`([data])	If no version retrieval function is passed to `bump_version()`, then this function will be used.
`default_replace_func`(data, old_version, …)	If no version replacement function is passed to `bump_version()`, then this function will be used.
`get_current_ver`([data])
`version_replace`(data, old_version, new_version)	Replace the version line in `data` containing `old_version` with a version line containing `new_version`