docs/POETRY_USAGE.md

Poetry Usage Guide

This guide provides instructions on how to use Poetry to manage dependencies, install packages, and prepare your project for both development and production environments.

Table of Contents

• Overview
• Installing Poetry
• Using Poetry in Development
  • Installing Dependencies
  • Updating Dependencies
  • Adding and Removing Dependencies
  • Synchronizing Dependencies
• Using Poetry in Production
  • Locking Dependencies
  • Installing from poetry.lock
• Poetry Commands Summary

---

Overview

Poetry is a dependency manager and build tool for Python projects. It simplifies managing dependencies, creating virtual environments, and ensuring version consistency between development and production environments. Poetry relies on two files:

• pyproject.toml: Defines the dependencies and configuration.
• poetry.lock: Locks dependencies to specific versions to ensure consistency.

---

Installing Poetry(macOS only)

To install Poetry, use the following command:

brew install poetry

Refer to the Poetry documentation for more options and OS-specific installation instructions.

---

Using Poetry in Development

Installing Dependencies

In development, install dependencies specified in pyproject.toml:

1. Navigate to the project directory:

   cd path/to/project
   

2. Run:

   poetry install
   

This command creates a virtual environment, installs all dependencies, and ensures they are compatible with the Python version specified.

Updating Dependencies

During development, you can update dependencies by editing pyproject.toml directly and then running:

poetry install

This will apply any changes and update the environment without manually adding each dependency.

Adding and Removing Dependencies

• Add a New Dependency:

  poetry add <package-name>
  

  Example:

  poetry add requests
  

• Add a Development Dependency (only used for development/testing):

  poetry add --group dev <package-name>
  

  Example:

  poetry add --group dev pytest
  

• Remove a Dependency:

  poetry remove <package-name>
  

Synchronizing Dependencies

If the pyproject.toml or poetry.lock files are updated (e.g., after pulling changes), run:

poetry install

This keeps your environment synchronized with any updates made to the dependency files.

---

Using Poetry in Production

Locking Dependencies

To lock dependencies for production use, run:

poetry lock

This creates or updates poetry.lock, which pins each dependency to a specific version. This lock file should be used to maintain consistency in production.

Installing from poetry.lock

In production, use poetry.lock to ensure exact dependency versions:

1. Install only the required (non-development) dependencies:

   poetry install --no-dev
   

This ensures that dependencies are installed exactly as defined in poetry.lock.

---

Poetry Commands Summary

Command	Description
poetry install	Installs dependencies from pyproject.toml or poetry.lock.
poetry add <package-name>	Adds a new dependency and updates pyproject.toml.
poetry add --group dev <pkg>	Adds a development-only dependency.
poetry remove <package-name>	Removes a dependency and updates pyproject.toml.
poetry update	Updates all dependencies to their latest compatible versions.
poetry lock	Locks dependencies to specific versions for production.
poetry shell	Activates the Poetry-managed virtual environment.

---

Additional Resources

• Poetry Documentation: https://python-poetry.org/docs/
• GitHub Repository: https://github.com/python-poetry/poetry

For further help, please refer to the Poetry documentation.