Building Python Projects With Poetry
What is Poetry
Poetry is a build tool and package manager for Python, simmilar to things like Rake, Bundler, and Cargo to name a few.
Poetry takes some of the technical overhead of developing Python apps mainly dependency
management and packaging, and condenses everything down to a
.toml file in your repo.
What Can It Do?
Poetry is a super powerful tool, here are some of the features that we will cover in this article. However, this isn't going to be a deep-dive so I encourage futher reading and research as always.
In this article we will go over doing the following things with Poetry.
- Bootstrapping a new Python project
- Adding some dependencies to the project
- Packaging the project up for release
- Building a wheel package
- Release on PyPi
The application we are building is a simple CLI script to fetch system information and metrics and display them to the user in the terminal when the session loads, simmilar to apps like Neofetch.
Before we begin we will to install the Poetry CLI tool, do this by running the following command in your terminal.
$ curl -sSL https://install.python-poetry.org | python3 -
Boostrapping The Project
Poetry includes a
new command to generate some basic file structure to get us started. The command takes
one positional argument, that being the path to put the generated boilerplate. The path given will also name the
Lets generate our boilerplate and get started.
$ poetry new ./helloworld
You should be greeted with a folder structure simillar to this.
pyproject.toml and we will fill out the metadata to ensure everything is
documented properly and we wont have any issues when we publish our package. Edit
the fields like
author and the like to suit your needs and then move on
to the next section.
Writing a Skeleton CLI Script
Create a new file in
helloworld/helloworld/console.py, In that file create an empty function
called something like
run, this will be the entrypoint for our CLI app.
# helloworld/helloworld/console.py def run(): print("Hello world")
Before we build any functionality lets make sure that our app is installable. When we build
a python package with Poetry we can define "scripts" to be installed as console commands.
To do this we need to open
pyproject.toml again and add a new section.
pyproject.toml and add the following to the bottom of the file.
[tool.poetry.scripts] helloworld = 'helloworld.console:run'
To break that down really quick. the left hand side of the
= denotes the command used to call
the function expressed on the right hand side. the notation is
Install our package to the test environment
We can now run
poetry install. This will install all our packages dependencies, and our package itself
to a virtual environment managed by Poetry in the background. Running
poetry install should give you
the following output (or something close too it).
Now we use
poetry shell to open a shell inside of our virtual environment Poetry created for us.
This is somewhat equivelent to running
source ./venv/bin/activate in a traditional virtualenv setup.
Now that we have a shell in our environment we should be able to call
helloworld and have it print out
"Hello World" to the console.
Build the Package
Now lets make sure everything compiles properly. We will use the
poetry build command to build both
sdist package and a
wheel package. Simply run the build command and you should see something like
Distribute the package via PyPi
To build our package, run
poetry build. This will create both an sdist and a wheel package. Once
you have run
poetry build you will find both the wheel package and sdist in the
We can now run
poetry publish to publish the package to PyPi. You will need to setup your PyPi credentials
so poetry can authenticate with PyPi, you can read more about that here (opens in a new tab).