Poetry

Poetry Tutorial: A Modern Python Dependency Management Tool

Table of Contents

1. Introduction to Poetry
   Installation
   Basic Usage
   Key Commands
   Comparison with pip
Conclusion

---

1. Introduction to Poetry

Poetry is a modern tool for dependency management and packaging in Python. It simplifies the process of managing project dependencies, creating virtual environments, and building/publishing Python packages. Poetry uses a pyproject.toml file to manage project metadata and dependencies, replacing the traditional requirements.txt and setup.py files.

Key Features:

• Dependency resolution and locking.

• Virtual environment management.

• Easy project scaffolding.

• Publishing packages to PyPI.

• Support for pyproject.toml (PEP 517 and PEP 518).

---

2. Installation

To install Poetry, run the following command:

bash

Copy

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -

After installation, add Poetry to your system's PATH (if not done automatically):

bash

Copy

# Add Poetry to PATH (Linux/macOS)
export PATH="$HOME/.local/bin:$PATH"

# Verify installation
poetry --version

For Windows, use the PowerShell command:

powershell

Copy

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

---

3. Basic Usage

Creating a New Project

To create a new Poetry project, use the new command:

bash

Copy

poetry new my_project

This creates a directory structure like this:

Copy

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

Adding Dependencies

To add a dependency, use the add command:

bash

Copy

poetry add requests

This updates the pyproject.toml file and installs the dependency in a virtual environment.

Installing Dependencies

To install all dependencies listed in pyproject.toml, run:

bash

Copy

poetry install

This creates a poetry.lock file, which ensures reproducible builds by locking dependency versions.

Running Scripts

You can run Python scripts using Poetry's virtual environment:

bash

Copy

poetry run python my_script.py

---

4. Key Commands

Here are some essential Poetry commands:

Command	Description
poetry new <project_name>	Create a new Poetry project.
poetry add <package>	Add a dependency to the project.
poetry remove <package>	Remove a dependency from the project.
poetry install	Install all dependencies and create a poetry.lock file.
poetry update	Update dependencies to their latest versions and update the lock file.
poetry shell	Spawn a shell within the virtual environment.
poetry run <command>	Run a command within the virtual environment.
poetry build	Build the project into a distributable format (wheel and sdist).
poetry publish	Publish the package to PyPI.
poetry show	List installed dependencies.
poetry env info	Display information about the virtual environment.

---

5. Comparison with pip

Feature	Poetry	pip
Dependency Management	Uses pyproject.toml and poetry.lock.	Uses requirements.txt.
Virtual Environments	Automatically creates and manages them.	Requires manual setup (e.g., venv).
Dependency Resolution	Advanced resolution with lock files.	Basic resolution, no lock file by default.
Project Scaffolding	Built-in (poetry new).	Requires manual setup or third-party tools.
Publishing Packages	Built-in (poetry publish).	Requires twine and setup.py.
Ease of Use	Streamlined and user-friendly.	More manual and fragmented.

Example: Adding a Dependency

• Poetry: poetry add requests

• pip: Add requests to requirements.txt and run pip install -r requirements.txt.

Example: Installing Dependencies

• Poetry: poetry install (automatically creates a virtual environment and installs dependencies).

• pip: Requires manual creation of a virtual environment (python -m venv venv) and activation (source venv/bin/activate), followed by pip install -r requirements.txt.

---

6. Conclusion

Poetry is a powerful and modern tool that simplifies Python dependency management and packaging. It offers a more streamlined and user-friendly experience compared to traditional tools like pip. By using Poetry, you can focus more on writing code and less on managing dependencies and environments.

Next Steps

• Explore Poetry's documentation: https://python-poetry.org/docs/

• Try creating and publishing your own Python package with Poetry.

• Experiment with advanced features like dependency groups and scripts.

Happy coding with Poetry! 🚀