Installing your module via setup.py

In our code directory we specified a requirements.txt file that allowed users to easily installed the dependencies for our code. However, if someone wants to run our main script (sim_catalog) then they have to be in the code directory. If we want to run the code from some other location on our system then it won’t work. The reason is that we haven’t installed our code as a python module.

Installing a python module will do the following:

• Copy the module directory and files (eg skysim/*) to a central location so that python can access them no matter where it’s run from,
  • something like /home/${USER}/.py3/lib/python3.8/site-packages/;
• Copy and scripts (eg sim_sky) to a similar location so that they can be invoked from anywhere,
  • something like /home/${USER}/.py3/bin/;
• Make a note that the module is installed,
  • so that pip freeze will report the name/version of the software.

In order to install a python module you need a special file called setup.py.

Template for setup.py

The python documentation covers all the gory details of the how and why of using a setup.py file. However, a great place to start is to use a template so we’ll provide one here to get started.

import setuptools
import skysim

with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()

with open('requirements.txt', 'r') as fh:
    reqs = [line for line in fh.readlines() if not line.startswith('#')]

setuptools.setup(
    name="SkySim",
    version=skysim.__version__,
    author=skysim.__author__,
    author_email="author@example.com",
    description="Simulate sky locations",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/DevOne/sky_sim",
    scripts=['scripts/sim_catalog'],
    python_requires=">=3.6",
)

Note the following:

• we import the skysim module so that we can read the __version__ and __author__ information directly,
• we populate the long_description by reading the README.md file,
• we read the requirements from the requirements.txt file,
• we have set a minimum python version for this program, something that we can’t do with a requirements.txt file,
• we have moved the script sim_catalog from the root directory into the scripts/ directory.

The above notes are in keeping with the good coding practice of not repeating ourselves. All the information is stored in a single location and duplication is minimised.

Installing the module

For someone to install our software they should do one of the following:

git clone git@github.com:<gituser>/<projectname>.git
pip install .

or just download a .zip file from github, unzip it, and then run pip install . in the same directory.

The final ‘.’ indicates that pip should install the module defined in this directory. Pip will search for a setup.py file for the required information.

Uninstall the module

A user can uninstall the module from anywhere by running:

pip uninstall SkySim

Developer mode

As a developer it is annoying to have to uninstall/install your module every time you make a change and want to check that things are working. Pip has a nice solution to this which is a developer mode install. Unlike a regular install, the developer mode will not copy files to some python directory, but make symlinks instead. This means that your changes to the files will be immediately used in the installed version of the code. If you move or add files however, you’ll need to uninstall/install the code again.

A developer mode install can be done using the -e flag for pip:

pip install -e .

Upgrading

If users want to upgrade the module they have to download or pull the new version, uninstall the old one, and then install the new one. It can be a little tedious and easy to forget. Luckily there is a python package index pypi.org which pip can look to in order to find different versions of your software. It is thanks to pypi.org that pip knows how to install all the modules that we listed in our requirements.txt file. We’ll explore the python package index in the next lesson.