Let's see a simple example of distutils. We'll create a basic setup.py installation script for the palindrome module we wrote in the Chapter 11, Debugging with PDB.

The first thing we want to do is to create a directory to hold our project. Let's call this palindrome:

$ mkdir palindrome
$ cd palindrome

Let's put a copy of our palindrome.py in this directory:

"""palindrome.py - Detect palindromic integers"""

import unittest

def digits(x):
    """Convert an integer into a list of digits.

    Args:
      x: The number whose digits we want.

    Returns: A list of the digits, in order, of ``x``.

    >>> digits(4586378)
    [4, 5, 8, 6, 3, 7, 8]
    """

    digs = []
    while x != 0:
        div, mod = divmod(x, 10)
        digs.append(mod)
        x = div
    return digs

def is_palindrome(x):
    """Determine if an integer is a palindrome.

    Args:
      x: The number to check for palindromicity.

    Returns: True if the digits of ``x`` are a palindrome,
        False otherwise.

    >>> is_palindrome(1234)
    False
    >>> is_palindrome(2468642)
    True
    """
    digs = digits(x)
    for f, r in zip(digs, reversed(digs)):
        if f != r:
            return False
    return True

class Tests(unittest.TestCase):
    "Tests for the ``is_palindrome()`` function."
    def test_negative(self):
        "Check that it returns False correctly."
        self.assertFalse(is_palindrome(1234))

    def test_positive(self):
        "Check that it returns True correctly."
        self.assertTrue(is_palindrome(1234321))

    def test_single_digit(self):
        "Check that it works for single digit numbers."
        for i in range(10):
            self.assertTrue(is_palindrome(i))

if __name__ == '__main__':
    unittest.main()

And finally let's create the setup.py script:

from distutils.core import setup

setup(
    name = 'palindrome',
    version = '1.0',
    py_modules  = ['palindrome'],

    # metadata
    author = 'Austin Bingham',
    author_email = '[email protected]',
    description = 'A module for finding palindromic integers.',
    license = 'Public domain',
    keywords = 'palindrome',
    )

The first line in the file imports the functionality we need from the distutils.core module, namely the setup() function. This function does all of the work of installing our code, so we need to tell it about the code we’re installing. We do this, of course, with the arguments we pass to the function.

The first thing we tell setup() is the name of this project. We've chosen palindrome in this case, but you can choose any name you like. In general, though, it's simplest to just keep the name the same as your project name.

The next argument we pass to setup() is the version. Again, this can be any string you want. Python doesn't rely on the version to follow any rules.

The next argument, py_modules, is probably the most interesting. We use this to specify the Python modules we want to install. Each entry in this list is the name of the module without the .py extension. The setup() function will look for a matching .py file and install it. So, in our example, we've asked setup() to install palindrome.py which, of course, is a file in our project.

The rest of the arguments we're using here are fairly self-explanatory and are there mostly to help people to use your module correctly and to know who to contact if they have problems.

Before we start using our setup.py, we first need to create a virtual environment into which we'll install our module. In your palindrome directory, create a virtual environment called palindrome_env:

$ python3 -m venv palindrome_env

When this completes, activate the new environment. On Linux or macOS, source the activate script:

$ source palindrome_env/bin/activate

Or on Windows call the script directly:

> palindrome_envinactivate