TCPDashboard/docs/dependency-management.md

Dependency Management Guide

This guide explains how to manage Python dependencies in the Crypto Trading Bot Dashboard project.

Local Development

Adding New Dependencies

1. Core Dependencies (Required for Runtime)

To add a new core dependency:

# Method 1: Add directly to pyproject.toml
# Edit pyproject.toml and add to the dependencies list:
# "new-package>=1.0.0",

# Method 2: Use UV to add and update pyproject.toml
uv add "new-package>=1.0.0"

# Sync to install
uv sync

2. Development Dependencies (Testing, Linting, etc.)

# Add development-only dependency
uv add --dev "new-dev-package>=1.0.0"

# Or edit pyproject.toml under [project.optional-dependencies.dev]
# Then run:
uv sync --dev

Installing Dependencies

# Install all dependencies
uv sync

# Install with development dependencies
uv sync --dev

# Install only production dependencies
uv sync --no-dev

Updating Dependencies

# Update all dependencies to latest compatible versions
uv sync --upgrade

# Update specific package
uv sync --upgrade-package "package-name"

Docker Environment

Current Approach

The project uses a volume-based development approach where:

• Dependencies are installed in the local environment using UV
• Docker containers provide only infrastructure services (PostgreSQL, Redis)
• The Python application runs locally with hot reload

Adding Dependencies for Docker-based Development

If you want to run the entire application in Docker:

1. Create a Dockerfile

FROM python:3.10-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    postgresql-client \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install UV
RUN pip install uv

# Copy dependency files
COPY pyproject.toml ./
COPY README.md ./

# Install dependencies
RUN uv sync --no-dev

# Copy application code
COPY . .

# Expose port
EXPOSE 8050

# Run application
CMD ["uv", "run", "python", "main.py"]

2. Add Application Service to docker-compose.yml

services:
  app:
    build: .
    container_name: dashboard_app
    ports:
      - "8050:8050"
    volumes:
      - .:/app
      - uv_cache:/root/.cache/uv
    environment:
      - DATABASE_URL=postgresql://dashboard:dashboard123@postgres:5432/dashboard
      - REDIS_URL=redis://redis:6379
    depends_on:
      - postgres
      - redis
    networks:
      - dashboard-network
    restart: unless-stopped

volumes:
  uv_cache:

3. Development Workflow with Docker

# Build and start all services
docker-compose up --build

# Add new dependency
# 1. Edit pyproject.toml
# 2. Rebuild container
docker-compose build app
docker-compose up -d app

# Or use dev dependencies mount
# Mount local UV cache for faster rebuilds

Hot Reload Development

Method 1: Local Development (Recommended)

Run services in Docker, application locally with hot reload:

# Start infrastructure
python scripts/dev.py start

# Run app with hot reload
uv run python scripts/dev.py dev-server

Method 2: Docker with Volume Mounts

If using Docker for the app, mount source code:

volumes:
  - .:/app  # Mount source code
  - /app/__pycache__  # Exclude cache

Best Practices

1. Version Pinning

# Good: Specify minimum version with compatibility
"requests>=2.31.0,<3.0.0"

# Acceptable: Major version constraint
"pandas>=2.1.0"

# Avoid: Exact pinning (except for critical deps)
"somepackage==1.2.3"  # Only if necessary

2. Dependency Categories

[project]
dependencies = [
    # Core web framework
    "dash>=2.14.0",
    
    # Database
    "sqlalchemy>=2.0.0",
    "psycopg2-binary>=2.9.0",
    
    # ... group related dependencies
]

3. Security Updates

# Check for security vulnerabilities
pip-audit

# Update specific vulnerable package
uv sync --upgrade-package "vulnerable-package"

Troubleshooting

Common Issues

1. Dependency Conflicts

   # Clear UV cache and reinstall
   uv cache clean
   uv sync --refresh
   

2. PostgreSQL Connection Issues

   # Ensure psycopg2-binary is installed
   uv add "psycopg2-binary>=2.9.0"
   

3. Docker Build Failures

   # Clean docker build cache
   docker system prune --volumes
   docker-compose build --no-cache
   

Debugging Dependencies

# Show installed packages
uv pip list

# Show dependency tree
uv pip show <package-name>

# Check for conflicts
uv pip check

Migration from requirements.txt

If you have an existing requirements.txt:

# Convert to pyproject.toml
uv add -r requirements.txt

# Or manually copy dependencies to pyproject.toml
# Then remove requirements.txt