Poetry is a dependency manager for Python that is also capable of building and packaging your Python projects for distribution. PyPI is the official Python repository for uploading and downloading Python packages, and will be used in this tutorial. It is the official third party source for Python packages, and is operated by the Python Software Foundation. Publishing your packages on PyPI makes it publicly available for installation by yourself, or anyone else.
In this tutorial you will create a PyPI account, set up token authentication with your account to enable use with Poetry, then build and publish your packaged project onto PyPI. This will also enable you to add your published package as a dependency to your other Python projects.
sudoprivileges and a firewall enabled.
In order to publish a package to PyPI, you will need to create an account. Go to the official registration page in your web browser:
Next you will need to enable token authentication in order to safely use your PyPI credentials with Poetry.
Token authentication is the recommended way to use your PyPI account in the command line. You can use a single, automatically generated token instead of a username and password. Tokens can be added and revoked at any time or granted granular access to parts of your account. This makes them more secure, and avoids the risk of your password being compromised. You will need to create a new API token for your account by navigating to your account settings:
Scroll down until you reach the “API tokens” section. Click on “Add API token”:
On the following page, you can name your token. This tutorial will name it
poetry, but feel free to choose whatever name you’d like:
Once your token is created, it is important to copy your token because it will only be shown once. This is common practice with API tokens that allow you to make a new one as needed, so make note of your token before proceeding.
You will now use this token to configure your credentials in Poetry to prepare for publishing. Instead of appending your API token to every command that needs it in Poetry, instead you will do it once using Poetry’s
Add your API token to Poetry with this command:
- poetry config pypi-token.pypi your-api-token
With your API token added as your credentials, Poetry will notify you that your credentials are stored in a plaintext file. This would be an issue if you were using a traditional username and password for your credentials. Given that tokens can be easily deleted and renewed, while also being randomly generated and unique to a single use case, this makes token storage here a safe trade off for convenience. Alternatively, you can opt to enter your API token manually for each command.
With this, you are ready to build and then publish your project.
Building is the same as packaging your project, and this is a required step before you can publish it. To build your project, enter the following:
OutputBuilding sammy-poetry (0.1.0) - Building sdist - Built sammy-poetry-0.1.0.tar.gz - Building wheel - Built sammy_poetry-0.1.0-py3-none-any.whl
Two files will be outputted. First is the source which is
sdist, that outputs to a
tar.gz file. Second is the compiled package, which is
wheel, that outputs to a
.whl file. With these files, you are now ready to publish your Python package to PyPI.
PyPI is the default publishing target for Poetry. With your authentication API token already in place, your publish command will not need to include your credentials again.
To publish your compiled package, enter the following:
OutputPublishing sammy-poetry (0.1.0) to PyPI - Uploading sammy-poetry-0.1.0.tar.gz 100% - Uploading sammy_poetry-0.1.0-py3-none-any.whl 100%
You can now check your published package. Open up your PyPI projects in your browser.
Your package is published, is publicly available on PyPI, and also available as a dependency through Poetry as well. You can add your own published package as a dependency in your other Python projects.
Note: You can build and publish your package to PyPI in one command by adding the following flag to your
- poetry publish --build
This can be more efficient depending on the maturity of your project and workflow.
In this tutorial, you have used Poetry for its building and publishing ability. You created a PyPI account, set up API Token authentication with Poetry, then compiled your project before publishing it. Your package is available as a dependency publicly, and can even be included as a dependency through Poetry.
Next, you may want to delve more deeply into Python by checking out our How To Code in Python tutorial series.
If you’ve enjoyed this tutorial and our broader community, consider checking out our DigitalOcean products which can also help you achieve your development goals.