Building Python Projects With Poetry

Josh Burns, • python
Back

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.

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).

© Josh Burns.RSS