Complete Guide from Developing a Python Package to Registering on PyPi

In this article will describe how to develop your own python packages, create a development environment for it, setup dependencies and finally when ready upload to pypi; so it can be installed with pip install ....

If you have experience with python, then you know pip well. And you may developed some packages for your own projects. So If you love open-source and you have used open-sources before, then the burden is on YOU! If it is a package that worth using & may solve someone else requirements, Then you should publish it for other users in github. And for better usage, register on Pypi so they can install it via pip install <package-name>.

But there are something you should know before starting to publish your python package:

• Developing a python package need an environment. for example if you are developing a Django package, then you need to setup a dev environment so that you can separately develop your python package and check if it is working perfectly on real projects.
• Your package should work well; So if anybody installed it doesn’t have to make any changes on your Project. So you should define settings and Options for users, so they just need to config your package and no need for them to change your codes.
• For pypi you should register and do some steps to make it ready for others to use it as a python package via pip installer.

Step #1. Create Structure of Python Package

In this article we consider we are building a package for Django framework. But for any other Python framework like flask, pyramid and …. it will be the same.

Each python package should include at least below files:

package-folder
├── LICENSE
├── README.md
├── example_pkg
│   └── __init__.py
├── setup.py
└── tests

The most important file to make a python package is setup.py file. It holds following information:

import setuptools

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

setuptools.setup(
    name="example-pkg",
    version="0.0.1",
    author="Reza Torkaman Ahmadi",
    author_email="reza@cpol.co",
    packages=["example_pkg"],
    description="A small example package",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/gituser/example-pkg",
    license='GPT',
    python_requires='>=3.6',
    install_requires=[
         "Django>=2.0",
    ]
)

The most important sections are mentioned with Bold Font.

• name variable describe package name which will be registered on pypi. This can be any name as long as only contains letters, numbers, _ , and -. It also must not already be taken on pypi.org. Be sure to update this with your username, as this ensures you won’t try to upload a package with the same name as one which already exists when you upload the package.
• version is the package version (follow semantic naming if you want)
• long_description about package will be picked up from reading README.md file in project root. (with text/markdown template) So please update README.md file of your project so whenever someone want to install your package from github or pypi, reads about it for better understanding.
• install_requires: this part should mention all packages that need to be installed before your package work. So whenever user try to use your package, if these packages are not installed, will automatically install it.
• author and author_email are used to identify the author of the package.
• description is a short, one-sentence summary of the package.

To update README.md file using markdown language you can follow this guide. And for licensing you can also read in this page.

Step #2. Develop Python Package

Now it is time to develop your python package in folder example_pk . Be noted that each package should contain __init__.py file. and for example if you are using a django package, you may need files like models.py, views.py, urls.py and …

For example here is a folder structure of a django package:

But how we can test if this package is working fine or not!

this is the most important question. And it getting harder to test package and make a live dev environment for it, if you are building a django app. Then you need to have a django project, manage.py and …

Actually the answer is really simple.

• Create a separate pure project. For example if you are developing a Django package, create a pure django project with command: django-admin.py startproject PROJECT command. And setup project structure to be working.
• Now install your package in new project via command:

pip install -e <example-pkg folder path here>

this command will try to install your package from folder. So just give it the folder path of your new package created. it will run setup.py and do proper tasks you defined in your own package and install it.

Now in your new project, you can use and test whether the new app is ok or not. Each time you updated your code, you just need to install it again on test project via pip install -e ... command.

Step #3. Register package on Pypi

Now that you developed your python package and you tested it and it is working fine, you need to register it on PyPi. So other users can also access it via pip package installer. For that you should follow below:

1- register on Pypi

Visit https://pypi.org/ if you are not registered yet

2- generate distribution archives

These generated files will be uploaded to pypi later, and users will install your package with them from pip. But you should have latest versions of setuptools and wheel. Just run below command to install them on your system:

pip install --user --upgrade setuptools wheel

Now that you installed them, run below command to generate archives:

python3 setup.py sdist bdist_wheel

It will generate folders build, dist, example_pkg.egg-info.

Remember to add all of this folders to your .gitignore.

3- Uploading to Pypi

To upload to pypi you need twine package installed. run below command if not installed yet:

pip install --user --upgrade twine

and run below command to upload the package with proper version defined in setup.py file.

twine upload --repository pypi dist/*

Remember you can also register on testpypi if you think your package version is not enough ready.

Step #4. Install package

Now that all steps are done, you can install this package in your projects with pip installer

pip install example-pkg

Hope this article was useful. peace :)