Want to use any python library like Numpy and Pandas in your project? Just `pip install` it in your systems and voila! You can access all the exciting features the library is providing with a simple import line without explicitly writing down the whole code.
But ever wondered how you can access their huge codebase with a single command ` pip install <package>’?
Well, Python gives you the ultimate power to re-use their methods and modules which drastically reduces the stress of writing it down on your own.
Dedicated library for each and every task people usually do. It’s like a cook you are provided with each and every ingredient and a handbook on how to use that. P.S. We call them documentation. Now you don’t need to worry about traveling to the farm for veggies, spending hours at the market searching for the right cooking materials and whatnot. Everything is being put right in front of you and waiting to utilize as a part of the remarkable dish you are planning to cook.
In this article, I’m going to show you a detailed step-by-step procedure to create your python package from scratch and make it available at PyPI. The whole python community can access your package by just pip installing it and importing it into their source code.
Doesn’t it sound exciting?
So brace yourself! At the end of this article, you will be able to do it on your own with ease.
So what exactly are a Python Package and PyPI?
When you are working on a project you need to create several classes and functions for various features you are providing. You don’t put them all in a single file instead you create a directory and sub-directory hierarchy that has different files in them according to per the requirements. You create a separate file for each feature you are providing and you link them all together in a way that they are easy to debug and update without crashing down the whole project.
Now, in Python, this process of maintaining the hierarchical structure of modules and sub-packages and binding them together is known as Python Packaging.
Python Software Foundation (PSF) has this amazing repository of software for the Python community hosted at https://pypi.org/ which has the fabulous collection of various libraries for beginner to advanced level developers. All publically available with a single command ‘pip install <package name>`.
In this tutorial, I’ll be showing you all the necessary steps you need to know. You’ll get a better idea of creating your package or publishing an existing one.
STEP1: Creating a package
Start by creating a basic directory and sub-directory structure having some necessary files in them
The hierarchy might look like this:
This is the minimum directory structure that you should maintain in order to create a python package. Of course, you can add more files and folders whenever required for your project.
The source directory(src) will contain all the necessary files and codes related to the software/project you are creating
__init__.py is used to mark directories as Python package directories. Any directory or subdirectory having an __init__.py file is considered to be a Python package. Just for starters remember that an __init__.py should be contained in your directory and sub-directory to make the files in those directories executable as a package.
Want to know more
Visit: https://docs.python.org/3/tutorial/modules.html#packages
LICENSE.txt contains the open source license for your project. GitHub gives you the ease of creating a license file while creating a repository for your project. You can do that manually by copy-pasting the license text in your `LICENSE.txt` file.
Not sure which license to choose? Visit: https://choosealicense.com/
README.md contains all the documentation of your project. It’s always better to document your project good enough for other users as well as developers to better understand the usage, installation, and description
Setup.py is the most important file you need to create for your project to be a perfect package and be publishable at PyPI. It contains all the necessary information about your project.
This is a common setup.py structure recommended by the Official Python Community. Feel free to edit as per your project and copy-paste it into your setup.py.
Want to read more about it?
Visit: https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py
STEP2: Publishing to PyPI
Now that you have created your whole project which is ready to publish, you need to create an account at PyPI.
Go to https://pypi.org/ and register yourself
Before publishing your package, you need to create a source distribution of your project. It is basically an archive of your source code which is to be uploaded at PyPI.
Navigate to the project directory and run this command
This command will generate two files in the dist directory – a source archive, and a wheel.
Don’t forget to add these newly created folders to your .gitignore file.
You can use Twine to upload your package at PyPI Run this command to install Twine if you haven’t done it already.
To check if everything install and created successfully run this command
If it shows PASSED, then you are on the right path and ready to go!
The last step is to upload your package to PyPI. Simply, run this command:
It will ask for your PyPI credentials, so do it carefully. This command will upload everything that we created earlier in the dist folder to PyPI.
You have successfully published your project to PyPI.
Now wait for a few minutes and navigate to your PyPI account where you will see your project successfully uploaded.
STEP3: Installing and updating your package
You can now directly navigate to <project-name> to see the project dashboard.
Your project is publically available to install using the command
Try installing your own package in your virtualenv to check if everything is working as expected.
If you need to update anything, just change it in your codebase and create the source distribution again
For each new updation, you will need to upgrade your version (ex: from 0.0.1 to 0.0.2) so that PyPI understands this as an upgraded version of your project.
Then again run the command
Now upgrade your package is the virtualenv to get the updated changes in your system.
There is another portal named TestPyPI which is a separate instance of the Python Package Index that allows you to try distribution tools and processes without affecting the real index.
If you are doing it for the first time then before uploading it to PyPI, I will recommend uploading and testing it at TestPyPI. This is ensuring everything is working just fine and you are good to go.
Conclusion
I hope you understood how to create a python package and make it available for everyone. This whole process will take a few hours at first but you’ll be really cheered to see your work being a part of the Python community. By publishing a package you are helping other developers as well as users and making the python development company stronger than before. I wish you all the best for your new package and I’ll really happy to see some more cool libraries out there for our usage.
