Skip to content

POETRY.md

Latest commit

 

History

History
584 lines (452 loc) · 12.7 KB

POETRY.md

File metadata and controls

584 lines (452 loc) · 12.7 KB
Raw

Poetry Setup and Usage Guide

What is Poetry?

Poetry is a modern Python dependency management and packaging tool that provides:

  • Dependency Resolution: Automatically resolves and locks dependencies
  • Virtual Environments: Creates and manages isolated Python environments
  • Reproducible Builds: Lock file ensures consistent installations across all environments
  • Easy Dependency Management: Simple commands to add, update, and remove packages

Installation

Installing Poetry

macOS / Linux:

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

Windows (PowerShell):

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

Alternative (via pip):

pip install poetry

Verify Installation

poetry --version

Shell Completion (Optional)

Poetry supports tab completion for bash, zsh, and fish:

# Bash
poetry completions bash >> ~/.bash_completion

# Zsh
poetry completions zsh > ~/.zfunc/_poetry

# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish

Project Configuration

This project is configured with Poetry using the following files:

pyproject.toml

The main configuration file that defines:

  • Project metadata (name, version, description, authors)
  • Python version requirement (^3.11)
  • All project dependencies
  • Dependency groups (dev, wvnet, uat)
  • Build system configuration

poetry.lock

Auto-generated lock file that:

  • Locks exact versions of all dependencies (including transitive ones)
  • Ensures reproducible installations
  • Should be committed to version control

poetry.toml

Project-specific Poetry settings:

[virtualenvs]
create = true
in-project = true

This configuration creates the virtual environment inside the project directory (.venv/), making it easier to manage and discover.

Getting Started with This Project

1. Clone the Repository

git clone https://github.com/3492PARTs/PARTs_WebAPI.git
cd PARTs_WebAPI

2. Install Dependencies

Install only production dependencies:

poetry install --no-dev

Install with development dependencies (recommended for contributors):

poetry install --with dev

Install all optional dependency groups:

poetry install --with dev,wvnet,uat

3. Activate the Virtual Environment

Option 1: Use poetry run (recommended)

poetry run python src/manage.py runserver
poetry run pytest

Option 2: Activate the shell

poetry shell
# Now you're in the virtual environment
python src/manage.py runserver
pytest

Option 3: Direct shell activation

# Unix/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

Dependency Groups

This project defines several dependency groups for different use cases:

Main Dependencies (Required)

These are the core dependencies required to run the application:

[tool.poetry.dependencies]
python = "^3.11"
django = "5.2.8"
djangorestframework = "3.16.1"
djangorestframework-simplejwt = "5.5.1"
django-cors-headers = "4.8.0"
django-filter = "25.1"
django-simple-history = "3.10.1"
django-webpush = "0.3.6"
cloudinary = "1.44.1"
gunicorn = "23.0.0"
python-dotenv = "1.1.1"
requests = "2.32.5"
pillow = "11.3.0"
# ... and other core dependencies

Installation:

poetry install

Development Group (Optional)

Testing and development tools:

[tool.poetry.group.dev]
optional = true

[tool.poetry.group.dev.dependencies]
pipdeptree = "^2.23.4"          # Visualize dependency tree
pytest = "^8.0.0"                # Test framework
pytest-django = "^4.8.0"         # Django plugin for pytest
pytest-cov = "^6.0.0"            # Coverage reporting
pytest-mock = "^3.14.0"          # Enhanced mocking
freezegun = "^1.5.0"             # Time mocking for tests
factory-boy = "^3.3.0"           # Test data factories
requests-mock = "^1.12.0"        # HTTP request mocking
faker = "^33.0.0"                # Fake data generation

Installation:

poetry install --with dev

Use for:

  • Running tests (pytest)
  • Code coverage reports
  • Development and debugging
  • Test data generation

WVNet Group (Optional)

Dependencies for WVNet deployment environment:

[tool.poetry.group.wvnet]
optional = true

[tool.poetry.group.wvnet.dependencies]
gunicorn = "23.0.0"              # WSGI HTTP server
uwsgi = "2.0.30"                 # Application server
mysqlclient = "2.2.7"            # MySQL database adapter

Installation:

poetry install --with wvnet

Use for:

  • WVNet production deployments
  • MySQL database connections
  • uWSGI application server setup

UAT Group (Optional)

Dependencies for User Acceptance Testing (staging) environment:

[tool.poetry.group.uat]
optional = true

[tool.poetry.group.uat.dependencies]
gunicorn = "23.0.0"              # WSGI HTTP server
uwsgi = "2.0.30"                 # Application server
psycopg2-binary = "*"            # PostgreSQL database adapter

Installation:

poetry install --with uat

Use for:

  • UAT/staging deployments
  • PostgreSQL database connections
  • Pre-production testing

Common Poetry Commands

Managing Dependencies

Add a new dependency:

# Add to main dependencies
poetry add django-extensions

# Add to dev group
poetry add --group dev black

# Add with version constraint
poetry add "django>=4.0,<5.0"

Remove a dependency:

poetry remove package-name

Update dependencies:

# Update all dependencies
poetry update

# Update specific package
poetry update django

# Update packages in a group
poetry update --with dev

Show installed packages:

poetry show

# Show as a tree
poetry show --tree

# Show only dev dependencies
poetry show --only dev

Check for outdated packages:

poetry show --outdated

Running Commands

Run a command in the virtual environment:

poetry run python src/manage.py migrate
poetry run pytest
poetry run python src/manage.py runserver

Activate shell:

poetry shell

Exit shell:

exit

Environment Management

Show environment info:

poetry env info

List environments:

poetry env list

Remove environment:

poetry env remove python3.11

Use a specific Python version:

poetry env use python3.11
poetry env use python3.12

Lock File Management

Update lock file without installing:

poetry lock --no-update

Update lock file and upgrade dependencies:

poetry lock

Install from lock file exactly:

poetry install --sync

Working with Requirements.txt

If you need a requirements.txt file (for deployment platforms that don't support Poetry):

Export all dependencies:

poetry export -f requirements.txt --output requirements.txt --without-hashes

Export with dev dependencies:

poetry export -f requirements.txt --output requirements.txt --with dev --without-hashes

Export specific groups:

poetry export -f requirements.txt --output requirements.txt --with dev,wvnet --without-hashes

Project-Specific Workflows

Development Setup

# 1. Install with dev dependencies
poetry install --with dev

# 2. Set up environment
cp .env.example .env
# Edit .env with your settings

# 3. Run migrations
poetry run python src/manage.py migrate

# 4. Run tests
poetry run pytest

# 5. Start development server
poetry run python src/manage.py runserver

Running Tests

# All tests with coverage
poetry run pytest

# Without coverage (faster)
poetry run pytest --no-cov

# Specific test file
poetry run pytest tests/user/test_user_comprehensive.py

# Verbose output
poetry run pytest -v

WVNet Deployment

# Install with WVNet dependencies
poetry install --without dev --with wvnet

# Start with gunicorn
cd src
poetry run gunicorn parts_webapi.wsgi:application --bind 0.0.0.0:8000

UAT Deployment

# Install with UAT dependencies
poetry install --without dev --with uat

# Run migrations
poetry run python src/manage.py migrate --settings=parts_webapi.settings.production

# Start with gunicorn
cd src
poetry run gunicorn parts_webapi.wsgi:application --bind 0.0.0.0:8000

Troubleshooting

Virtual Environment Not Found

# Recreate the virtual environment
poetry env remove python3.11
poetry install --with dev

Dependency Conflicts

# Clear cache and reinstall
poetry cache clear pypi --all
poetry install --with dev

Lock File Out of Sync

# Regenerate lock file
poetry lock --no-update
poetry install --with dev

Poetry Command Not Found

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

# Or reinstall
curl -sSL https://install.python-poetry.org | python3 -

Slow Dependency Resolution

# Use newer installer (faster)
poetry config installer.modern-installation true

Configuration Options

Global Configuration

List current config:

poetry config --list

Set PyPI credentials:

poetry config pypi-token.pypi <your-token>

Configure virtualenv location:

# Create in project directory (already configured for this project)
poetry config virtualenvs.in-project true

# Create in global cache
poetry config virtualenvs.in-project false

Project Configuration

The project uses poetry.toml for project-specific settings:

[virtualenvs]
create = true
in-project = true

This ensures consistent virtual environment location across all developers.

Best Practices

For Contributors

  1. Always use Poetry for dependency management
  2. Commit poetry.lock to ensure reproducible builds
  3. Use dependency groups appropriately (dev, wvnet, uat)
  4. Run tests before committing: poetry run pytest
  5. Keep dependencies updated regularly
  6. Use specific version constraints when adding critical dependencies

Adding New Dependencies

# 1. Add the dependency
poetry add package-name

# 2. Test that it works
poetry run pytest

# 3. Commit both pyproject.toml and poetry.lock
git add pyproject.toml poetry.lock
git commit -m "Add package-name dependency"

Updating Dependencies

# 1. Update dependencies
poetry update

# 2. Run tests to ensure nothing broke
poetry run pytest

# 3. Commit the updated lock file
git add poetry.lock
git commit -m "Update dependencies"

Comparison with pip/virtualenv

Feature Poetry pip + virtualenv
Dependency Resolution ✅ Automatic ❌ Manual
Lock File ✅ Yes (poetry.lock) ⚠️ Manual (requirements.txt)
Virtual Environment ✅ Automatic ❌ Manual creation
Dependency Groups ✅ Built-in ❌ Multiple requirement files
Add/Remove Packages ✅ poetry add/remove ⚠️ pip install + manual requirements update
Version Constraints ✅ Flexible syntax ⚠️ Less flexible
Build System ✅ Integrated ❌ Separate tools

Additional Resources

Quick Reference

# Setup
poetry install                           # Install dependencies
poetry install --with dev                # Install with dev group
poetry install --with dev,wvnet,uat      # Install all groups

# Add/Remove
poetry add package-name                  # Add dependency
poetry add --group dev package-name      # Add to dev group
poetry remove package-name               # Remove dependency

# Update
poetry update                            # Update all
poetry update package-name               # Update specific package

# Run
poetry run <command>                     # Run command
poetry shell                             # Activate shell

# Info
poetry show                              # List packages
poetry show --tree                       # Show as tree
poetry show --outdated                   # Check for updates
poetry env info                          # Environment info

# Export
poetry export -f requirements.txt --output requirements.txt --without-hashes

Questions or Issues?

For questions about Poetry usage in this project:

  1. Check this documentation
  2. See CONTRIBUTING.md for contribution guidelines
  3. Review the official Poetry documentation
  4. Open an issue on GitHub for project-specific questions