Read time: 4.9 minutes (492 words)

Step 7: Publishing on PyPi

Python packages, including the mmdesigner application we are building, usually end up being published on the Python Package Index server. Once there, interested folks can install this tool on their systems using the standard pip command.

Our next job involves adding the structure needed to publish and maintain the project on PyPi.

Setup Files

To publish a project on PyPi, a setup.py file is required. This file contains information about the project that will end up being displayed on PyPi for interested folks to examine. Here is the file for this project:

setup.py

from setuptools import setup
import io
import re
from os.path import dirname
from os.path import join

def read(*names, **kwargs):
    with io.open(
        join(dirname(__file__), *names),
        encoding=kwargs.get('encoding', 'utf8')
    ) as fh:
        return fh.read()

setup(
    name='mmdesigner',
    description='Indoor model airplane design using OpenSCAD',
    long_description=re.compile(
        '^.. start-badges.*^.. end-badges',
        re.M | re.S
    ).sub(
        '',
        read('README.rst')
    ),
    long_description_content_type='text/x-rst',
    author='Roie R. Black',
    author_email='roie.black@gmail.com',
    url='https://github.com/rblack42/math-magik',
    license='BSD',
    version='0.1.10',
    packages=['mmdesigner'],
entry_points= {
        "console_scripts": [
            "mmd = mmdesigner.cli:cli"
        ]
    },
    python_requires='>=3.7, <3.10',
    classifiers=[
        'Development Status :: 4 - Beta',
        'Intended Audience :: Developers',
        'Framework :: tox',
        'License :: OSI Approved :: BSD License',
        'Programming Language :: Python',
        'Programming Language :: Python :: 3',
        'Programming Language :: Python :: 3.7',
        'Programming Language :: Python :: 3.8',
        'Programming Language :: Python :: 3.9',
        'Programming Language :: Python :: Implementation :: CPython',
        'Programming Language :: Python :: Implementation :: PyPy',
        'Topic :: Software Development :: Testing',
    ],
)

Details on all of this can be found in the pyPi documentation.

I also added one more file which aids in creating the package uploaded to PyPi

setup.cfg

[bdist_wheel]
universal = 1

Updating Version Numbers

There is a version number in the setup.py file. Every time we create a version of the project that we want to let users access on PyPi we will need to update this number. PyPi does not let you update the version currently shown (the latest) after publishing it.

So far, the version number appears in three places in this project:

• README.rst - seen on GitHub

• mmdesigner/__version__.py - the master project version number

• setup.py - PyPi control file

Managing all three of these can be a problem, so there is a nice tool that helps keep them on track: bump2version.

Using this tool, which we can add to the requirements.txt file, involves creating a configuration file that looks like this:

.bumpversion.cfg

[bumpversion]
current_version = 0.1.10
commit = True
tag = True

[bumpversion:file:mmdesigner/__init__.py]
search = __version__ = "v{current_version}"
replace = __version__ = "v{new_version}"

[bumpversion:file:setup.py]
search = {current_version}
replace = {new_version}

[bumpversion:file:README.rst]
search = {current_version}
replace = {new_version}

Warning

The project is named bump2version, but the configuration file is just bumpversion. The original project developer abandoned the project, and a new maintainer renamed it.

With this file n place, we can increment any part of a semantic versioning number using one of the new Makefile commands provided in the Modular Make collection:

mk/version.mk

.PHONY: inc-major
inc-major:	## increment major version number
	@bump2version major

.PHONY: inc-minor
inc-minor:	## increment minor version number
	@bump2version minor

.PHONY: inc-patch
inc-patch:	## increment patch version number
	@bump2version patch

.PHONY:	version
version: ## display current version number
	@cat mmdesigner/__init__.py

Publishing the Project

Now, when the project reaches a milestone point and you want to release a new version on PyPi, we need to do a few things:

• Bump the version number as needed

• Build the package for PyPi

• Test the new version to make sure it will upload properly

• Publish the version officially

We have already covered the tools needed to bump the version number properly.

Building a Package for PyPi

To build the package for PyPi, all we need to do is run the setup.py script using Python:

$ python setup.py sdist bdist_wheel

This command will build two files n a new dist directory in the project root directory:

• mmdesigner-x.x.x-py2.py3-none-any-whl

• mmdesigner-x.x.x.tar.gz

The first file is the one that will be delivered to a user running the pip command. The second one contains the source code for the project. This is just the contents of the mmdesigner directory, not the full documentation and test code available on GitHub.

Test The Package for PyPi

PyPi has a test server that can be used to check the package before it goes public. We will use the twine tool to send this project to the test server:

$ twine upload --repository testpypi dist/* --skip-existing

This will upload the new version. If you try to upload an existing version, nothing will actually be uploaded.

Publish the Package

Finally, we use twine to publish the new version officially:

$ twine upload  dist/* --skip-existing

All of these commands are included in a Modular Make module:

mk/pypi.mk

.PHONY: build
build:	## package project for PyPi
	rm -rf build dist
	python setup.py sdist bdist_wheel
	twine check dist/*

.PHONY: pypitest
pypitest:	 build  ## upload project to pypi test server
	twine upload --repository testpypi dist/* --skip-existing

.PHONY: upload
upload:	build ## upload new version to PyPi
	twine upload dist/* --skip-existing