Python 201: An Intro to distutils

Last time we learned how to create modules and packages. Today we’re going to take the package we created and use Python’s distutils to create a couple different ways to distribute our code. In this tutorial, we’ll be learning the following:

How to create a setup.py file
How to create a source distribution
How to create a Windows distribution

Let’s get started!

Writing Our First “setup.py” Script

When you write your setup.py script, you need to be mindful of its location. If you put it inside your package’s folder, you’ll receive an error when you try to build a distribution. And if you put the setup.py file outside of the folder where there’s a bunch of other folders, you’ll probably end up adding a bunch of files you didn’t mean to. So to make this super easy, create a new folder and copy the “mymath” folder we created in the last article into your new folder. Then create your setup.py file in there next to your mymath folder. The folder structure should look something like this:

myNewFolder/
    mymath/
    setup.py

Note: If you don’t have the code from the last article, you can download it mymath.zip

Now we need to put some code into our new script. Let’s take a look at the following example:

from distutils.core import setup

setup(name = "mymath",
      version = "0.1",
      description = "A Simple Math Package",
      author = "Mike Driscoll",
      author_email = "mike@somedomain.com",
      url = "https://www.blog.pythonlibrary.org/2012/07/08/python-201-creating-modules-and-packages/",
      packages=["mymath"]
      )

Well, that looks pretty straight-forward. If we want to add some more packages to our setup.py file, we’d just add them to the packages list. There’s also a py_modules list that can be added for individual modules. If you go digging in the docs, you will discover that you can add non-Python files too using disutils’ Extension class. This is for including C files or similar, like what is found in 3rd party packages like lxml.

Distutils: How to Build a Source and Windows Distribution

Now that we have our setup script all defined and save, we can create a source archive file that we can use to distribute our fabulous package. Just open up a terminal (or the command line on Windows) and change directories to the new one you created. Then execute the following command:

python setup.py sdist

This should spit out something like this:

C:\Users\mdriscoll\Documents\mymath-setup>python setup.py sdist
running sdist
warning: sdist: manifest template 'MANIFEST.in' does not exist (using default fi
le list)
writing manifest file 'MANIFEST'
creating mymath-0.1
creating mymath-0.1\mymath
copying files to mymath-0.1...
copying README.txt -> mymath-0.1
copying setup.py -> mymath-0.1
copying mymath\__init__.py -> mymath-0.1\mymath
copying mymath\add.py -> mymath-0.1\mymath
copying mymath\divide.py -> mymath-0.1\mymath
copying mymath\multiply.py -> mymath-0.1\mymath
copying mymath\subtract.py -> mymath-0.1\mymath
creating dist
creating 'dist\mymath-0.1.zip' and adding 'mymath-0.1' to it
adding 'mymath-0.1\PKG-INFO'
adding 'mymath-0.1\README.txt'
adding 'mymath-0.1\setup.py'
adding 'mymath-0.1\mymath\add.py'
adding 'mymath-0.1\mymath\divide.py'
adding 'mymath-0.1\mymath\multiply.py'
adding 'mymath-0.1\mymath\subtract.py'
adding 'mymath-0.1\mymath\__init__.py'
creating 'dist\mymath-0.1.zip' and adding 'mymath-0.1' to it
adding 'mymath-0.1\PKG-INFO'
adding 'mymath-0.1\README.txt'
adding 'mymath-0.1\setup.py'
adding 'mymath-0.1\mymath\add.py'
adding 'mymath-0.1\mymath\divide.py'
adding 'mymath-0.1\mymath\multiply.py'
adding 'mymath-0.1\mymath\subtract.py'
adding 'mymath-0.1\mymath\__init__.py'
removing 'mymath-0.1' (and everything under it)

What all this means is that distutils has created a new folder named dist that now has a zip file (mymath-0.1.zip) with all your package’s files in it. If you run it on Windows, you get a zip file while on *nix, you’ll get a tarball.

Now if you wanted to create a little Windows installer exe, you can do that too. Just run this slightly different command on the command line:

python setup.py bdist_wininst

This command will create a build directory (which you can ignore) and a file named “mymath-0.1.win32.exe” in your dist folder that you can run on Windows to install your package. Speaking of installing, we should probably try that!

How to Install Your Package

In the case of the source file, you’ll need to unpack / unzip it and then call the following command from your terminal / command line window:

python setup.py install

If everything works correctly, you’ll have a new package installed to your system. To use the Windows exe, you just double-click it and you should see the following wizard appear:

Notice that it displays all that metadata we created in our setup.py script. Isn’t that cool? Anyway, if you run through the installer, it should install the package too.

NOTE: Doing the installation this way will add this package to your base Python installation. If you would rather not do that, then you could use virtualenv for your testbed.

Wrapping Up

At this point, you should be able to create and install your own package using distutils and Python. If you want to upload your package to the Python Packages Index (PyPI), then you should read their tutorial. Good luck and happy coding!