poetry

poetry Best Practices

Poetry is the de-facto standard for modern Python project management. This guide outlines our team's definitive best practices for leveraging Poetry's full power, ensuring reproducible builds, streamlined development, and robust packaging.

1. Project Initialization & Structure

Always start new projects with poetry new to establish a correct pyproject.toml and project structure.

✅ GOOD: Use src layout by default

Poetry 2.1+ defaults to the src layout, which prevents common import issues and improves package isolation.

# Initialize a new project with the recommended src layout
poetry new my-project

This creates:

my-project/
├── pyproject.toml
├── README.md
├── my_project/  # Your package source code lives here
│   └── __init__.py
└── tests/
    └── __init__.py
    └── test_my_project.py

2. pyproject.toml Configuration

pyproject.toml is your project's single source of truth.

✅ GOOD: Prioritize PEP 621 [project] section

Poetry 2.0+ fully supports PEP 621. Use the [project] section for standard metadata (name, version, description, authors, etc.). Only use [tool.poetry] for Poetry-specific features not covered by PEP 621.

❌ BAD: Using deprecated tool.poetry fields

# pyproject.toml
[tool.poetry]
name = "my-project" # Deprecated in favor of [project].name
version = "0.1.0"   # Deprecated in favor of [project].version
description = "A bad example"
authors = ["Bad Developer <[email protected]>"]

✅ GOOD: Using [project] for standard metadata

# pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
description = "A good example using PEP 621"
authors = [{name = "Good Developer", email = "[email protected]"}]
readme = "README.md"
requires-python = ">=3.9,<4.0" # Always specify Python version
license = { text = "MIT" }     # Or { file = "LICENSE" }
keywords = ["python", "poetry", "best-practices"]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[tool.poetry]
# Only Poetry-specific configurations here, e.g., packages, scripts
packages = [{ include = "my_project" }] # Required for src layout