Python Packaging: Create and Distribute Packages

Introduction

This lab introduces the setup.py script, a fundamental component for packaging Python projects using the traditional Distutils library. You will learn its purpose, structure, and how to use it to make your Python modules installable. By the end of this lab, you will have created a basic setup.py file and used it to install a simple Python package.

Introduction

In this step, you will understand the role of the setup.py script as the center of all activity in building, distributing, and installing modules with Distutils.

The setup script is the core of building, distributing, and installing modules using Distutils. Its main purpose is to describe your module distribution to Distutils, so that the various commands that operate on your modules do the right thing.

The setup.py file is at the heart of a Python project. It describes all the metadata about your project. While there are many fields you can add to provide rich metadata, only three are required:

name: The name of your package. This must be unique if you wish to publish your package on the Python Package Index (PyPI).
version: The current version of your package. This helps users distinguish between different releases.
packages: A list of all Python packages to be included in your distribution.

Once you have a setup.py file, you can easily install the Python package into your environment. The recommended way is to use pip to install the package from the current directory. Run the following command in your terminal from the same directory as the setup.py file:

pip install .

This command will handle the process of building and installing the module so it can be imported and used in other Python scripts. In the next step, we will create a setup.py file and run this command.

Example

In this step, we will review a basic example of a setup.py script and create one for our project. This example will include the required fields as well as optional information like the license and a long description read from a README.txt file.

First, navigate into the project directory that has been prepared for you. Use the file explorer on the left side of the IDE to see the pythonCheatsheet directory. Inside, you'll find a pipenv sub-directory and a README.txt file.

Now, create a new file named setup.py inside the ~/project/pythonCheatsheet directory. Click the pythonCheatsheet folder in the file explorer, then click the "New File" icon and name it setup.py.

Copy and paste the following code into your newly created setup.py file:

## setup.py: define package metadata for distribution
from distutils.core import setup

setup(
   name='pythonCheatsheet',  ## Package name (must be unique on PyPI)
   version='0.1',  ## Version number
   packages=['pipenv',],  ## List of packages to include
   license='MIT',  ## License type
   long_description=open('README.txt').read(),  ## Read description from file
)

Let's break down this script:

from distutils.core import setup: This line imports the setup function, which is the main entry point for the script.
name='pythonCheatsheet': Defines the name of our package.
version='0.1': Sets the initial version.
packages=['pipenv',]: Tells Distutils that the package to be included is in the pipenv directory.
license='MIT': Specifies the license under which the package is distributed.
long_description=open('README.txt').read(): Reads the contents of README.txt to provide a detailed description for the package.

Now that the setup.py file is ready, open a terminal by clicking the + icon in the terminal panel at the bottom of the IDE. Make sure your current directory is ~/project/pythonCheatsheet. You can navigate to it by running cd ~/project/pythonCheatsheet.

Run the install command:

pip install .

You will see output in the terminal as pip builds and installs the package. The output will look something like this, ending with a confirmation that the package is installed:

Processing /home/labex/project/pythonCheatsheet
Building wheels for collected packages: pythonCheatsheet
  Building wheel for pythonCheatsheet (setup.py) ... done
  Created wheel for pythonCheatsheet: pythonCheatsheet-0.1-py3-none-any.whl
  Stored in directory: /tmp/pip-wheel-xxxxx
Successfully built pythonCheatsheet
Installing collected packages: pythonCheatsheet
Successfully installed pythonCheatsheet-0.1

To confirm the installation, you can use pip to list installed packages and filter for your new package:

pip list | grep pythonCheatsheet

You should see your package listed with its version:

pythonCheatsheet  0.1

Congratulations! You have successfully created a setup.py file and installed a Python package.

Summary

In this lab, you learned about the fundamental role of the setup.py script in Python project distribution using Distutils. You covered the essential metadata fields required for a package: name, version, and packages. Finally, you created a practical setup.py file, included additional metadata like license and long_description, and successfully installed your package into the local environment using the pip install . command. You now have the basic knowledge to make your own Python projects distributable.