docs/POETRY_USAGE.md

# Poetry Usage Guide

This guide provides instructions on how to use [Poetry](https://python-poetry.org/) to manage dependencies, install packages, and prepare your project for both development and production environments.

## Table of Contents

- [Overview](#overview)
- [Installing Poetry](#installing-poetry)
- [Using Poetry in Development](#using-poetry-in-development)
  - [Installing Dependencies](#installing-dependencies)
  - [Updating Dependencies](#updating-dependencies)
  - [Adding and Removing Dependencies](#adding-and-removing-dependencies)
  - [Synchronizing Dependencies](#synchronizing-dependencies)
- [Using Poetry in Production](#using-poetry-in-production)
  - [Locking Dependencies](#locking-dependencies)
  - [Installing from `poetry.lock`](#installing-from-poetrylock)
- [Poetry Commands Summary](#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:

```bash
brew install poetry
```

Refer to the [Poetry documentation](https://python-poetry.org/docs/#installation) 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:

   ```bash
   cd path/to/project
   ```

2. Run:
   ```bash
   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:

```bash
poetry install
```

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

### Adding and Removing Dependencies

- **Add a New Dependency**:

  ```bash
  poetry add <package-name>
  ```

  Example:

  ```bash
  poetry add requests
  ```

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

  ```bash
  poetry add --group dev <package-name>
  ```

  Example:

  ```bash
  poetry add --group dev pytest
  ```

- **Remove a Dependency**:
  ```bash
  poetry remove <package-name>
  ```

### Synchronizing Dependencies

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

```bash
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:

```bash
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:
   ```bash
   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/](https://python-poetry.org/docs/)
- **GitHub Repository**: [https://github.com/python-poetry/poetry](https://github.com/python-poetry/poetry)

For further help, please refer to the [Poetry documentation](https://python-poetry.org/docs/).