Packaging Python Projects using setuptools

Packaging Python Projects using setuptools : In this tutorial we will explain how to create a package of a python project using the setuptools library. We will see how to add the files and the structure that will allow us to create this package. Without further ado, let’s get to the heart of the matter! 🙂

Project name

First of all, we need to define a name for ourz python project. This project we will call it amira_data. I advise you to read the python documentation on modules and packages if you are a beginner on the subject. In the rest of the tutorial, we will use this amira_data project for all our explanations. You can directly rename it for your case if you wish ! 🙂

Create the project locally

To create the amira_data project locally, simply create the following file structure :

tutorial/ 
   amira_data/ 
      __init__.py

For the rest of the tutorial it will be necessary to be at the root of the project. The following shell command will have to be done:

cd tutorial

The __init.py__ file is required to import the directory as a package. It can be empty.

Generate the package files

We will first create files to prepare the packaging. Here is the architecture of the package :

tutorial/ 
   amira_data/ 
      __init__.py
   setup.py 
   LICENSE 
   README.md

Creation of the python setup.py file

The python setup.py file will be useful for the setuptools building script. It gives setuptools information about the package you want to create. Open the setup.py file in a text editor to edit it. I will show you an example of how to use setuptools that I will detail later.

import setuptools

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

setuptools.setup(
    name="amira-data-aa",
    version="0.1",
    author="A AMIRA",
    author_email="author@amiradata.com",
    description="example package",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/pypa/amira-data",
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.7',
)

As we can see, the setup() function can take several arguments :

• Name: Name of the distribution of the package. It must contain only letters, numbers and the characters – and _ . It must not also exist on the pypi.org website.
• Version: The version of the package. I invite you to consult the PEP 440 documentation for the choice of version numbers.
• Author: Allows to identify the author of the created package. Author_email is the author’s email address.
• Description: A patented description of the package
• long_description: A more detailed description of the package. Here we get the content of the README.md file that we will detail later in the tutorial.
• long_description_content_type: Indicates the type of markup used in the long description.
• url: Url of the package’s web home page
• packages: Lists all the packages used in this project. The find_packages() function allows us to do it directly, it avoids omissions.
• classifiers: Gives some additional metadata about our package. For a complete list of available classifiers, you can consult this link : https://pypi.org/classifiers/
• python_requires:

There are many unused options for this example package. For more details, please consult the official documentation : https://packaging.python.org/guides/distributing-packages-using-setuptools/

Creating README.md

Provides a description of what the package does :

This package allows you to understand how to create a python package

Creating LICENCE.txt

It is very important that each package created is a license. This allows future users of this package to understand the conditions under which they can use this package.

Generating distribution archives

This step consists in generating archives which are downloaded in the index package and which can be installed by pip :

We need to have the latest versions of setuptools and wheel :

python -m pip install --user --upgrade setuptools wheel

Then, execute the following command in the directory where the setup.py file is present :

python setup.py sdist bdist_wheel

This command generates two files :

dist/ 
   amira_data_aa-0.1-py3-none-any.whl            
   amira_data_aa-0.1.tar.gz

Uploading the distribution archives

The first step is to create an account on Test PyPI which is a separate instance of the package index for testing. Go to https://test.pypi.org/account/register/ and follow the steps for creating the account

The second step is to create a token to access the API. Go to: https://test.pypi.org/manage/account/#api-tokens

Once your account is created and your token is created, just execute these two shell commands :

python -m pip install --user --upgrade twine
python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

The first command installs Twine. The second command downloads all the archives to the dist folder. You will be prompted to enter your account information (username and password). For the username use __token__ and for the password use the value of the token previously created.

The amira-data-aa package should now be visible on TestPypi at this address:

https://test.pypi.org/project/amira-data-aa

You can now install your package using the pip command:

python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps amira-data-aa

And finally you can use this package in your python program like this:

import amira-data-aa

Conclusion

You now know how to create a python package thanks to setuptools. I hope you have learned a lot. Feel free to send me feedback if you have any blocking points on this subject, I would be happy to answer them! 🙂

If you want to learn more about python, you can read this book (As an Amazon Partner, I make a profit on qualifying purchases) :

Back to the Python section