Poetry

So what is the point of poetry? It provides two main things:

• A dependency manager
• Set up tools to build a wheel file

Before we get into all that, we need to do some initial set up. Specifically, we need to create a virtual environment and install poetry into it. Let's knock this out.

First we create a venv:

python -m venv venv

Next, we activate the venv:

source venv/bin/activate

After that we are going to install poetry:

pip install poetry

Activating poetry shell

Let's say that for whatever reason, you closed your project and need to access the poetry shell. Here is how you will do:

source venv/bin/activate

Then you will navigate over to the newly created roadtrip directory. And activate poetry shell:

cd roadtrip
poetry shell

Making a Poetry Project

Ok, now that we got the boring part out the way, let's make a poetry project like so:

poetry new roadtrip

This will create the following file structure:

roadtrip
├── pyproject.toml
├── README.md
├── roadtrip
│   └── __init__.py
└── tests
    └── __init__.py

Adding the Code

We are going to be using the RoadTrip class that we wrote earlier as our code for this python project.

The inner roadtrip directory is the heart of the package. Let's add a module there called trip.py:

class RoadTrip:

    # a class attributes i.e. something that is true on all
    # of your road trips
    friends = 0

    # init lets you set up instance attributes
    def __init__(self):
        self.car = "Mazada"

    # our first method
    def duration(self, distance, speed):
        return (distance/speed)*60

And let's add that convenience interface to the __init__.py:

from .trip import RoadTrip

In the end our directory should look like this:

roadtrip
├── pyproject.toml
├── README.md
├── roadtrip
│   └── __init__.py
│   └── trip.py
└── tests
    └── __init__.py

Dependency Management

The main way that poetry manages dependencies is through the pyproject.toml. Here you will write everything that you need to configure the project. Let's take a look inside:

[tool.poetry]
name = "roadtrip"
version = "0.1.0"
description = ""
authors = ["Your Name <[email protected]>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.9"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

The first section has some info about the project, which I think is somewhat self evident, so I won't go into detail here.

Next we have the dependencies. In order to add to the dependencies, you can use the poetry add command. Let's add pandas:

poetry add pandas

This will update the following line to our toml:

[tool.poetry.dependencies]
python = "^3.9"
pandas = "^2.2.0"

When you use poetry add, it will automatically install the dependencies to your project. But you can also use poetry install to install them. You might do this if you just cloned this poetry project from GitHub.

Making a Wheel

In order for this to be a proper package, it has to become a wheel. It is very easy to do this. You just need to do the following in the root folder of your project:

poetry build

This will create a new folder called dist. In that folder, we will find our wheel file.

So great, we have a wheel file. How will we use it? You can install wheel files on mirrors or directly on a cluster on data bricks. You can even use it locally.

Let's create a new directory (outside of our roadtrip directory) and venv for that directory.

mkdir test
cd test
python -m venv venv 
source venv/bin/activate

Then we will install our wheel into that new venv. We need to install the wheel package first:

pip install wheel

And then our wheel file (from the test directory):

pip install <path-to-your-poetry-project>/roadtrip/dist/roadtrip-0.1.0-py3-none-any.whl