moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-lang-python/examples.md

@@ -1,624 +1,977 @@
-# Python 3.13 Code Examples
+# Python Production-Ready Code Examples
 
-Production-ready examples for modern Python development with pytest 8.4.2, ruff 0.13.1, mypy 1.8.0, FastAPI 0.115.0, and Python 3.13.1 features.
+## Complete FastAPI Application
 
----
-
-## Example 1: pytest 8.4.2 with Fixtures and Async Tests
+### Project Structure
+```
+fastapi_app/
+├── app/
+│   ├── __init__.py
+│   ├── main.py
+│   ├── config.py
+│   ├── database.py
+│   ├── dependencies.py
+│   ├── models/
+│   │   ├── __init__.py
+│   │   └── user.py
+│   ├── schemas/
+│   │   ├── __init__.py
+│   │   └── user.py
+│   ├── repositories/
+│   │   ├── __init__.py
+│   │   └── user_repository.py
+│   ├── services/
+│   │   ├── __init__.py
+│   │   └── user_service.py
+│   └── api/
+│       ├── __init__.py
+│       └── v1/
+│           ├── __init__.py
+│           ├── router.py
+│           └── endpoints/
+│               └── users.py
+├── tests/
+│   ├── conftest.py
+│   ├── test_users.py
+│   └── test_services.py
+├── pyproject.toml
+└── Dockerfile
+```
 
-### Test File: `tests/test_user_service.py`
+### Main Application Entry
 
 ```python
-"""
-Test suite for UserService with pytest fixtures and async support.
-Demonstrates pytest 8.4.2 best practices for Python 3.13.
-"""
-import pytest
-from unittest.mock import AsyncMock
-from src.services.user_service import UserService
-from src.models.user import User
-
-
-@pytest.fixture
-def user_service():
-    """Fixture providing a UserService instance with mocked dependencies."""
-    return UserService(db_client=AsyncMock())
+# app/main.py
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.config import get_settings
+from app.database import init_db, close_db
+from app.api.v1.router import api_router
+
+settings = get_settings()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    await init_db()
+    yield
+    # Shutdown
+    await close_db()
+
+app = FastAPI(
+    title=settings.app_name,
+    version="1.0.0",
+    lifespan=lifespan,
+    docs_url="/api/docs",
+    redoc_url="/api/redoc",
+)
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include API router
+app.include_router(api_router, prefix="/api/v1")
+
+@app.get("/health")
+async def health_check():
+    return {"status": "healthy", "version": "1.0.0"}
+```
 
+### Configuration
 
-@pytest.fixture
-def sample_user():
-    """Fixture providing a sample User instance for tests."""
-    return User(id=1, name="Alice", email="alice@example.com")
+```python
+# app/config.py
+from functools import lru_cache
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+    )
 
+    # Application
+    app_name: str = "FastAPI App"
+    debug: bool = False
+    environment: str = "development"
 
-def test_user_creation(user_service, sample_user):
-    """Verify user creation with valid data."""
-    result = user_service.validate_user(sample_user)
-    assert result is True
-    assert sample_user.id > 0
+    # Database
+    database_url: str = "postgresql+asyncpg://user:pass@localhost/db"
+    db_pool_size: int = 5
+    db_max_overflow: int = 10
+    db_pool_timeout: int = 30
 
+    # Security
+    secret_key: str
+    access_token_expire_minutes: int = 30
+    refresh_token_expire_days: int = 7
+    algorithm: str = "HS256"
 
-@pytest.mark.asyncio
-async def test_fetch_user_async(user_service):
-    """Test async user fetching with mocked database."""
-    user_service.db_client.fetch_user.return_value = User(
-        id=1, name="Bob", email="bob@example.com"
-    )
+    # CORS
+    cors_origins: list[str] = ["http://localhost:3000"]
 
-    user = await user_service.fetch_user(user_id=1)
+    # Redis (optional)
+    redis_url: str | None = None
 
-    assert user is not None
-    assert user.name == "Bob"
-    user_service.db_client.fetch_user.assert_called_once_with(1)
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()
+```
 
+### Database Setup
 
-@pytest.mark.parametrize("user_id,expected_name", [
-    (1, "Alice"),
-    (2, "Bob"),
-    (3, "Charlie"),
-])
-@pytest.mark.asyncio
-async def test_fetch_multiple_users(user_service, user_id, expected_name):
-    """Parametrized test for fetching multiple users."""
-    user_service.db_client.fetch_user.return_value = User(
-        id=user_id, name=expected_name, email=f"{expected_name.lower()}@example.com"
+```python
+# app/database.py
+from sqlalchemy.ext.asyncio import (
+    create_async_engine,
+    async_sessionmaker,
+    AsyncSession,
+    AsyncEngine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+from app.config import get_settings
+
+settings = get_settings()
+
+class Base(DeclarativeBase):
+    pass
+
+engine: AsyncEngine | None = None
+async_session_factory: async_sessionmaker[AsyncSession] | None = None
+
+async def init_db():
+    global engine, async_session_factory
+
+    engine = create_async_engine(
+        settings.database_url,
+        pool_size=settings.db_pool_size,
+        max_overflow=settings.db_max_overflow,
+        pool_timeout=settings.db_pool_timeout,
+        pool_pre_ping=True,
+        echo=settings.debug,
     )
 
-    user = await user_service.fetch_user(user_id=user_id)
+    async_session_factory = async_sessionmaker(
+        engine,
+        class_=AsyncSession,
+        expire_on_commit=False,
+        autoflush=False,
+    )
 
-    assert user.name == expected_name
+    # Create tables (for development only)
+    if settings.debug:
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+
+async def close_db():
+    global engine
+    if engine:
+        await engine.dispose()
+
+async def get_db() -> AsyncSession:
+    if async_session_factory is None:
+        raise RuntimeError("Database not initialized")
+
+    async with async_session_factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
 ```
 
-**Key Features**:
-- ✅ Fixtures for dependency injection
-- ✅ `@pytest.mark.asyncio` for async tests
-- ✅ `@pytest.mark.parametrize` for data-driven tests
-- ✅ AsyncMock for mocking async operations
-- ✅ One assertion per test (clarity)
-
-**Run Commands**:
-```bash
-pytest tests/test_user_service.py -v
-pytest tests/test_user_service.py --cov=src.services --cov-report=term
-```
+### SQLAlchemy Models
 
----
+```python
+# app/models/user.py
+from datetime import datetime
+from sqlalchemy import String, Boolean, DateTime, func
+from sqlalchemy.orm import Mapped, mapped_column
 
-## Example 2: ruff 0.13.1 Linting and Formatting Workflow
+from app.database import Base
 
-### Project Configuration: `pyproject.toml`
+class User(Base):
+    __tablename__ = "users"
 
-```toml
-[tool.ruff]
-line-length = 100
-target-version = "py313"
-exclude = [".venv", "build", "dist", "__pycache__"]
+    id: Mapped[int] = mapped_column(primary_key=True, index=True)
+    email: Mapped[str] = mapped_column(
+        String(255), unique=True, index=True, nullable=False
+    )
+    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    is_superuser: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
+    )
 
-[tool.ruff.lint]
-select = [
-    "E",   # pycodestyle errors
-    "F",   # pyflakes
-    "W",   # pycodestyle warnings
-    "I",   # isort (import sorting)
-    "N",   # pep8-naming
-    "UP",  # pyupgrade (use Python 3.13 features)
-    "B",   # flake8-bugbear
-    "C4",  # flake8-comprehensions
-]
-ignore = ["E501"]  # Line length handled by formatter
-
-[tool.ruff.lint.per-file-ignores]
-"tests/**/*.py" = ["F401", "F811"]  # Allow unused imports in tests
-
-[tool.ruff.format]
-quote-style = "double"
-indent-style = "space"
+    def __repr__(self) -> str:
+        return f"<User(id={self.id}, email={self.email})>"
 ```
 
-### Example Source File: `src/utils/formatter.py`
+### Pydantic Schemas
 
 ```python
-"""String formatting utilities using Python 3.13 features."""
-from typing import override
-
-
-class Formatter:
-    """Base formatter class."""
-
-    def format(self, text: str) -> str:
-        """Format text with default behavior."""
-        return text.strip()
+# app/schemas/user.py
+from datetime import datetime
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
 
+class UserBase(BaseModel):
+    email: EmailStr
+    name: str = Field(min_length=1, max_length=100)
 
-class UppercaseFormatter(Formatter):
-    """Formatter that converts text to uppercase."""
+class UserCreate(UserBase):
+    password: str = Field(min_length=8, max_length=100)
 
-    @override  # Python 3.13 PEP 698
-    def format(self, text: str) -> str:
-        """Format text to uppercase."""
-        return text.strip().upper()
+class UserUpdate(BaseModel):
+    name: str | None = Field(None, min_length=1, max_length=100)
+    password: str | None = Field(None, min_length=8, max_length=100)
 
+class UserResponse(UserBase):
+    model_config = ConfigDict(from_attributes=True)
 
-def format_user_info(name: str, age: int, city: str) -> str:
-    """Format user information with nested f-strings (Python 3.13 PEP 701)."""
-    # Python 3.13 allows nested f-strings and arbitrary expressions
-    return f"User: {name}, Details: {f'Age: {age}, City: {city.upper()}'}"
+    id: int
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+
+class UserListResponse(BaseModel):
+    users: list[UserResponse]
+    total: int
+    page: int
+    size: int
+
+class Token(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+
+class TokenPayload(BaseModel):
+    sub: int
+    exp: datetime
+    type: str  # "access" or "refresh"
 ```
 
-**Workflow Commands**:
-```bash
-# Lint and auto-fix issues
-ruff check . --fix
-
-# Format code (replaces black)
-ruff format .
-
-# Check specific rules
-ruff check --select I .           # Import sorting only
-ruff check --select UP .          # Python 3.13 upgrade suggestions
+### Repository Pattern
 
-# Show what would be fixed (dry-run)
-ruff check --show-fixes .
+```python
+# app/repositories/user_repository.py
+from sqlalchemy import select, func
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.user import User
+from app.schemas.user import UserCreate, UserUpdate
+
+class UserRepository:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def get_by_id(self, user_id: int) -> User | None:
+        result = await self.session.execute(
+            select(User).where(User.id == user_id)
+        )
+        return result.scalar_one_or_none()
+
+    async def get_by_email(self, email: str) -> User | None:
+        result = await self.session.execute(
+            select(User).where(User.email == email)
+        )
+        return result.scalar_one_or_none()
+
+    async def get_multi(
+        self,
+        skip: int = 0,
+        limit: int = 100,
+        is_active: bool | None = None,
+    ) -> tuple[list[User], int]:
+        query = select(User)
+        count_query = select(func.count(User.id))
+
+        if is_active is not None:
+            query = query.where(User.is_active == is_active)
+            count_query = count_query.where(User.is_active == is_active)
+
+        # Get total count
+        total_result = await self.session.execute(count_query)
+        total = total_result.scalar_one()
+
+        # Get users
+        query = query.offset(skip).limit(limit).order_by(User.created_at.desc())
+        result = await self.session.execute(query)
+        users = result.scalars().all()
+
+        return list(users), total
+
+    async def create(self, user_create: UserCreate, hashed_password: str) -> User:
+        user = User(
+            email=user_create.email,
+            name=user_create.name,
+            hashed_password=hashed_password,
+        )
+        self.session.add(user)
+        await self.session.flush()
+        await self.session.refresh(user)
+        return user
+
+    async def update(self, user: User, user_update: UserUpdate) -> User:
+        update_data = user_update.model_dump(exclude_unset=True)
+        for field, value in update_data.items():
+            setattr(user, field, value)
+        await self.session.flush()
+        await self.session.refresh(user)
+        return user
+
+    async def delete(self, user: User) -> None:
+        await self.session.delete(user)
+        await self.session.flush()
+
+    async def deactivate(self, user: User) -> User:
+        user.is_active = False
+        await self.session.flush()
+        await self.session.refresh(user)
+        return user
 ```
 
----
-
-## Example 3: mypy 1.8.0 Type Checking with Pydantic 2.7.0
-
-### Source File: `src/models/product.py`
+### Service Layer
 
 ```python
-"""Product models with static (mypy) and runtime (Pydantic) validation."""
-from typing import override
-from pydantic import BaseModel, Field, field_validator
-from decimal import Decimal
-
-
-class Product(BaseModel):
-    """Product model with runtime validation via Pydantic 2.7.0."""
-
-    id: int = Field(gt=0, description="Product ID must be positive")
-    name: str = Field(min_length=1, max_length=100)
-    price: Decimal = Field(gt=0, decimal_places=2)
-    stock: int = Field(ge=0, description="Stock cannot be negative")
-
-    @field_validator("name")
-    @classmethod
-    def name_must_not_contain_special_chars(cls, v: str) -> str:
-        """Validate that name contains only alphanumeric characters."""
-        if not v.replace(" ", "").isalnum():
-            raise ValueError("Product name must be alphanumeric")
-        return v
-
-    def apply_discount(self, percentage: float) -> Decimal:
-        """Apply discount percentage to product price."""
-        if not 0 <= percentage <= 100:
-            raise ValueError("Discount must be between 0 and 100")
-        discount_amount = self.price * Decimal(percentage / 100)
-        return self.price - discount_amount
-
-
-class GenericContainer[T]:  # Python 3.13 PEP 695 type parameters
-    """Generic container using Python 3.13 type parameter syntax."""
-
-    def __init__(self, items: list[T]) -> None:
-        self.items = items
-
-    def first(self) -> T | None:
-        """Return first item or None if empty."""
-        return self.items[0] if self.items else None
+# app/services/user_service.py
+from datetime import datetime, timedelta, timezone
+from jose import jwt
+from passlib.context import CryptContext
+
+from app.config import get_settings
+from app.models.user import User
+from app.schemas.user import UserCreate, UserUpdate, Token, TokenPayload
+from app.repositories.user_repository import UserRepository
+
+settings = get_settings()
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+class UserService:
+    def __init__(self, repository: UserRepository):
+        self.repository = repository
+
+    @staticmethod
+    def hash_password(password: str) -> str:
+        return pwd_context.hash(password)
+
+    @staticmethod
+    def verify_password(plain_password: str, hashed_password: str) -> bool:
+        return pwd_context.verify(plain_password, hashed_password)
+
+    @staticmethod
+    def create_token(user_id: int, token_type: str, expires_delta: timedelta) -> str:
+        expire = datetime.now(timezone.utc) + expires_delta
+        payload = TokenPayload(
+            sub=user_id,
+            exp=expire,
+            type=token_type,
+        )
+        return jwt.encode(
+            payload.model_dump(),
+            settings.secret_key,
+            algorithm=settings.algorithm,
+        )
+
+    def create_tokens(self, user: User) -> Token:
+        access_token = self.create_token(
+            user.id,
+            "access",
+            timedelta(minutes=settings.access_token_expire_minutes),
+        )
+        refresh_token = self.create_token(
+            user.id,
+            "refresh",
+            timedelta(days=settings.refresh_token_expire_days),
+        )
+        return Token(access_token=access_token, refresh_token=refresh_token)
+
+    async def authenticate(self, email: str, password: str) -> User | None:
+        user = await self.repository.get_by_email(email)
+        if not user:
+            return None
+        if not self.verify_password(password, user.hashed_password):
+            return None
+        if not user.is_active:
+            return None
+        return user
+
+    async def register(self, user_create: UserCreate) -> User:
+        hashed_password = self.hash_password(user_create.password)
+        return await self.repository.create(user_create, hashed_password)
+
+    async def update(self, user: User, user_update: UserUpdate) -> User:
+        if user_update.password:
+            user_update.password = self.hash_password(user_update.password)
+        return await self.repository.update(user, user_update)
+```
 
-    def add(self, item: T) -> None:
-        """Add item to container."""
-        self.items.append(item)
+### API Endpoints
 
+```python
+# app/api/v1/endpoints/users.py
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.database import get_db
+from app.dependencies import get_current_user, get_current_active_superuser
+from app.models.user import User
+from app.schemas.user import (
+    UserCreate,
+    UserUpdate,
+    UserResponse,
+    UserListResponse,
+    Token,
+)
+from app.repositories.user_repository import UserRepository
+from app.services.user_service import UserService
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+def get_user_service(db: AsyncSession = Depends(get_db)) -> UserService:
+    repository = UserRepository(db)
+    return UserService(repository)
+
+@router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def register(
+    user_create: UserCreate,
+    service: UserService = Depends(get_user_service),
+):
+    """Register a new user."""
+    existing = await service.repository.get_by_email(user_create.email)
+    if existing:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Email already registered",
+        )
+    user = await service.register(user_create)
+    return user
+
+@router.post("/login", response_model=Token)
+async def login(
+    email: str,
+    password: str,
+    service: UserService = Depends(get_user_service),
+):
+    """Authenticate and get tokens."""
+    user = await service.authenticate(email, password)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid credentials",
+        )
+    return service.create_tokens(user)
+
+@router.get("/me", response_model=UserResponse)
+async def get_current_user_info(
+    current_user: User = Depends(get_current_user),
+):
+    """Get current user information."""
+    return current_user
+
+@router.patch("/me", response_model=UserResponse)
+async def update_current_user(
+    user_update: UserUpdate,
+    current_user: User = Depends(get_current_user),
+    service: UserService = Depends(get_user_service),
+):
+    """Update current user."""
+    return await service.update(current_user, user_update)
+
+@router.get("", response_model=UserListResponse)
+async def list_users(
+    page: int = Query(1, ge=1),
+    size: int = Query(20, ge=1, le=100),
+    is_active: bool | None = None,
+    current_user: User = Depends(get_current_active_superuser),
+    service: UserService = Depends(get_user_service),
+):
+    """List all users (admin only)."""
+    skip = (page - 1) * size
+    users, total = await service.repository.get_multi(
+        skip=skip, limit=size, is_active=is_active
+    )
+    return UserListResponse(users=users, total=total, page=page, size=size)
 
-# Usage example
-def process_products(products: GenericContainer[Product]) -> list[str]:
-    """Process products and return their names."""
-    return [p.name for p in products.items if p.stock > 0]
+@router.get("/{user_id}", response_model=UserResponse)
+async def get_user(
+    user_id: int,
+    current_user: User = Depends(get_current_active_superuser),
+    service: UserService = Depends(get_user_service),
+):
+    """Get user by ID (admin only)."""
+    user = await service.repository.get_by_id(user_id)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found",
+        )
+    return user
+
+@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def deactivate_user(
+    user_id: int,
+    current_user: User = Depends(get_current_active_superuser),
+    service: UserService = Depends(get_user_service),
+):
+    """Deactivate user (admin only)."""
+    user = await service.repository.get_by_id(user_id)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found",
+        )
+    await service.repository.deactivate(user)
 ```
 
-### mypy Configuration: `pyproject.toml`
+### Dependencies
 
-```toml
-[tool.mypy]
-python_version = "3.13"
-strict = true
-warn_return_any = true
-warn_unused_configs = true
-disallow_untyped_defs = true
-disallow_any_generics = true
-check_untyped_defs = true
-no_implicit_optional = true
-warn_redundant_casts = true
-warn_unused_ignores = true
-
-[[tool.mypy.overrides]]
-module = "tests.*"
-disallow_untyped_defs = false
-```
+```python
+# app/dependencies.py
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import jwt, JWTError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import get_settings
+from app.database import get_db
+from app.models.user import User
+from app.repositories.user_repository import UserRepository
+from app.schemas.user import TokenPayload
+
+settings = get_settings()
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/users/login")
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
 
-**Run Commands**:
-```bash
-mypy .                             # Type check all files
-mypy --strict src/                 # Strict mode for production code
-mypy --show-column-numbers .       # Show precise error locations
+    try:
+        payload = jwt.decode(
+            token, settings.secret_key, algorithms=[settings.algorithm]
+        )
+        token_data = TokenPayload(**payload)
+
+        if token_data.type != "access":
+            raise credentials_exception
+
+    except JWTError:
+        raise credentials_exception
+
+    repository = UserRepository(db)
+    user = await repository.get_by_id(token_data.sub)
+
+    if user is None:
+        raise credentials_exception
+
+    return user
+
+async def get_current_active_user(
+    current_user: User = Depends(get_current_user),
+) -> User:
+    if not current_user.is_active:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Inactive user",
+        )
+    return current_user
+
+async def get_current_active_superuser(
+    current_user: User = Depends(get_current_active_user),
+) -> User:
+    if not current_user.is_superuser:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Insufficient permissions",
+        )
+    return current_user
 ```
 
 ---
 
-## Example 4: FastAPI 0.115.0 REST API with Async Handlers
-
-### API Server: `src/api/main.py`
+## Complete pytest Test Suite
 
 ```python
-"""FastAPI 0.115.0 application with async handlers and dependency injection."""
-from fastapi import FastAPI, HTTPException, Depends
-from fastapi.responses import JSONResponse
-from pydantic import BaseModel, Field
-from typing import Annotated
-import asyncio
-
-
-app = FastAPI(title="Product API", version="1.0.0")
-
-
-class ProductCreate(BaseModel):
-    """Product creation request schema."""
-    name: str = Field(min_length=1, max_length=100)
-    price: float = Field(gt=0)
-    stock: int = Field(ge=0)
-
-
-class ProductResponse(BaseModel):
-    """Product response schema."""
-    id: int
-    name: str
-    price: float
-    stock: int
-
+# tests/conftest.py
+import pytest
+import pytest_asyncio
+from httpx import AsyncClient, ASGITransport
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.pool import StaticPool
+
+from app.database import Base, get_db
+from app.main import app
+from app.config import get_settings
+
+settings = get_settings()
+
+@pytest.fixture(scope="session")
+def event_loop():
+    import asyncio
+    loop = asyncio.new_event_loop()
+    yield loop
+    loop.close()
+
+@pytest_asyncio.fixture(scope="session")
+async def engine():
+    engine = create_async_engine(
+        "sqlite+aiosqlite:///:memory:",
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+    )
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield engine
+    await engine.dispose()
+
+@pytest_asyncio.fixture
+async def db_session(engine):
+    async_session = sessionmaker(
+        engine, class_=AsyncSession, expire_on_commit=False
+    )
+    async with async_session() as session:
+        yield session
+        await session.rollback()
 
-# Dependency injection
-async def get_db_session():
-    """Simulated database session (replace with actual DB)."""
-    # In production: use SQLAlchemy async session
-    yield {"connection": "active"}
+@pytest_asyncio.fixture
+async def async_client(db_session):
+    async def override_get_db():
+        yield db_session
 
+    app.dependency_overrides[get_db] = override_get_db
 
-@app.get("/")
-async def root():
-    """Health check endpoint."""
-    return {"status": "ok", "version": "1.0.0"}
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        yield client
 
+    app.dependency_overrides.clear()
 
-@app.post("/products", response_model=ProductResponse, status_code=201)
-async def create_product(
-    product: ProductCreate,
-    db: Annotated[dict, Depends(get_db_session)]
-):
-    """Create a new product (async handler)."""
-    # Simulate async database operation
-    await asyncio.sleep(0.1)
-
-    # In production: insert into database
-    product_data = {
-        "id": 1,
-        "name": product.name,
-        "price": product.price,
-        "stock": product.stock,
+@pytest.fixture
+def user_data():
+    return {
+        "email": "test@example.com",
+        "name": "Test User",
+        "password": "password123",
     }
+```
 
-    return ProductResponse(**product_data)
-
-
-@app.get("/products/{product_id}", response_model=ProductResponse)
-async def get_product(
-    product_id: int,
-    db: Annotated[dict, Depends(get_db_session)]
-):
-    """Retrieve product by ID (async handler)."""
-    # Simulate async database lookup
-    await asyncio.sleep(0.1)
-
-    # In production: query from database
-    if product_id == 999:
-        raise HTTPException(status_code=404, detail="Product not found")
-
-    return ProductResponse(id=product_id, name="Sample Product", price=29.99, stock=100)
+```python
+# tests/test_users.py
+import pytest
+from httpx import AsyncClient
 
+@pytest.mark.asyncio
+async def test_register_user(async_client: AsyncClient, user_data: dict):
+    response = await async_client.post("/api/v1/users/register", json=user_data)
 
-@app.exception_handler(ValueError)
-async def value_error_handler(request, exc):
-    """Global exception handler for ValueError."""
-    return JSONResponse(
-        status_code=400,
-        content={"error": "Validation failed", "detail": str(exc)},
-    )
-```
+    assert response.status_code == 201
+    data = response.json()
+    assert data["email"] == user_data["email"]
+    assert data["name"] == user_data["name"]
+    assert "id" in data
+    assert "password" not in data
 
-### Test File: `tests/test_api.py`
+@pytest.mark.asyncio
+async def test_register_duplicate_email(async_client: AsyncClient, user_data: dict):
+    # First registration
+    await async_client.post("/api/v1/users/register", json=user_data)
 
-```python
-"""Tests for FastAPI endpoints using pytest-asyncio."""
-import pytest
-from httpx import AsyncClient, ASGITransport
-from src.api.main import app
+    # Second registration with same email
+    response = await async_client.post("/api/v1/users/register", json=user_data)
 
+    assert response.status_code == 400
+    assert "already registered" in response.json()["detail"]
 
 @pytest.mark.asyncio
-async def test_root_endpoint():
-    """Test health check endpoint."""
-    async with AsyncClient(
-        transport=ASGITransport(app=app),
-        base_url="http://test"
-    ) as client:
-        response = await client.get("/")
-        assert response.status_code == 200
-        assert response.json() == {"status": "ok", "version": "1.0.0"}
+@pytest.mark.parametrize(
+    "invalid_data,expected_detail",
+    [
+        ({"email": "invalid", "name": "Test", "password": "pass123"}, "email"),
+        ({"email": "test@example.com", "name": "", "password": "pass123"}, "name"),
+        ({"email": "test@example.com", "name": "Test", "password": "short"}, "password"),
+    ],
+    ids=["invalid_email", "empty_name", "short_password"],
+)
+async def test_register_validation(
+    async_client: AsyncClient,
+    invalid_data: dict,
+    expected_detail: str,
+):
+    response = await async_client.post("/api/v1/users/register", json=invalid_data)
 
+    assert response.status_code == 422
 
 @pytest.mark.asyncio
-async def test_create_product():
-    """Test product creation endpoint."""
-    async with AsyncClient(
-        transport=ASGITransport(app=app),
-        base_url="http://test"
-    ) as client:
-        response = await client.post("/products", json={
-            "name": "Test Product",
-            "price": 19.99,
-            "stock": 50,
-        })
-        assert response.status_code == 201
-        data = response.json()
-        assert data["name"] == "Test Product"
-        assert data["price"] == 19.99
+async def test_login_success(async_client: AsyncClient, user_data: dict):
+    # Register user first
+    await async_client.post("/api/v1/users/register", json=user_data)
+
+    # Login
+    response = await async_client.post(
+        "/api/v1/users/login",
+        params={"email": user_data["email"], "password": user_data["password"]},
+    )
 
+    assert response.status_code == 200
+    data = response.json()
+    assert "access_token" in data
+    assert "refresh_token" in data
+    assert data["token_type"] == "bearer"
 
 @pytest.mark.asyncio
-async def test_get_product_not_found():
-    """Test product retrieval with non-existent ID."""
-    async with AsyncClient(
-        transport=ASGITransport(app=app),
-        base_url="http://test"
-    ) as client:
-        response = await client.get("/products/999")
-        assert response.status_code == 404
-```
+async def test_get_current_user(async_client: AsyncClient, user_data: dict):
+    # Register and login
+    await async_client.post("/api/v1/users/register", json=user_data)
+    login_response = await async_client.post(
+        "/api/v1/users/login",
+        params={"email": user_data["email"], "password": user_data["password"]},
+    )
+    token = login_response.json()["access_token"]
 
-**Run Commands**:
-```bash
-# Start development server
-uvicorn src.api.main:app --reload
+    # Get current user
+    response = await async_client.get(
+        "/api/v1/users/me",
+        headers={"Authorization": f"Bearer {token}"},
+    )
 
-# Run tests
-pytest tests/test_api.py -v --cov=src.api
+    assert response.status_code == 200
+    data = response.json()
+    assert data["email"] == user_data["email"]
 ```
 
 ---
 
-## Example 5: asyncio.TaskGroup Concurrent Pattern (Python 3.13)
+## Async Patterns Examples
 
-### Concurrent Operations: `src/services/data_fetcher.py`
+### Task Groups (Python 3.11+)
 
 ```python
-"""Data fetching service using Python 3.13 asyncio.TaskGroup."""
 import asyncio
 from typing import Any
-import httpx
-
-
-class DataFetcher:
-    """Fetch data from multiple sources concurrently using TaskGroup."""
-
-    def __init__(self, base_url: str):
-        self.base_url = base_url
-
-    async def fetch_user(self, user_id: int) -> dict[str, Any]:
-        """Fetch user data from API."""
-        await asyncio.sleep(0.1)  # Simulate network delay
-        return {"id": user_id, "name": f"User{user_id}"}
-
-    async def fetch_posts(self, user_id: int) -> list[dict[str, Any]]:
-        """Fetch user posts from API."""
-        await asyncio.sleep(0.15)  # Simulate network delay
-        return [
-            {"id": 1, "user_id": user_id, "title": "Post 1"},
-            {"id": 2, "user_id": user_id, "title": "Post 2"},
-        ]
-
-    async def fetch_comments(self, user_id: int) -> list[dict[str, Any]]:
-        """Fetch user comments from API."""
-        await asyncio.sleep(0.12)  # Simulate network delay
-        return [
-            {"id": 1, "user_id": user_id, "text": "Comment 1"},
-        ]
-
-    async def fetch_user_profile(self, user_id: int) -> dict[str, Any]:
-        """
-        Fetch complete user profile concurrently using TaskGroup.
-
-        TaskGroup advantages over asyncio.gather:
-        - Automatic exception propagation
-        - Structured concurrency (cancellation safety)
-        - Cleaner error handling
-        """
-        async with asyncio.TaskGroup() as tg:
-            user_task = tg.create_task(self.fetch_user(user_id))
-            posts_task = tg.create_task(self.fetch_posts(user_id))
-            comments_task = tg.create_task(self.fetch_comments(user_id))
-            # All tasks run concurrently here
-            # If any task fails, TaskGroup cancels others and raises
-
-        # After TaskGroup exits, all tasks are complete
-        return {
-            "user": user_task.result(),
-            "posts": posts_task.result(),
-            "comments": comments_task.result(),
-        }
-
-    async def fetch_multiple_users(self, user_ids: list[int]) -> list[dict[str, Any]]:
-        """Fetch multiple user profiles concurrently."""
-        async with asyncio.TaskGroup() as tg:
-            tasks = [
-                tg.create_task(self.fetch_user_profile(user_id))
-                for user_id in user_ids
-            ]
-
-        return [task.result() for task in tasks]
-
-
-# Context Variables for request tracking
-from contextvars import ContextVar
-
-request_id_var: ContextVar[str | None] = ContextVar("request_id", default=None)
-
-
-async def process_request(request_id: str) -> dict[str, Any]:
-    """Process request with context variable tracking."""
-    # Set context variable (inherited by all spawned tasks)
-    token = request_id_var.set(request_id)
 
-    try:
-        fetcher = DataFetcher(base_url="https://api.example.com")
-        result = await fetcher.fetch_user_profile(user_id=1)
+async def fetch_user(user_id: int) -> dict:
+    await asyncio.sleep(0.1)  # Simulate API call
+    return {"id": user_id, "name": f"User {user_id}"}
+
+async def fetch_all_users(user_ids: list[int]) -> list[dict]:
+    async with asyncio.TaskGroup() as tg:
+        tasks = [tg.create_task(fetch_user(uid)) for uid in user_ids]
 
-        # Log with request ID (available in all async contexts)
-        current_request_id = request_id_var.get()
-        print(f"Request {current_request_id} completed")
+    return [task.result() for task in tasks]
 
-        return result
-    finally:
-        request_id_var.reset(token)
+# Exception handling with TaskGroup
+async def fetch_with_error_handling(user_ids: list[int]) -> tuple[list[dict], list[Exception]]:
+    results = []
+    errors = []
 
+    async def safe_fetch(user_id: int):
+        try:
+            result = await fetch_user(user_id)
+            results.append(result)
+        except Exception as e:
+            errors.append(e)
 
-# Main execution
-async def main():
-    """Example usage of DataFetcher with TaskGroup."""
-    fetcher = DataFetcher(base_url="https://api.example.com")
+    async with asyncio.TaskGroup() as tg:
+        for uid in user_ids:
+            tg.create_task(safe_fetch(uid))
 
-    # Fetch single user profile
-    profile = await fetcher.fetch_user_profile(user_id=1)
-    print(f"Profile: {profile}")
+    return results, errors
+```
 
-    # Fetch multiple users concurrently
-    profiles = await fetcher.fetch_multiple_users([1, 2, 3])
-    print(f"Fetched {len(profiles)} profiles")
+### Semaphore for Rate Limiting
 
-    # Process request with context tracking
-    result = await process_request(request_id="req-12345")
-    print(f"Result: {result}")
+```python
+import asyncio
+from contextlib import asynccontextmanager
 
+class RateLimiter:
+    def __init__(self, max_concurrent: int = 10):
+        self._semaphore = asyncio.Semaphore(max_concurrent)
 
-if __name__ == "__main__":
-    asyncio.run(main())
+    @asynccontextmanager
+    async def acquire(self):
+        async with self._semaphore:
+            yield
+
+rate_limiter = RateLimiter(max_concurrent=5)
+
+async def rate_limited_fetch(url: str) -> dict:
+    async with rate_limiter.acquire():
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url)
+            return response.json()
 ```
 
-### Test File: `tests/test_data_fetcher.py`
+### Async Generator Streaming
 
 ```python
-"""Tests for DataFetcher using pytest-asyncio."""
-import pytest
-from src.services.data_fetcher import DataFetcher
+from typing import AsyncGenerator
+
+async def stream_large_data(
+    db: AsyncSession,
+    batch_size: int = 1000,
+) -> AsyncGenerator[list[User], None]:
+    offset = 0
+    while True:
+        result = await db.execute(
+            select(User)
+            .offset(offset)
+            .limit(batch_size)
+            .order_by(User.id)
+        )
+        users = result.scalars().all()
+
+        if not users:
+            break
+
+        yield users
+        offset += batch_size
+
+# Usage
+async def process_all_users(db: AsyncSession):
+    async for batch in stream_large_data(db):
+        for user in batch:
+            await process_user(user)
+```
 
+---
 
-@pytest.mark.asyncio
-async def test_fetch_user_profile():
-    """Test concurrent user profile fetching."""
-    fetcher = DataFetcher(base_url="https://api.example.com")
-    profile = await fetcher.fetch_user_profile(user_id=1)
+## Docker Production Dockerfile
 
-    assert "user" in profile
-    assert "posts" in profile
-    assert "comments" in profile
-    assert profile["user"]["id"] == 1
+```dockerfile
+# Dockerfile
+FROM python:3.13-slim AS builder
 
+WORKDIR /app
 
-@pytest.mark.asyncio
-async def test_fetch_multiple_users():
-    """Test fetching multiple user profiles concurrently."""
-    fetcher = DataFetcher(base_url="https://api.example.com")
-    profiles = await fetcher.fetch_multiple_users([1, 2, 3])
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
 
-    assert len(profiles) == 3
-    assert all("user" in p for p in profiles)
+# Install Python dependencies
+COPY pyproject.toml poetry.lock ./
+RUN pip install poetry && \
+    poetry config virtualenvs.create false && \
+    poetry install --no-dev --no-interaction --no-ansi
 
+FROM python:3.13-slim AS runtime
 
-@pytest.mark.asyncio
-async def test_taskgroup_error_propagation():
-    """Test that TaskGroup properly propagates exceptions."""
-    fetcher = DataFetcher(base_url="https://api.example.com")
+WORKDIR /app
 
-    # Override method to raise error
-    async def failing_fetch(user_id: int):
-        raise ValueError("Simulated error")
+# Create non-root user
+RUN addgroup --system --gid 1001 appgroup && \
+    adduser --system --uid 1001 --gid 1001 appuser
 
-    fetcher.fetch_user = failing_fetch
+# Copy dependencies from builder
+COPY --from=builder /usr/local/lib/python3.13/site-packages /usr/local/lib/python3.13/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
 
-    with pytest.raises(ValueError, match="Simulated error"):
-        await fetcher.fetch_user_profile(user_id=1)
-```
+# Copy application code
+COPY --chown=appuser:appgroup . .
 
-**Run Commands**:
-```bash
-# Run the example
-python -m src.services.data_fetcher
+# Switch to non-root user
+USER appuser
 
-# Run tests
-pytest tests/test_data_fetcher.py -v --cov=src.services
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import httpx; httpx.get('http://localhost:8000/health')"
+
+# Run application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]
 ```
 
 ---
 
-## Quick Reference
+## pyproject.toml Complete Configuration
 
-### Setup New Project (uv 0.9.3)
-
-```bash
-# Create project with Python 3.13
-uv venv --python 3.13
-source .venv/bin/activate
+```toml
+[tool.poetry]
+name = "fastapi-app"
+version = "1.0.0"
+description = "Production FastAPI Application"
+authors = ["Developer <dev@example.com>"]
+python = "^3.13"
+
+[tool.poetry.dependencies]
+python = "^3.13"
+fastapi = "^0.115.0"
+uvicorn = {extras = ["standard"], version = "^0.32.0"}
+pydantic = "^2.9.0"
+pydantic-settings = "^2.6.0"
+sqlalchemy = {extras = ["asyncio"], version = "^2.0.0"}
+asyncpg = "^0.30.0"
+python-jose = {extras = ["cryptography"], version = "^3.3.0"}
+passlib = {extras = ["bcrypt"], version = "^1.7.4"}
+httpx = "^0.28.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.0"
+pytest-asyncio = "^0.24.0"
+pytest-cov = "^6.0.0"
+aiosqlite = "^0.20.0"
+ruff = "^0.8.0"
+mypy = "^1.13.0"
 
-# Install dependencies
-uv add pytest pytest-asyncio ruff mypy fastapi uvicorn httpx pydantic
+[tool.ruff]
+line-length = 100
+target-version = "py313"
 
-# Add development dependencies
-uv add --dev pytest-cov pytest-mock
-```
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "C4", "SIM"]
+ignore = ["E501"]
 
-### Quality Gate Commands
+[tool.ruff.lint.isort]
+known-first-party = ["app"]
 
-```bash
-# Run all tests with coverage
-pytest --cov=src --cov-report=term-missing --cov-report=html
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "-v --tb=short --cov=app --cov-report=term-missing"
 
-# Lint and format
-ruff check . --fix
-ruff format .
+[tool.mypy]
+python_version = "3.13"
+strict = true
+plugins = ["pydantic.mypy"]
 
-# Type check
-mypy --strict src/
+[tool.coverage.run]
+source = ["app"]
+omit = ["tests/*"]
 
-# Full quality gate (run before commit)
-pytest --cov=src --cov-report=term && ruff check . && mypy .
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
 ```
 
-### Production Dependencies Matrix
-
-| Package | Version | Purpose |
-|---------|---------|---------|
-| pytest | 8.4.2 | Testing framework |
-| pytest-asyncio | latest | Async test support |
-| pytest-cov | latest | Coverage reporting |
-| ruff | 0.13.1 | Linting & formatting |
-| mypy | 1.8.0 | Static type checking |
-| uv | 0.9.3 | Package management |
-| FastAPI | 0.115.0 | Web framework |
-| Pydantic | 2.7.0 | Data validation |
-| httpx | latest | Async HTTP client |
-| uvicorn | latest | ASGI server |
-
 ---
 
-All examples are tested against Python 3.13.1 and follow MoAI-ADK TRUST 5 principles.
+Last Updated: 2025-12-07
+Version: 1.0.0