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
Overview
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.
Install Poetry
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
project.
Lets generate our boilerplate and get started.
$ poetry new ./helloworld
You should be greeted with a folder structure simillar to this.
Open up 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 name
, 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.
Open up 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 [package].[module]:[function]
.
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
a sdist
package and a wheel
package. Simply run the build command and you should see something like
this.
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 dist/
directory.
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).