Overview
This post discuss using Poetry which is a powerful and easy-to-use tool for managing dependencies and packaging in Python projects. It simplifies the process of adding, removing, and updating libraries, and keeps project settings and dependencies organized using a single file, pyproject.toml.
Uses of Poetry
- Managing dependencies: Poetry automatically finds and installs the right versions of libraries, ensuring they work well together. It also removes outdated dependencies and updates them to the latest versions.
- Creating virtual environments: Poetry creates separate virtual environments for each project, preventing conflicts between libraries.
- Packaging projecs: Poetry sets up new projects with a basic structure and stores all metadata in the pyproject.toml file. It also makes it easy to publish packages to repositories like PyPI.
Sample application
To demonstrate the use of Poetry, we will do the following:
- Install Poetry
- Create a new project
- Create a virtual environment
- Add Flask dependency
- Implement a Hello World API endpoint
- Test the application
- Package the project
- Install the package
Step 1: Install Poetry
The Poetry package must be installed before we can start using it. This can be done using the following command:
pip install poetry
To check if Poetry was installed successfully, run:
python -m pip install --upgrade pip
If it is installed, the output will look something like:
Name: poetry Version: 2.1.1 Summary: Python dependency management and packaging made easy. Home-page: https://python-poetry.org/ Author: Sébastien Eustace ...
Step 2: Use Poetry to create an empty project
First create a new project folder say 'Sample' and then use Poetry's 'new' command to generate basic project skeleton.
mkdir Sample poetry new FlaskHello
This will generate a directory with the project name which is 'FlaskHello' in this case and a readme.md file.
We now have the following directory strcture:
Sample/
+- readme.md
+- FlaskHello/
+- pyproject.toml
+- README.md
+- src/
+- flaskhello/
+- __init__.py
+- tests/
- flaskhello/: Contains an __init__.py file. We can write our Flask code, modules, functions, and other related support components here.
- pyproject.toml: Contains Project details, Poetry configuration, and installed dependencies.
- README.md: Place project documentation here.
- tests: Unit tests should be stored here.
The pyproject.toml file looks like this:
[project]
name = "flaskhello"
version = "0.1.0"
description = ""
authors = [
{name = "Your Name",email = "you@example.com"}
]
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
]
[tool.poetry]
packages = [{include = "flaskhello", from = "src"}]
[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"
This file should be edited to have the correct author information.
Step 3: Create a virtual environment
Virtual environments are a great way to have project specific Python runtimes with only the packages that the project requires. It is preferable to install packages in virtual environments than install them globally. This reduces the need to deal with conflicting packages all installed in the same place.
The following Poetry command creates a virtual environment:
cd FlaskHello poetry env use python
When run on Windows, the virtual environment will be created in:
C:\Users\<username>\AppData\Local\pypoetry\Cache\virtualenvs
Use the following command to activate the virtual environment.
poetry env activate
Step 4: Adding dependencies
The 'poetry add <package>' command is used to add a package dependency to the project. Let's first add the dependency for Flask.
poetry add flask
The 'add' command updates the pyproject.toml file with the dependency for flask. If we inspect the file, we see the Flask package listed in the dependency list.
dependencies = [
"flask (>=3.1.0,<4.0.0)"
]
Similarly, add the dependency for DotEnv.
poetry add dotenv
Step 5: The Hello World API
It is time to implemment the API which returns Hello World. The impementation can be as simple as the following:
# Filename: app.py
import os
from flask import Flask
from dotenv import load_dotenv
app = Flask(__name__)
@app.route("/")
def hello():
return "Hello, World!"
if __name__ == "__main__":
load_dotenv()
app.run(port=os.environ['PORT'])
The file is saved as app.py.
Create an empty text file named .env to hold configurations. The only configuration for this application is the PORT number. Thie file needs to be saved in the same directory as the app.py file.
PORT=5000
Step 6: Test the application
The application can be run from the command line using:
poetry run python src\flaskhello\app.py
The API can be invoked as follows:
curl http://127.0.0.1:5000 Hello, World!
Now that everything is working, the next step is to package the application.
Step 7: Package the project
The 'poetry build' command is used to build a package. Though this application is not a package, let's still build it as a package.
poetry build
The package is built as .whl package. The package files are built and stored in the 'dist' folder.
26-02-2025 14:29 <DIR> .
26-02-2025 14:29 <DIR> ..
26-02-2025 14:29 1,459 flaskhello-0.1.0-py3-none-any.whl
26-02-2025 14:29 779 flaskhello-0.1.0.tar.gz
2 File(s) 2,238 bytes
2 Dir(s) 857,288,904,704 bytes free
Step 8: Install the package
The next step is to install the flaskhello package. Create a new folder named 'FlaskHelloTest' & create a new virtual environment with in & activate it.
mkdir FlaskHelloTest python -m venv venv venv\scripts\activate
Install the flaskhello package. This is done using the pip command:
pip install flaskhello-0.1.0-py3-none-any.whl
Open an interactive Python session & enter the following commands:
python >>> from flaskhello import flaskhello >>> flaskhello.hello() 'Hello, World!'
There! we have been able to install the flaskhello package and call the hello() function as if it were a reusable package.