How to publish your Python Package to pip

Here is a step-by-step guide to follow to publish your Python package to PyPI, so anyone interested can download your package using the ‘pip install ’ command. By making it available on PyPI, you are essentially making your library open source.

This article will not focus on developing the python package, but it will be a guide to publish the package in PyPI.

If you want to read about my first Open Source Python Library - PyCalendly, check out my article I Published my first opensource python library.

Step 1: Naming your package

Naming your package is the important stuff. As of this writing, there are over 313,035 packages available in PyPI. Select a unique name for your package so potential users can find your package without any hustle.

Selecting a Package name is like selecting a domain name. Make sure it is easy to remember and unique.

Tip: You can use the search option in https://pypi.org/search/ to check if the name that you are interested in is available.

Step 2: Create package configuration files.

A Python package is expected to have a few configuration files set up before publishing it to PyPI.

your_package_root/
|--setup.py
|--README.md
|--LICENSE
|--pyproject.toml
|--package_src/
| |- __init__.py
| |- <src_files>.py
|--tests/*

README.md :

Create a README file that explains your package, functionality and link them to the proper documentation or guide to use the package. You can also include contribution guidelines and issues tracker mechanisms in the README.

Here’s a template that I found interesting that you can make use of - README Template.

LICENSE :

Since you are making your package Open Source, you need to include a License in your project. When it comes to License, there are multiple options, carefully choose one that fits your needs.

It might seem overwhelming initially understanding these different Licenses, here’s a tool that can help you zero in on a LICENSE suitable for your project - Choose a License.

setup.py :

You can use the following template for your setup.py and edit more as you proceed to advanced functionalities.

import setuptools

long_desc = open("README.md").read()
required = [<Dependent Packages>] # Comma seperated dependent libraries name

setuptools.setup(
    name="<PACKAGE_NAME>",
    version="<VERSION_NUMBER>", # eg:1.0.0
    author="<YOUR NAME>",
    author_email="<YOUR EMAIL>",
    license="<YOUR_LICENSE>",
    description="<SHORT DESCRIPTION>",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="<PACKAGE GITHUB URL>",
    packages = ['<YOUR_PACKAGE_NAME>'],
    # project_urls is optional
    project_urls={
        "Bug Tracker": "<BUG_TRACKER_URL>",
    },
    key_words="<KEY WORDS>",
    install_requires=required,
    packages=setuptools.find_packages(where="src"),
    python_requires=">=3.6",
)

pyproject.toml :

pyproject.toml informs the build tools about the requirements to build our package. Here’s a template that you can customize to your needs

[build-system]
requires = [
    "setuptools>=42",
    "wheel"
]
build-backend = "setuptools.build_meta"

tests (directory):

Create an empty tests directory for now. You can research on PyTests and how to write tests later.

Step 3: Create accounts in Test PyPI and PyPI.

Both the interfaces(Test PyPI and PyPI) look very similar but remember they are two independent platforms. As the name suggests, Test PyPI is what you use to test your package, and PyPI is where you publish it to the world.

Register on both platforms independently (You can follow the links below to set up a new account)\

• Test PyPI Registration - Create Account\
• PyPI Registration - Create Account

Step 4: Set up API tokens for both Test PyPI and PyPI.

Login to PyPI/Test PyPI, navigate to ‘Account settings’, scroll down till you can see the ‘API Tokens’ section. Create a new token.

After creating a new token, you next need to create the .pypirc file in your machine. Create a file ’.pypirc’ in the path: “$HOME/.pypirc”.

(Note: $HOME in windows is *C:/Users/<username>.* In mac,$HOME is the user folder)

Replace the and with the API tokens that you have created before.

[pypi]
username = __token__
password = <PyPI token>

[testpypi]
username = __token__
password = <TestPyPI token>

Step 5: Build distribution archives

Next, we generate distribution archives. These are the files that will be uploaded to the PyPI.

python -m pip install --upgrade build

python -m build

Once these commands run successfully, it will generate distribution archive files under the dist/ folder inside the project.

Step 6: Upload archives to Test PyPI

To upload the archives to the Package Index(PI), we will make use of the twine library.

If you haven’t installed twine yet, install using the command: python -m pip install --upgrade twine

Once twine is installed, we upload the archives by executing the following command

python -m twine upload --repository testpypi dist/*

If everything goes well and the execution is complete, you can see your package on the test.pypi.org site.

You can then test the installation and functionality by creating a new virtual environment and installing the package from Test PyPI.

Install a package from Test PyPI: python -m pip install --index-url https://test.pypi.org/simple/ your-package

Step 7(Final!): Uploading to PyPI

Uploading to PyPI is similar to Test PyPI.

execute the following command:

python -m twine upload dist/*

Once the upload is successful, you can see your package on the PyPI website. You can navigate to ‘your projects’ in PyPI and find the uploaded package there.

Now the library is available to the world. Anyone can install your library by running the following command.

pip install <your_package_name>

Bonus: Updating your package

If you make some changes, add some new features, and want to release a new version of the package, follow the steps as follows.

- Update the version number in the setup.py file

- Repeat Step5 to Step7 again. Check if the dist folder is properly generated after Step 5.

This will update the package, and the latest version can be seen by the users.

Reference:

Python.org - Packaging Projects
Python.org - .pypirc file