Clean Code Python: From git init to Production Traffic

services:
  api:
    build:
      context: .
      target: runtime
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://shelfwise:shelfwise@postgres:5432/shelfwise
      - REDIS_URL=redis://redis:6379/0
      - LOG_LEVEL=debug
      - ENVIRONMENT=development
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    volumes:
      - ./src:/app/src  # Hot reload in development
    command: uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

  worker:
    build:
      context: .
      target: runtime
    environment:
      - DATABASE_URL=postgresql+asyncpg://shelfwise:shelfwise@postgres:5432/shelfwise
      - REDIS_URL=redis://redis:6379/0
      - LOG_LEVEL=debug
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: arq src.tasks.worker.WorkerSettings

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: shelfwise
      POSTGRES_PASSWORD: shelfwise
      POSTGRES_DB: shelfwise
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shelfwise"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"  # SMTP
      - "8025:8025"  # Web UI

volumes:
  pgdata:

name: CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint-and-type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv sync --frozen
      - run: uv run ruff check .
      - run: uv run ruff format --check .
      - run: uv run pyright --strict

  unit-tests:
    runs-on: ubuntu-latest
    needs: lint-and-type-check
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv sync --frozen
      - run: uv run pytest tests/unit/ --cov=src --cov-fail-under=80

  integration-tests:
    runs-on: ubuntu-latest
    needs: lint-and-type-check
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
          POSTGRES_DB: test
        ports: ["5432:5432"]
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
      redis:
        image: redis:7-alpine
        ports: ["6379:6379"]
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv sync --frozen
      - run: uv run pytest tests/integration/ -x -v
        env:
          DATABASE_URL: postgresql+asyncpg://test:test@localhost:5432/test
          REDIS_URL: redis://localhost:6379/0

  contract-tests:
    runs-on: ubuntu-latest
    needs: integration-tests
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv sync --frozen
      - run: |
          uv run uvicorn src.main:app --host 0.0.0.0 --port 8000 &
          sleep 5
          uv run schemathesis run http://localhost:8000/openapi.json --checks all

  deploy-staging:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    needs: [unit-tests, integration-tests, contract-tests]
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t shelfwise:${{ github.sha }} .
      - run: ./scripts/deploy.sh staging ${{ github.sha }}

  smoke-tests:
    runs-on: ubuntu-latest
    needs: deploy-staging
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/smoke_test.sh https://staging.shelfwise.io

  deploy-production:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    needs: smoke-tests
    environment: production
    steps:
      - run: ./scripts/deploy.sh production ${{ github.sha }}

from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    """Configuration from environment variables — Part 10."""
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
    )

    # Core
    environment: str = "development"  # development | staging | production
    debug: bool = False
    log_level: str = "info"

    # Database — Part 11 connection pooling
    database_url: SecretStr
    db_pool_min: int = 5
    db_pool_max: int = 20

    # Redis — Part 13 caching, Part 14 task queue
    redis_url: str = "redis://localhost:6379/0"

    # Security — Part 18
    jwt_secret: SecretStr = SecretStr("change-me-in-production")
    encryption_key: SecretStr = SecretStr("change-me-in-production")

    @property
    def is_production(self) -> bool:
        return self.environment == "production"

"""Automated tenant provisioning pipeline."""
import asyncio
from uuid import UUID

import structlog

from src.core.context import set_current_tenant, system_context
from src.db.session import get_session
from src.models.tenant import TenantModel
from src.services.tenant_service import TenantService

logger = structlog.get_logger()


async def provision_tenant(
    slug: str,
    name: str,
    plan: str,
    admin_email: str,
) -> UUID:
    """Provision a new tenant end-to-end.

    Steps:
    1. Create tenant record in database
    2. Run tenant-specific migrations (if schema-per-tenant)
    3. Seed default data (categories, roles, permissions)
    4. Warm caches for the new tenant
    5. Send welcome email to admin
    6. Notify operations channel

    Raises TenantProvisioningError on any failure.
    """
    async with system_context(reason="provisioning", operator="system"):
        async with get_session() as session:
            # Step 1: Create tenant record
            tenant_service = TenantService(session)
            tenant = await tenant_service.create_tenant(
                slug=slug,
                name=name,
                plan=plan,
            )
            logger.info(
                "tenant_created",
                tenant_id=str(tenant.id),
                slug=slug,
            )

            # Step 2: Seed default data
            await tenant_service.seed_defaults(tenant.id)
            logger.info("tenant_defaults_seeded", tenant_id=str(tenant.id))

            # Step 3: Create admin user
            await tenant_service.create_admin_user(
                tenant_id=tenant.id,
                email=admin_email,
            )

            # Step 4: Warm caches
            await tenant_service.warm_caches(tenant.id)

            # Step 5: Send welcome email (via background task)
            await tenant_service.enqueue_welcome_email(
                tenant_id=tenant.id,
                admin_email=admin_email,
            )

            await session.commit()
            logger.info(
                "tenant_provisioned",
                tenant_id=str(tenant.id),
                slug=slug,
                plan=plan,
            )
            return tenant.id


if __name__ == "__main__":
    import sys

    tenant_id = asyncio.run(
        provision_tenant(
            slug=sys.argv[1],
            name=sys.argv[2],
            plan=sys.argv[3],
            admin_email=sys.argv[4],
        )
    )
    print(f"Provisioned tenant: {tenant_id}")

"""Tenant offboarding pipeline: suspend → export → delete → archive."""
import asyncio
from uuid import UUID

import structlog

logger = structlog.get_logger()


async def offboard_tenant(tenant_id: UUID, reason: str) -> None:
    """Offboard a tenant with full data lifecycle.

    This is a multi-day process, not a single operation:
    Day 0:  Suspend tenant (API returns 403, data preserved)
    Day 1:  Export tenant data to S3 (GDPR data portability)
    Day 30: Delete tenant data from database
    Day 30: Archive audit logs to cold storage (7-year retention)
    """
    # Phase 1: Immediate suspension
    await _suspend_tenant(tenant_id, reason)
    logger.info("tenant_suspended", tenant_id=str(tenant_id), reason=reason)

    # Phase 2: Schedule data export (async task)
    await _enqueue_data_export(tenant_id)
    logger.info("tenant_export_scheduled", tenant_id=str(tenant_id))

    # Phase 3: Schedule deletion (30-day grace period)
    await _schedule_deletion(tenant_id, grace_days=30)
    logger.info(
        "tenant_deletion_scheduled",
        tenant_id=str(tenant_id),
        grace_days=30,
    )


async def _suspend_tenant(tenant_id: UUID, reason: str) -> None:
    """Set tenant status to suspended. All API calls return 403."""
    ...


async def _enqueue_data_export(tenant_id: UUID) -> None:
    """Export all tenant data to S3 for data portability."""
    ...


async def _schedule_deletion(tenant_id: UUID, grace_days: int) -> None:
    """Schedule hard deletion after grace period."""
    ...

groups:
  - name: shelfwise
    rules:
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05
        for: 2m
        labels:
          severity: sev2
        annotations:
          summary: "Error rate above 5% for 2 minutes"

      - alert: HighP99Latency
        expr: histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 0.5
        for: 5m
        labels:
          severity: sev3
        annotations:
          summary: "p99 latency above 500ms for 5 minutes"

      - alert: QueryCountSpike
        expr: avg(http_request_query_count) > 20
        for: 1m
        labels:
          severity: sev3
        annotations:
          summary: "Average queries per request above 20 — probable N+1"

      - alert: PoolExhaustion
        expr: db_pool_checked_out / db_pool_size > 0.9
        for: 2m
        labels:
          severity: sev2
        annotations:
          summary: "DB connection pool above 90% — requests will queue"

      - alert: WorkerQueueBacklog
        expr: arq_queue_length > 1000
        for: 5m
        labels:
          severity: sev2
        annotations:
          summary: "Background task queue backlog above 1000"