How to Create Your First Python Package

So you want to make some open source contribution and create your own Python package? And you realized there aren’t many tutorials online after one hour of research? Comrade, you are in the right place. This tutorial guides you the exact steps to take and trust me a pip install my-own-package moment feels pretty awesome.

Folder Structure

Your code repository should have your package code and some other housekeeping files formatted nicely for distribution. Now I will walk you through what are each of the files and what to write in them.

/package_name
  setup.py
  LICENSE
  README.md
  /package_name
    __init__.py
    class.py
    requirements.txt

README.md

Things in your README.md is going to show up as the description of the package in the PyPI page so make it clear and concise. What is PyPI you may ask. PyPI (Python Package Index) is the repository for all python packages. The essence of creating a Python package is actually to make it available on the PyPI so people can pip install it.

PyPI page of tensorflow

setup.py

setup.py is the build script for setuptools. It tells setuptools about your package (such as the name and version) as well as which code files to include. [Source]

In other words, pip install actually calls setup.py to install your module. Having a setup.py file set up means your library has been packaged and ready to be distributed with Distutils, which is the standard for distributing Python Modules.

In setup.py, you can put some author information and project descriptions. But what’s most important is to change the version every time you push your package to PyPI so that it updates the release history.

import setuptools
with open("README.md", "r") as fh:
    long_description = fh.read()
setuptools.setup(
    name="dingpy",
    version="0.0.1",
    author="Tina Bu",
    author_email="tina.hongbu@gmail.com",
    description="Plays alarm when long script finishes",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/Tina-Bu/dingpy/",
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
)

Release history of Pandas

LICENSE

This part is pretty standard. Without a license people can’t legally download, distribute, or modify your code. If you want to allow other people to work on improving the package however they want, choose MIT. If you are not sure which one to choose out of the whole list, try out this license chooser.

requirements.txt

Encapsulate your package’s dependencies into a requirements.txt file so they can be installed when your package is. I like to do it with pipreqs.

pip install pipreqs
pipreqs /path/to/folder

I prefer pipreqs to the more commonly suggested pip freeze because pip freeze returns all packages that are currently installed in the environment while pipreqs generates the requirement file based only on the project imports, or in other words what is actually needed in this repo.

Test upload your package to test.pypi

# create test account at Test PyPI at 
# https://test.pypi.org/account/register/
# verify your email address
# install setuptools and wheel
python3 -m pip install --user --upgrade setuptools wheel
# run this from setup.py directory to create distribution files in a folder called dist/
python3 setup.py sdist bdist_wheel
# install twine which uploads your distribution packages
python3 -m pip install --user --upgrade twine
# upload distribution packages with twine to PyPI test
python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Test install it:

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

Generating distribution archives

# create accound at Python Package Index (PyPI) at
# https://pypi.org/account/register/
# install setuptools and wheel
python3 -m pip install --user --upgrade setuptools wheel
# run this from setup.py directory to create distribution files in a folder called dist/
python3 setup.py sdist bdist_wheel
# install twine which uploads your distribution packages
python3 -m pip install --user --upgrade twine
# upload distribution packages with twine to PyPI
python3 -m twine upload dist/*

1. Delete the `build`, `dist`, and `<package name>.egg-info` folders in your root directory.
2. Change version number in your `setup.py` file.
3. Create distribution again. e.g: `python setup.py sdist bdist_wheel`
4. Upload distribution again. e.g: `twine upload dist/*`

Install Your Package via pip

After the package is uploaded to PyPI, it can be installed via pip install package-name.

Make it Available for Anaconda?

Congratulations on reaching this point! Now your package is up and running and pip-install-able but you still won’t be able to show it off in a jupyter notebook (or do conda install) because it’s not available on the Anaconda distribution yet (only PyPI). There are quite a few steps to make that happen and I will refer you to this GitHub repo tutorial and an article by Qiusheng Wu on how to make it happen.

About the author: I am a machine learning engineer and creating technology solutions for underserved communities and industries, raising awareness, solving social, humanitarian, and environmental challenges is both a personal passion and a professional goal. When I am not coding, you can find me cooking in my kitchen or watching dog videos.