Publishing a Python Package to PyPI

Imagine this

You sit down and begin to start on a new Python project. Soon enough you're typing in pip install [package_name], only to realize you don't have the slightest clue about how this works. You do some googling, end up finding PyPI, and celebrate that you've figured it out! But wait, how do I get my code to be pip installable? Now that is a great question.

What is PyPI?

Put simply, PyPI is where you computer looks to download a package, when you type in "pip install". Lets say you want to download the famous Pandas package so you type in pip install pandas. Your computer is going to the Pandas PyPI page and installing the necessary code to your local computer.

Now you might be thinking with a service like this, how much does it cost to have a package hosted? Fortunately, it's 100% free! This service is fully-funded from sponsors to the Python Software Foundation.

How do I set up my project?

Before we starting coding, we'll need to go over a key tool that will make publishing to PyPI a breeze. To start we'll use Poetry which is a dependency management and packaging tool. This will allow us to turn our code into packaged software as well as let "pip" know whether we'll need any other packages for our code to work.

For this, simply run pip install poetry (pretty meta right?). Now that you have Poetry installed, simply run poetry new marcos-hello-world-package (or whatever you want to name your package). Alternatively, to add Poetry configuration to an existing project you simply run poetry init from the project root.

Now we have a project! Open in up in your editor of choice (I love VSCode) and bask in the progress!

The last piece I'd recommend before coding is adding this poetry.toml file to the root of your project. It will tell Poetry to create a virtual environment in your project compared to a global one it defaults to (I find it easier to manage).

Code!

To highlight the packaging and publishing processes, we'll keep it simple and create a Hello World package. This can be done by simply adding a hello_world function to marcos_hello_world_package/__init__.py.

That's all that's needed! Any type or complexity of code is possible but this is just an example to help show how it's used later on. Now let's move on to testing the code.

Test locally

Testing is always good before deployment! Now while automated tests are important for production systems, we'll just do some user testing. Run poetry install and this will act like it's been pip installed. Test it by importing the package and executing it.

Publish to PyPI!

The time has come but before we can publish we'll have to create a PyPI account.

Finally, you'll need two commands to publish your package:

1. poetry build will package your code. You'll notice a dist/ folder is created in this process as that is where your code is compressed.
2. poetry publish -u [username] -p [password] will publish your code to PyPI. Replace the username and password with your PyPI account information and you're all set!

Summary

To recap, with only a few commands we were able to get a Python package published to PyPI. This is all due to the fantastic Poetry package. It wouldn't be this easy without it (trust me I've done it). In later articles, I hope to show how to publish to PyPI directly from a GitHub repo with GitHub Actions and Secrets!