@baselane/packs 0.1.4 → 0.1.5

package/packs/python-rules/rendered/GEMINI.md

@@ -1,3 +1,3451 @@
 # GEMINI.md
 
 @AGENTS.md
+
+## Skills
+
+### python-patterns
+
+Pythonic idioms, type hints, error handling, context managers, comprehensions/generators, dataclasses, decorators, concurrency, package layout, and anti-patterns. Use when writing, reviewing, or refactoring Python code, or designing a package/module layout.
+
+# Python Development Patterns
+
+Idiomatic Python patterns and best practices for building robust, efficient, and maintainable applications.
+
+## When to Activate
+
+- Writing new Python code
+- Reviewing Python code
+- Refactoring existing Python code
+- Designing Python packages/modules
+
+## Core Principles
+
+### 1. Readability Counts
+
+Python prioritizes readability. Code should be obvious and easy to understand.
+
+```python
+# Good: Clear and readable
+def get_active_users(users: list[User]) -> list[User]:
+    """Return only active users from the provided list."""
+    return [user for user in users if user.is_active]
+
+
+# Bad: Clever but confusing
+def get_active_users(u):
+    return [x for x in u if x.a]
+```
+
+### 2. Explicit is Better Than Implicit
+
+Avoid magic; be clear about what your code does.
+
+```python
+# Good: Explicit configuration
+import logging
+
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+# Bad: Hidden side effects
+import some_module
+some_module.setup()  # What does this do?
+```
+
+### 3. EAFP - Easier to Ask Forgiveness Than Permission
+
+Python prefers exception handling over checking conditions.
+
+```python
+# Good: EAFP style
+def get_value(dictionary: dict, key: str, default_value: Any = None) -> Any:
+    try:
+        return dictionary[key]
+    except KeyError:
+        return default_value
+
+# Bad: LBYL (Look Before You Leap) style
+def get_value(dictionary: dict, key: str, default_value: Any = None) -> Any:
+    if key in dictionary:
+        return dictionary[key]
+    else:
+        return default_value
+```
+
+## Type Hints
+
+### Basic Type Annotations
+
+```python
+from typing import Optional, List, Dict, Any
+
+def process_user(
+    user_id: str,
+    data: Dict[str, Any],
+    active: bool = True
+) -> Optional[User]:
+    """Process a user and return the updated User or None."""
+    if not active:
+        return None
+    return User(user_id, data)
+```
+
+### Modern Type Hints (Python 3.9+)
+
+```python
+# Python 3.9+ - Use built-in types
+def process_items(items: list[str]) -> dict[str, int]:
+    return {item: len(item) for item in items}
+
+# Python 3.8 and earlier - Use typing module
+from typing import List, Dict
+
+def process_items(items: List[str]) -> Dict[str, int]:
+    return {item: len(item) for item in items}
+```
+
+### Type Aliases and TypeVar
+
+```python
+from typing import TypeVar, Union
+
+# Type alias for complex types
+JSON = Union[dict[str, Any], list[Any], str, int, float, bool, None]
+
+def parse_json(data: str) -> JSON:
+    return json.loads(data)
+
+# Generic types
+T = TypeVar('T')
+
+def first(items: list[T]) -> T | None:
+    """Return the first item or None if list is empty."""
+    return items[0] if items else None
+```
+
+### Protocol-Based Duck Typing
+
+```python
+from typing import Protocol
+
+class Renderable(Protocol):
+    def render(self) -> str:
+        """Render the object to a string."""
+
+def render_all(items: list[Renderable]) -> str:
+    """Render all items that implement the Renderable protocol."""
+    return "\n".join(item.render() for item in items)
+```
+
+## Error Handling Patterns
+
+### Specific Exception Handling
+
+```python
+# Good: Catch specific exceptions
+def load_config(path: str) -> Config:
+    try:
+        with open(path) as f:
+            return Config.from_json(f.read())
+    except FileNotFoundError as e:
+        raise ConfigError(f"Config file not found: {path}") from e
+    except json.JSONDecodeError as e:
+        raise ConfigError(f"Invalid JSON in config: {path}") from e
+
+# Bad: Bare except
+def load_config(path: str) -> Config:
+    try:
+        with open(path) as f:
+            return Config.from_json(f.read())
+    except:
+        return None  # Silent failure!
+```
+
+### Exception Chaining
+
+```python
+def process_data(data: str) -> Result:
+    try:
+        parsed = json.loads(data)
+    except json.JSONDecodeError as e:
+        # Chain exceptions to preserve the traceback
+        raise ValueError(f"Failed to parse data: {data}") from e
+```
+
+### Custom Exception Hierarchy
+
+```python
+class AppError(Exception):
+    """Base exception for all application errors."""
+    pass
+
+class ValidationError(AppError):
+    """Raised when input validation fails."""
+    pass
+
+class NotFoundError(AppError):
+    """Raised when a requested resource is not found."""
+    pass
+
+# Usage
+def get_user(user_id: str) -> User:
+    user = db.find_user(user_id)
+    if not user:
+        raise NotFoundError(f"User not found: {user_id}")
+    return user
+```
+
+## Context Managers
+
+### Resource Management
+
+```python
+# Good: Using context managers
+def process_file(path: str) -> str:
+    with open(path, 'r') as f:
+        return f.read()
+
+# Bad: Manual resource management
+def process_file(path: str) -> str:
+    f = open(path, 'r')
+    try:
+        return f.read()
+    finally:
+        f.close()
+```
+
+### Custom Context Managers
+
+```python
+from contextlib import contextmanager
+
+@contextmanager
+def timer(name: str):
+    """Context manager to time a block of code."""
+    start = time.perf_counter()
+    yield
+    elapsed = time.perf_counter() - start
+    print(f"{name} took {elapsed:.4f} seconds")
+
+# Usage
+with timer("data processing"):
+    process_large_dataset()
+```
+
+### Context Manager Classes
+
+```python
+class DatabaseTransaction:
+    def __init__(self, connection):
+        self.connection = connection
+
+    def __enter__(self):
+        self.connection.begin_transaction()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type is None:
+            self.connection.commit()
+        else:
+            self.connection.rollback()
+        return False  # Don't suppress exceptions
+
+# Usage
+with DatabaseTransaction(conn):
+    user = conn.create_user(user_data)
+    conn.create_profile(user.id, profile_data)
+```
+
+## Comprehensions and Generators
+
+### List Comprehensions
+
+```python
+# Good: List comprehension for simple transformations
+names = [user.name for user in users if user.is_active]
+
+# Bad: Manual loop
+names = []
+for user in users:
+    if user.is_active:
+        names.append(user.name)
+
+# Complex comprehensions should be expanded
+# Bad: Too complex
+result = [x * 2 for x in items if x > 0 if x % 2 == 0]
+
+# Good: Use a generator function
+def filter_and_transform(items: Iterable[int]) -> list[int]:
+    result = []
+    for x in items:
+        if x > 0 and x % 2 == 0:
+            result.append(x * 2)
+    return result
+```
+
+### Generator Expressions
+
+```python
+# Good: Generator for lazy evaluation
+total = sum(x * x for x in range(1_000_000))
+
+# Bad: Creates large intermediate list
+total = sum([x * x for x in range(1_000_000)])
+```
+
+### Generator Functions
+
+```python
+def read_large_file(path: str) -> Iterator[str]:
+    """Read a large file line by line."""
+    with open(path) as f:
+        for line in f:
+            yield line.strip()
+
+# Usage
+for line in read_large_file("huge.txt"):
+    process(line)
+```
+
+## Data Classes and Named Tuples
+
+### Data Classes
+
+```python
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class User:
+    """User entity with automatic __init__, __repr__, and __eq__."""
+    id: str
+    name: str
+    email: str
+    created_at: datetime = field(default_factory=datetime.now)
+    is_active: bool = True
+
+# Usage
+user = User(
+    id="123",
+    name="Alice",
+    email="alice@example.com"
+)
+```
+
+### Data Classes with Validation
+
+```python
+@dataclass
+class User:
+    email: str
+    age: int
+
+    def __post_init__(self):
+        # Validate email format
+        if "@" not in self.email:
+            raise ValueError(f"Invalid email: {self.email}")
+        # Validate age range
+        if self.age < 0 or self.age > 150:
+            raise ValueError(f"Invalid age: {self.age}")
+```
+
+### Named Tuples
+
+```python
+from typing import NamedTuple
+
+class Point(NamedTuple):
+    """Immutable 2D point."""
+    x: float
+    y: float
+
+    def distance(self, other: 'Point') -> float:
+        return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5
+
+# Usage
+p1 = Point(0, 0)
+p2 = Point(3, 4)
+print(p1.distance(p2))  # 5.0
+```
+
+## Decorators
+
+### Function Decorators
+
+```python
+import functools
+import time
+
+def timer(func: Callable) -> Callable:
+    """Decorator to time function execution."""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        start = time.perf_counter()
+        result = func(*args, **kwargs)
+        elapsed = time.perf_counter() - start
+        print(f"{func.__name__} took {elapsed:.4f}s")
+        return result
+    return wrapper
+
+@timer
+def slow_function():
+    time.sleep(1)
+
+# slow_function() prints: slow_function took 1.0012s
+```
+
+### Parameterized Decorators
+
+```python
+def repeat(times: int):
+    """Decorator to repeat a function multiple times."""
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            results = []
+            for _ in range(times):
+                results.append(func(*args, **kwargs))
+            return results
+        return wrapper
+    return decorator
+
+@repeat(times=3)
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# greet("Alice") returns ["Hello, Alice!", "Hello, Alice!", "Hello, Alice!"]
+```
+
+### Class-Based Decorators
+
+```python
+class CountCalls:
+    """Decorator that counts how many times a function is called."""
+    def __init__(self, func: Callable):
+        functools.update_wrapper(self, func)
+        self.func = func
+        self.count = 0
+
+    def __call__(self, *args, **kwargs):
+        self.count += 1
+        print(f"{self.func.__name__} has been called {self.count} times")
+        return self.func(*args, **kwargs)
+
+@CountCalls
+def process():
+    pass
+
+# Each call to process() prints the call count
+```
+
+## Concurrency Patterns
+
+### Threading for I/O-Bound Tasks
+
+```python
+import concurrent.futures
+import threading
+
+def fetch_url(url: str) -> str:
+    """Fetch a URL (I/O-bound operation)."""
+    import urllib.request
+    with urllib.request.urlopen(url) as response:
+        return response.read().decode()
+
+def fetch_all_urls(urls: list[str]) -> dict[str, str]:
+    """Fetch multiple URLs concurrently using threads."""
+    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
+        future_to_url = {executor.submit(fetch_url, url): url for url in urls}
+        results = {}
+        for future in concurrent.futures.as_completed(future_to_url):
+            url = future_to_url[future]
+            try:
+                results[url] = future.result()
+            except Exception as e:
+                results[url] = f"Error: {e}"
+    return results
+```
+
+### Multiprocessing for CPU-Bound Tasks
+
+```python
+def process_data(data: list[int]) -> int:
+    """CPU-intensive computation."""
+    return sum(x ** 2 for x in data)
+
+def process_all(datasets: list[list[int]]) -> list[int]:
+    """Process multiple datasets using multiple processes."""
+    with concurrent.futures.ProcessPoolExecutor() as executor:
+        results = list(executor.map(process_data, datasets))
+    return results
+```
+
+### Async/Await for Concurrent I/O
+
+```python
+import asyncio
+
+async def fetch_async(url: str) -> str:
+    """Fetch a URL asynchronously."""
+    import aiohttp
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.text()
+
+async def fetch_all(urls: list[str]) -> dict[str, str]:
+    """Fetch multiple URLs concurrently."""
+    tasks = [fetch_async(url) for url in urls]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+    return dict(zip(urls, results))
+```
+
+## Package Organization
+
+### Standard Project Layout
+
+```
+myproject/
+├── src/
+│   └── mypackage/
+│       ├── __init__.py
+│       ├── main.py
+│       ├── api/
+│       │   ├── __init__.py
+│       │   └── routes.py
+│       ├── models/
+│       │   ├── __init__.py
+│       │   └── user.py
+│       └── utils/
+│           ├── __init__.py
+│           └── helpers.py
+├── tests/
+│   ├── __init__.py
+│   ├── conftest.py
+│   ├── test_api.py
+│   └── test_models.py
+├── pyproject.toml
+├── README.md
+└── .gitignore
+```
+
+### Import Conventions
+
+```python
+# Good: Import order - stdlib, third-party, local
+import os
+import sys
+from pathlib import Path
+
+import requests
+from fastapi import FastAPI
+
+from mypackage.models import User
+from mypackage.utils import format_name
+
+# Good: Use isort for automatic import sorting
+# pip install isort
+```
+
+### __init__.py for Package Exports
+
+```python
+# mypackage/__init__.py
+"""mypackage - A sample Python package."""
+
+__version__ = "1.0.0"
+
+# Export main classes/functions at package level
+from mypackage.models import User, Post
+from mypackage.utils import format_name
+
+__all__ = ["User", "Post", "format_name"]
+```
+
+## Memory and Performance
+
+### Using __slots__ for Memory Efficiency
+
+```python
+# Bad: Regular class uses __dict__ (more memory)
+class Point:
+    def __init__(self, x: float, y: float):
+        self.x = x
+        self.y = y
+
+# Good: __slots__ reduces memory usage
+class Point:
+    __slots__ = ['x', 'y']
+
+    def __init__(self, x: float, y: float):
+        self.x = x
+        self.y = y
+```
+
+### Generator for Large Data
+
+```python
+# Bad: Returns full list in memory
+def read_lines(path: str) -> list[str]:
+    with open(path) as f:
+        return [line.strip() for line in f]
+
+# Good: Yields lines one at a time
+def read_lines(path: str) -> Iterator[str]:
+    with open(path) as f:
+        for line in f:
+            yield line.strip()
+```
+
+### Avoid String Concatenation in Loops
+
+```python
+# Bad: O(n²) due to string immutability
+result = ""
+for item in items:
+    result += str(item)
+
+# Good: O(n) using join
+result = "".join(str(item) for item in items)
+
+# Good: Using StringIO for building
+from io import StringIO
+
+buffer = StringIO()
+for item in items:
+    buffer.write(str(item))
+result = buffer.getvalue()
+```
+
+## Python Tooling Integration
+
+### Essential Commands
+
+```bash
+# Code formatting
+black .
+isort .
+
+# Linting
+ruff check .
+pylint mypackage/
+
+# Type checking
+mypy .
+
+# Testing
+pytest --cov=mypackage --cov-report=html
+
+# Security scanning
+bandit -r .
+
+# Dependency management
+pip-audit
+safety check
+```
+
+### pyproject.toml Configuration
+
+```toml
+[project]
+name = "mypackage"
+version = "1.0.0"
+requires-python = ">=3.9"
+dependencies = [
+    "requests>=2.31.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py39']
+
+[tool.ruff]
+line-length = 88
+select = ["E", "F", "I", "N", "W"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=mypackage --cov-report=term-missing"
+```
+
+## Quick Reference: Python Idioms
+
+| Idiom | Description |
+|-------|-------------|
+| EAFP | Easier to Ask Forgiveness than Permission |
+| Context managers | Use `with` for resource management |
+| List comprehensions | For simple transformations |
+| Generators | For lazy evaluation and large datasets |
+| Type hints | Annotate function signatures |
+| Dataclasses | For data containers with auto-generated methods |
+| `__slots__` | For memory optimization |
+| f-strings | For string formatting (Python 3.6+) |
+| `pathlib.Path` | For path operations (Python 3.4+) |
+| `enumerate` | For index-element pairs in loops |
+
+## Anti-Patterns to Avoid
+
+```python
+# Bad: Mutable default arguments
+def append_to(item, items=[]):
+    items.append(item)
+    return items
+
+# Good: Use None and create new list
+def append_to(item, items=None):
+    if items is None:
+        items = []
+    items.append(item)
+    return items
+
+# Bad: Checking type with type()
+if type(obj) == list:
+    process(obj)
+
+# Good: Use isinstance
+if isinstance(obj, list):
+    process(obj)
+
+# Bad: Comparing to None with ==
+if value == None:
+    process()
+
+# Good: Use is
+if value is None:
+    process()
+
+# Bad: from module import *
+from os.path import *
+
+# Good: Explicit imports
+from os.path import join, exists
+
+# Bad: Bare except
+try:
+    risky_operation()
+except:
+    pass
+
+# Good: Specific exception
+try:
+    risky_operation()
+except SpecificError as e:
+    logger.error(f"Operation failed: {e}")
+```
+
+__Remember__: Python code should be readable, explicit, and follow the principle of least surprise. When in doubt, prioritize clarity over cleverness.
+
+### python-testing
+
+pytest fundamentals, fixtures (scopes, params, autouse, conftest), parametrization, mocking/patching, async test patterns, and TDD methodology with coverage targets. Use when writing or reviewing Python tests, or setting up a pytest suite.
+
+# Python Testing Patterns
+
+Comprehensive testing strategies for Python applications using pytest, TDD methodology, and best practices.
+
+## When to Activate
+
+- Writing new Python code (follow TDD: red, green, refactor)
+- Designing test suites for Python projects
+- Reviewing Python test coverage
+- Setting up testing infrastructure
+
+## Core Testing Philosophy
+
+### Test-Driven Development (TDD)
+
+Always follow the TDD cycle:
+
+1. **RED**: Write a failing test for the desired behavior
+2. **GREEN**: Write minimal code to make the test pass
+3. **REFACTOR**: Improve code while keeping tests green
+
+```python
+# Step 1: Write failing test (RED)
+def test_add_numbers():
+    result = add(2, 3)
+    assert result == 5
+
+# Step 2: Write minimal implementation (GREEN)
+def add(a, b):
+    return a + b
+
+# Step 3: Refactor if needed (REFACTOR)
+```
+
+### Coverage Requirements
+
+- **Target**: 80%+ code coverage
+- **Critical paths**: 100% coverage required
+- Use `pytest --cov` to measure coverage
+
+```bash
+pytest --cov=mypackage --cov-report=term-missing --cov-report=html
+```
+
+## pytest Fundamentals
+
+### Basic Test Structure
+
+```python
+import pytest
+
+def test_addition():
+    """Test basic addition."""
+    assert 2 + 2 == 4
+
+def test_string_uppercase():
+    """Test string uppercasing."""
+    text = "hello"
+    assert text.upper() == "HELLO"
+
+def test_list_append():
+    """Test list append."""
+    items = [1, 2, 3]
+    items.append(4)
+    assert 4 in items
+    assert len(items) == 4
+```
+
+### Assertions
+
+```python
+# Equality
+assert result == expected
+
+# Inequality
+assert result != unexpected
+
+# Truthiness
+assert result  # Truthy
+assert not result  # Falsy
+assert result is True  # Exactly True
+assert result is False  # Exactly False
+assert result is None  # Exactly None
+
+# Membership
+assert item in collection
+assert item not in collection
+
+# Comparisons
+assert result > 0
+assert 0 <= result <= 100
+
+# Type checking
+assert isinstance(result, str)
+
+# Exception testing (preferred approach)
+with pytest.raises(ValueError):
+    raise ValueError("error message")
+
+# Check exception message
+with pytest.raises(ValueError, match="invalid input"):
+    raise ValueError("invalid input provided")
+
+# Check exception attributes
+with pytest.raises(ValueError) as exc_info:
+    raise ValueError("error message")
+assert str(exc_info.value) == "error message"
+```
+
+## Fixtures
+
+### Basic Fixture Usage
+
+```python
+import pytest
+
+@pytest.fixture
+def sample_data():
+    """Fixture providing sample data."""
+    return {"name": "Alice", "age": 30}
+
+def test_sample_data(sample_data):
+    """Test using the fixture."""
+    assert sample_data["name"] == "Alice"
+    assert sample_data["age"] == 30
+```
+
+### Fixture with Setup/Teardown
+
+```python
+@pytest.fixture
+def database():
+    """Fixture with setup and teardown."""
+    # Setup
+    db = Database(":memory:")
+    db.create_tables()
+    db.insert_test_data()
+
+    yield db  # Provide to test
+
+    # Teardown
+    db.close()
+
+def test_database_query(database):
+    """Test database operations."""
+    result = database.query("SELECT * FROM users")
+    assert len(result) > 0
+```
+
+### Fixture Scopes
+
+```python
+# Function scope (default) - runs for each test
+@pytest.fixture
+def temp_file():
+    with open("temp.txt", "w") as f:
+        yield f
+    os.remove("temp.txt")
+
+# Module scope - runs once per module
+@pytest.fixture(scope="module")
+def module_db():
+    db = Database(":memory:")
+    db.create_tables()
+    yield db
+    db.close()
+
+# Session scope - runs once per test session
+@pytest.fixture(scope="session")
+def shared_resource():
+    resource = ExpensiveResource()
+    yield resource
+    resource.cleanup()
+```
+
+### Fixture with Parameters
+
+```python
+@pytest.fixture(params=[1, 2, 3])
+def number(request):
+    """Parameterized fixture."""
+    return request.param
+
+def test_numbers(number):
+    """Test runs 3 times, once for each parameter."""
+    assert number > 0
+```
+
+### Using Multiple Fixtures
+
+```python
+@pytest.fixture
+def user():
+    return User(id=1, name="Alice")
+
+@pytest.fixture
+def admin():
+    return User(id=2, name="Admin", role="admin")
+
+def test_user_admin_interaction(user, admin):
+    """Test using multiple fixtures."""
+    assert admin.can_manage(user)
+```
+
+### Autouse Fixtures
+
+```python
+@pytest.fixture(autouse=True)
+def reset_config():
+    """Automatically runs before every test."""
+    Config.reset()
+    yield
+    Config.cleanup()
+
+def test_without_fixture_call():
+    # reset_config runs automatically
+    assert Config.get_setting("debug") is False
+```
+
+### Conftest.py for Shared Fixtures
+
+```python
+# tests/conftest.py
+import pytest
+
+@pytest.fixture
+def client():
+    """Shared fixture for all tests."""
+    app = create_app(testing=True)
+    with app.test_client() as client:
+        yield client
+
+@pytest.fixture
+def auth_headers(client):
+    """Generate auth headers for API testing."""
+    response = client.post("/api/login", json={
+        "username": "test",
+        "password": "test"
+    })
+    token = response.json["token"]
+    return {"Authorization": f"Bearer {token}"}
+```
+
+## Parametrization
+
+### Basic Parametrization
+
+```python
+@pytest.mark.parametrize("input,expected", [
+    ("hello", "HELLO"),
+    ("world", "WORLD"),
+    ("PyThOn", "PYTHON"),
+])
+def test_uppercase(input, expected):
+    """Test runs 3 times with different inputs."""
+    assert input.upper() == expected
+```
+
+### Multiple Parameters
+
+```python
+@pytest.mark.parametrize("a,b,expected", [
+    (2, 3, 5),
+    (0, 0, 0),
+    (-1, 1, 0),
+    (100, 200, 300),
+])
+def test_add(a, b, expected):
+    """Test addition with multiple inputs."""
+    assert add(a, b) == expected
+```
+
+### Parametrize with IDs
+
+```python
+@pytest.mark.parametrize("input,expected", [
+    ("valid@email.com", True),
+    ("invalid", False),
+    ("@no-domain.com", False),
+], ids=["valid-email", "missing-at", "missing-domain"])
+def test_email_validation(input, expected):
+    """Test email validation with readable test IDs."""
+    assert is_valid_email(input) is expected
+```
+
+### Parametrized Fixtures
+
+```python
+@pytest.fixture(params=["sqlite", "postgresql", "mysql"])
+def db(request):
+    """Test against multiple database backends."""
+    if request.param == "sqlite":
+        return Database(":memory:")
+    elif request.param == "postgresql":
+        return Database("postgresql://localhost/test")
+    elif request.param == "mysql":
+        return Database("mysql://localhost/test")
+
+def test_database_operations(db):
+    """Test runs 3 times, once for each database."""
+    result = db.query("SELECT 1")
+    assert result is not None
+```
+
+## Markers and Test Selection
+
+### Custom Markers
+
+```python
+# Mark slow tests
+@pytest.mark.slow
+def test_slow_operation():
+    time.sleep(5)
+
+# Mark integration tests
+@pytest.mark.integration
+def test_api_integration():
+    response = requests.get("https://api.example.com")
+    assert response.status_code == 200
+
+# Mark unit tests
+@pytest.mark.unit
+def test_unit_logic():
+    assert calculate(2, 3) == 5
+```
+
+### Run Specific Tests
+
+```bash
+# Run only fast tests
+pytest -m "not slow"
+
+# Run only integration tests
+pytest -m integration
+
+# Run integration or slow tests
+pytest -m "integration or slow"
+
+# Run tests marked as unit but not slow
+pytest -m "unit and not slow"
+```
+
+### Configure Markers in pytest.ini
+
+```ini
+[pytest]
+markers =
+    slow: marks tests as slow
+    integration: marks tests as integration tests
+    unit: marks tests as unit tests
+    django: marks tests as requiring Django
+```
+
+## Mocking and Patching
+
+### Mocking Functions
+
+```python
+from unittest.mock import patch, Mock
+
+@patch("mypackage.external_api_call")
+def test_with_mock(api_call_mock):
+    """Test with mocked external API."""
+    api_call_mock.return_value = {"status": "success"}
+
+    result = my_function()
+
+    api_call_mock.assert_called_once()
+    assert result["status"] == "success"
+```
+
+### Mocking Return Values
+
+```python
+@patch("mypackage.Database.connect")
+def test_database_connection(connect_mock):
+    """Test with mocked database connection."""
+    connect_mock.return_value = MockConnection()
+
+    db = Database()
+    db.connect()
+
+    connect_mock.assert_called_once_with("localhost")
+```
+
+### Mocking Exceptions
+
+```python
+@patch("mypackage.api_call")
+def test_api_error_handling(api_call_mock):
+    """Test error handling with mocked exception."""
+    api_call_mock.side_effect = ConnectionError("Network error")
+
+    with pytest.raises(ConnectionError):
+        api_call()
+
+    api_call_mock.assert_called_once()
+```
+
+### Mocking Context Managers
+
+```python
+@patch("builtins.open", new_callable=mock_open)
+def test_file_reading(mock_file):
+    """Test file reading with mocked open."""
+    mock_file.return_value.read.return_value = "file content"
+
+    result = read_file("test.txt")
+
+    mock_file.assert_called_once_with("test.txt", "r")
+    assert result == "file content"
+```
+
+### Using Autospec
+
+```python
+@patch("mypackage.DBConnection", autospec=True)
+def test_autospec(db_mock):
+    """Test with autospec to catch API misuse."""
+    db = db_mock.return_value
+    db.query("SELECT * FROM users")
+
+    # This would fail if DBConnection doesn't have query method
+    db_mock.assert_called_once()
+```
+
+### Mock Class Instances
+
+```python
+class TestUserService:
+    @patch("mypackage.UserRepository")
+    def test_create_user(self, repo_mock):
+        """Test user creation with mocked repository."""
+        repo_mock.return_value.save.return_value = User(id=1, name="Alice")
+
+        service = UserService(repo_mock.return_value)
+        user = service.create_user(name="Alice")
+
+        assert user.name == "Alice"
+        repo_mock.return_value.save.assert_called_once()
+```
+
+### Mock Property
+
+```python
+@pytest.fixture
+def mock_config():
+    """Create a mock with a property."""
+    config = Mock()
+    type(config).debug = PropertyMock(return_value=True)
+    type(config).api_key = PropertyMock(return_value="test-key")
+    return config
+
+def test_with_mock_config(mock_config):
+    """Test with mocked config properties."""
+    assert mock_config.debug is True
+    assert mock_config.api_key == "test-key"
+```
+
+## Testing Async Code
+
+### Async Tests with pytest-asyncio
+
+```python
+import pytest
+
+@pytest.mark.asyncio
+async def test_async_function():
+    """Test async function."""
+    result = await async_add(2, 3)
+    assert result == 5
+
+@pytest.mark.asyncio
+async def test_async_with_fixture(async_client):
+    """Test async with async fixture."""
+    response = await async_client.get("/api/users")
+    assert response.status_code == 200
+```
+
+### Async Fixture
+
+```python
+@pytest.fixture
+async def async_client():
+    """Async fixture providing async test client."""
+    app = create_app()
+    async with app.test_client() as client:
+        yield client
+
+@pytest.mark.asyncio
+async def test_api_endpoint(async_client):
+    """Test using async fixture."""
+    response = await async_client.get("/api/data")
+    assert response.status_code == 200
+```
+
+### Mocking Async Functions
+
+```python
+@pytest.mark.asyncio
+@patch("mypackage.async_api_call")
+async def test_async_mock(api_call_mock):
+    """Test async function with mock."""
+    api_call_mock.return_value = {"status": "ok"}
+
+    result = await my_async_function()
+
+    api_call_mock.assert_awaited_once()
+    assert result["status"] == "ok"
+```
+
+## Testing Exceptions
+
+### Testing Expected Exceptions
+
+```python
+def test_divide_by_zero():
+    """Test that dividing by zero raises ZeroDivisionError."""
+    with pytest.raises(ZeroDivisionError):
+        divide(10, 0)
+
+def test_custom_exception():
+    """Test custom exception with message."""
+    with pytest.raises(ValueError, match="invalid input"):
+        validate_input("invalid")
+```
+
+### Testing Exception Attributes
+
+```python
+def test_exception_with_details():
+    """Test exception with custom attributes."""
+    with pytest.raises(CustomError) as exc_info:
+        raise CustomError("error", code=400)
+
+    assert exc_info.value.code == 400
+    assert "error" in str(exc_info.value)
+```
+
+## Testing Side Effects
+
+### Testing File Operations
+
+```python
+import tempfile
+import os
+
+def test_file_processing():
+    """Test file processing with temp file."""
+    with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.txt') as f:
+        f.write("test content")
+        temp_path = f.name
+
+    try:
+        result = process_file(temp_path)
+        assert result == "processed: test content"
+    finally:
+        os.unlink(temp_path)
+```
+
+### Testing with pytest's tmp_path Fixture
+
+```python
+def test_with_tmp_path(tmp_path):
+    """Test using pytest's built-in temp path fixture."""
+    test_file = tmp_path / "test.txt"
+    test_file.write_text("hello world")
+
+    result = process_file(str(test_file))
+    assert result == "hello world"
+    # tmp_path automatically cleaned up
+```
+
+### Testing with tmpdir Fixture
+
+```python
+def test_with_tmpdir(tmpdir):
+    """Test using pytest's tmpdir fixture."""
+    test_file = tmpdir.join("test.txt")
+    test_file.write("data")
+
+    result = process_file(str(test_file))
+    assert result == "data"
+```
+
+## Test Organization
+
+### Directory Structure
+
+```
+tests/
+├── conftest.py                 # Shared fixtures
+├── __init__.py
+├── unit/                       # Unit tests
+│   ├── __init__.py
+│   ├── test_models.py
+│   ├── test_utils.py
+│   └── test_services.py
+├── integration/                # Integration tests
+│   ├── __init__.py
+│   ├── test_api.py
+│   └── test_database.py
+└── e2e/                        # End-to-end tests
+    ├── __init__.py
+    └── test_user_flow.py
+```
+
+### Test Classes
+
+```python
+class TestUserService:
+    """Group related tests in a class."""
+
+    @pytest.fixture(autouse=True)
+    def setup(self):
+        """Setup runs before each test in this class."""
+        self.service = UserService()
+
+    def test_create_user(self):
+        """Test user creation."""
+        user = self.service.create_user("Alice")
+        assert user.name == "Alice"
+
+    def test_delete_user(self):
+        """Test user deletion."""
+        user = User(id=1, name="Bob")
+        self.service.delete_user(user)
+        assert not self.service.user_exists(1)
+```
+
+## Best Practices
+
+### DO
+
+- **Follow TDD**: Write tests before code (red-green-refactor)
+- **Test one thing**: Each test should verify a single behavior
+- **Use descriptive names**: `test_user_login_with_invalid_credentials_fails`
+- **Use fixtures**: Eliminate duplication with fixtures
+- **Mock external dependencies**: Don't depend on external services
+- **Test edge cases**: Empty inputs, None values, boundary conditions
+- **Aim for 80%+ coverage**: Focus on critical paths
+- **Keep tests fast**: Use marks to separate slow tests
+
+### DON'T
+
+- **Don't test implementation**: Test behavior, not internals
+- **Don't use complex conditionals in tests**: Keep tests simple
+- **Don't ignore test failures**: All tests must pass
+- **Don't test third-party code**: Trust libraries to work
+- **Don't share state between tests**: Tests should be independent
+- **Don't catch exceptions in tests**: Use `pytest.raises`
+- **Don't use print statements**: Use assertions and pytest output
+- **Don't write tests that are too brittle**: Avoid over-specific mocks
+
+## Common Patterns
+
+### Testing API Endpoints (FastAPI/Flask)
+
+```python
+@pytest.fixture
+def client():
+    app = create_app(testing=True)
+    return app.test_client()
+
+def test_get_user(client):
+    response = client.get("/api/users/1")
+    assert response.status_code == 200
+    assert response.json["id"] == 1
+
+def test_create_user(client):
+    response = client.post("/api/users", json={
+        "name": "Alice",
+        "email": "alice@example.com"
+    })
+    assert response.status_code == 201
+    assert response.json["name"] == "Alice"
+```
+
+### Testing Database Operations
+
+```python
+@pytest.fixture
+def db_session():
+    """Create a test database session."""
+    session = Session(bind=engine)
+    session.begin_nested()
+    yield session
+    session.rollback()
+    session.close()
+
+def test_create_user(db_session):
+    user = User(name="Alice", email="alice@example.com")
+    db_session.add(user)
+    db_session.commit()
+
+    retrieved = db_session.query(User).filter_by(name="Alice").first()
+    assert retrieved.email == "alice@example.com"
+```
+
+### Testing Class Methods
+
+```python
+class TestCalculator:
+    @pytest.fixture
+    def calculator(self):
+        return Calculator()
+
+    def test_add(self, calculator):
+        assert calculator.add(2, 3) == 5
+
+    def test_divide_by_zero(self, calculator):
+        with pytest.raises(ZeroDivisionError):
+            calculator.divide(10, 0)
+```
+
+## pytest Configuration
+
+### pytest.ini
+
+```ini
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+addopts =
+    --strict-markers
+    --disable-warnings
+    --cov=mypackage
+    --cov-report=term-missing
+    --cov-report=html
+markers =
+    slow: marks tests as slow
+    integration: marks tests as integration tests
+    unit: marks tests as unit tests
+```
+
+### pyproject.toml
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--cov=mypackage",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+]
+markers = [
+    "slow: marks tests as slow",
+    "integration: marks tests as integration tests",
+    "unit: marks tests as unit tests",
+]
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific file
+pytest tests/test_utils.py
+
+# Run specific test
+pytest tests/test_utils.py::test_function
+
+# Run with verbose output
+pytest -v
+
+# Run with coverage
+pytest --cov=mypackage --cov-report=html
+
+# Run only fast tests
+pytest -m "not slow"
+
+# Run until first failure
+pytest -x
+
+# Run and stop on N failures
+pytest --maxfail=3
+
+# Run last failed tests
+pytest --lf
+
+# Run tests with pattern
+pytest -k "test_user"
+
+# Run with debugger on failure
+pytest --pdb
+```
+
+## Quick Reference
+
+| Pattern | Usage |
+|---------|-------|
+| `pytest.raises()` | Test expected exceptions |
+| `@pytest.fixture()` | Create reusable test fixtures |
+| `@pytest.mark.parametrize()` | Run tests with multiple inputs |
+| `@pytest.mark.slow` | Mark slow tests |
+| `pytest -m "not slow"` | Skip slow tests |
+| `@patch()` | Mock functions and classes |
+| `tmp_path` fixture | Automatic temp directory |
+| `pytest --cov` | Generate coverage report |
+| `assert` | Simple and readable assertions |
+
+**Remember**: Tests are code too. Keep them clean, readable, and maintainable. Good tests catch bugs; great tests prevent them.
+
+### fastapi-patterns
+
+FastAPI project layout, app factory/lifespan, pydantic-settings config, Pydantic v2 request/response schemas, async dependency injection, router design, a transactional service layer, and httpx+pytest testing. Use when building or reviewing a FastAPI application.
+
+# FastAPI Patterns
+
+Modern, production-grade FastAPI development: project layout, Pydantic v2 schemas, dependency injection, async patterns, auth, transactional service methods, and testing.
+
+## Project Structure
+
+```text
+my_app/
+|-- app/
+|   |-- main.py               # App factory, lifespan, middleware
+|   |-- config.py             # Settings via pydantic-settings
+|   |-- dependencies.py       # Shared FastAPI dependencies
+|   |-- database.py           # SQLAlchemy engine + session
+|   |-- routers/
+|   |   `-- users.py
+|   |-- models/               # SQLAlchemy ORM models
+|   |   `-- user.py
+|   |-- schemas/              # Pydantic request/response schemas
+|   |   `-- user.py
+|   `-- services/             # Business logic layer
+|       `-- user_service.py
+|-- tests/
+|   |-- conftest.py
+|   `-- test_users.py
+|-- pyproject.toml
+`-- .env
+```
+
+---
+
+## App Factory and Lifespan
+
+```python
+# app/main.py
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.config import settings
+from app.database import engine, Base
+from app.routers import users
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Automatically create tables on startup for ease of use in dev/demo environments.
+    # For strict production applications, manage schemas via Alembic migrations instead.
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    # Shutdown: close pooled resources.
+    await engine.dispose()
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title=settings.app_name,
+        version=settings.app_version,
+        lifespan=lifespan,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.allowed_origins,
+        allow_credentials=settings.allow_credentials,
+        allow_methods=settings.allowed_methods,
+        allow_headers=settings.allowed_headers,
+    )
+
+    app.include_router(users.router, prefix="/users", tags=["users"])
+
+    return app
+
+
+app = create_app()
+```
+
+---
+
+## Configuration with pydantic-settings
+
+```python
+# app/config.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    app_name: str = "My App"
+    app_version: str = "0.1.0"
+    debug: bool = False
+
+    database_url: str
+    secret_key: str
+    algorithm: str = "HS256"
+    access_token_expire_minutes: int = 30
+
+    # Pydantic-settings v2 safely evaluates mutable list literals directly
+    allowed_origins: list[str] = ["http://localhost:3000"]
+    allowed_methods: list[str] = ["GET", "POST", "PATCH", "DELETE", "OPTIONS"]
+    allowed_headers: list[str] = ["Authorization", "Content-Type"]
+    allow_credentials: bool = True
+
+
+settings = Settings()
+```
+
+---
+
+## Pydantic Schemas (v2)
+
+```python
+# app/schemas/user.py
+from datetime import datetime
+from pydantic import BaseModel, EmailStr, Field, model_validator
+
+
+class UserBase(BaseModel):
+    email: EmailStr
+    username: str = Field(min_length=3, max_length=50)
+
+
+class UserCreate(UserBase):
+    password: str = Field(min_length=8)
+    password_confirm: str
+
+    @model_validator(mode="after")
+    def passwords_match(self) -> "UserCreate":
+        if self.password != self.password_confirm:
+            raise ValueError("Passwords do not match")
+        return self
+
+
+class UserUpdate(BaseModel):
+    username: str | None = Field(default=None, min_length=3, max_length=50)
+    email: EmailStr | None = None
+
+
+class UserResponse(UserBase):
+    id: int
+    is_active: bool
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class UserListResponse(BaseModel):
+    total: int
+    items: list[UserResponse]
+```
+
+---
+
+## Dependency Injection
+
+```python
+# app/dependencies.py
+from typing import Annotated, AsyncGenerator
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.database import AsyncSessionLocal
+from app.models.user import User
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/users/token")
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    async with AsyncSessionLocal() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+
+
+async def get_current_user(
+    token: Annotated[str, Depends(oauth2_scheme)],
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> User:
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(token, settings.secret_key, algorithms=[settings.algorithm])
+        subject = payload.get("sub")
+        if subject is None:
+            raise credentials_exception
+        user_id = int(subject)
+    except (JWTError, TypeError, ValueError):
+        raise credentials_exception
+
+    user = await db.get(User, user_id)
+    if user is None:
+        raise credentials_exception
+    return user
+
+
+async def get_current_active_user(
+    current_user: Annotated[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
+
+
+DbDep = Annotated[AsyncSession, Depends(get_db)]
+CurrentUserDep = Annotated[User, Depends(get_current_user)]
+ActiveUserDep = Annotated[User, Depends(get_current_active_user)]
+```
+
+---
+
+## Router and Endpoint Design
+
+```python
+# app/routers/users.py
+from typing import Annotated
+from fastapi import APIRouter, HTTPException, Query, status
+from fastapi.security import OAuth2PasswordRequestForm
+
+from app.dependencies import ActiveUserDep, DbDep
+from app.schemas.user import UserCreate, UserResponse, UserUpdate, UserListResponse
+from app.services.user_service import DuplicateUserError, UserService
+
+router = APIRouter()
+
+
+@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+async def create_user(payload: UserCreate, db: DbDep) -> UserResponse:
+    service = UserService(db)
+    try:
+        return await service.create(payload)
+    except DuplicateUserError:
+        raise HTTPException(status_code=400, detail="Email already registered")
+
+
+@router.get("/me", response_model=UserResponse)
+async def get_me(current_user: ActiveUserDep) -> UserResponse:
+    return current_user
+
+
+@router.get("/", response_model=UserListResponse)
+async def list_users(
+    db: DbDep,
+    current_user: ActiveUserDep,
+    skip: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+) -> UserListResponse:
+    service = UserService(db)
+    users, total = await service.list(skip=skip, limit=limit)
+    return UserListResponse(total=total, items=users)
+
+
+@router.patch("/{user_id}", response_model=UserResponse)
+async def update_user(
+    user_id: int,
+    payload: UserUpdate,
+    db: DbDep,
+    current_user: ActiveUserDep,
+) -> UserResponse:
+    if current_user.id != user_id:
+        raise HTTPException(status_code=403, detail="Not authorized")
+    service = UserService(db)
+    try:
+        user = await service.update(user_id, payload)
+    except DuplicateUserError:
+        raise HTTPException(status_code=400, detail="Email already registered")
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+
+@router.post("/token")
+async def login(
+    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],
+    db: DbDep,
+) -> dict[str, str]:
+    service = UserService(db)
+    token = await service.authenticate(form_data.username, form_data.password)
+    if token is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return {"access_token": token, "token_type": "bearer"}
+```
+
+---
+
+## Service Layer
+
+```python
+# app/services/user_service.py
+from datetime import datetime, timedelta, timezone
+
+from jose import jwt
+from passlib.context import CryptContext
+from sqlalchemy import func, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import settings
+from app.models.user import User
+from app.schemas.user import UserCreate, UserUpdate
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+class DuplicateUserError(Exception):
+    """Raised when a unique user field conflicts with an existing row."""
+
+
+class UserService:
+    def __init__(self, db: AsyncSession) -> None:
+        self.db = db
+
+    async def get_by_email(self, email: str) -> User | None:
+        result = await self.db.execute(select(User).where(User.email == email))
+        return result.scalar_one_or_none()
+
+    async def create(self, payload: UserCreate) -> User:
+        user = User(
+            email=payload.email,
+            username=payload.username,
+            hashed_password=pwd_context.hash(payload.password),
+        )
+        self.db.add(user)
+        try:
+            # Rely on atomic DB constraints rather than race-prone application-level prechecks
+            await self.db.commit()
+        except IntegrityError as exc:
+            await self.db.rollback()
+            raise DuplicateUserError from exc
+        await self.db.refresh(user)
+        return user
+
+    async def list(self, skip: int = 0, limit: int = 20) -> tuple[list[User], int]:
+        total_result = await self.db.execute(select(func.count(User.id)))
+        total = total_result.scalar_one()
+        # Enforce explicit deterministic ordering to ensure reliable pagination
+        result = await self.db.execute(
+            select(User).order_by(User.id).offset(skip).limit(limit)
+        )
+        return list(result.scalars()), total
+
+    async def update(self, user_id: int, payload: UserUpdate) -> User | None:
+        user = await self.db.get(User, user_id)
+        if user is None:
+            return None
+        for field, value in payload.model_dump(exclude_unset=True).items():
+            setattr(user, field, value)
+        try:
+            await self.db.commit()
+        except IntegrityError as exc:
+            await self.db.rollback()
+            raise DuplicateUserError from exc
+        await self.db.refresh(user)
+        return user
+
+    async def authenticate(self, email: str, password: str) -> str | None:
+        user = await self.get_by_email(email)
+        if user is None or not pwd_context.verify(password, user.hashed_password):
+            return None
+        expire = datetime.now(timezone.utc) + timedelta(
+            minutes=settings.access_token_expire_minutes
+        )
+        return jwt.encode(
+            {"sub": str(user.id), "exp": expire},
+            settings.secret_key,
+            algorithm=settings.algorithm,
+        )
+```
+
+> **Note on Database Design:** Application-level unique handling requires an underlying unique database index (e.g., `unique=True` on your SQLAlchemy mapping attributes). Without underlying constraints, application layer error-catching cannot safely prevent concurrent race conditions.
+
+---
+
+## Testing with httpx and pytest
+
+```python
+# tests/conftest.py
+import pytest_asyncio
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.database import Base
+from app.dependencies import get_db
+from app.main import create_app
+
+TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"
+
+engine = create_async_engine(TEST_DATABASE_URL)
+TestingSessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
+
+@pytest_asyncio.fixture(autouse=True)
+async def setup_db():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    yield
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+
+
+@pytest_asyncio.fixture
+async def db_session():
+    async with TestingSessionLocal() as session:
+        yield session
+        await session.rollback()
+
+
+@pytest_asyncio.fixture
+async def client(db_session: AsyncSession):
+    app = create_app()
+
+    async def override_get_db():
+        yield db_session
+
+    app.dependency_overrides[get_db] = override_get_db
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as ac:
+        yield ac
+
+
+@pytest_asyncio.fixture
+async def registered_user(client: AsyncClient) -> dict:
+    resp = await client.post("/users/", json={
+        "email": "test@example.com",
+        "username": "testuser",
+        "password": "securepass1",
+        "password_confirm": "securepass1",
+    })
+    assert resp.status_code == 201
+    return resp.json()
+
+
+@pytest_asyncio.fixture
+async def auth_token(client: AsyncClient, registered_user: dict) -> str:
+    resp = await client.post("/users/token", data={
+        "username": "test@example.com",
+        "password": "securepass1",
+    })
+    assert resp.status_code == 200
+    return resp.json()["access_token"]
+
+
+@pytest_asyncio.fixture
+async def auth_client(client: AsyncClient, auth_token: str) -> AsyncClient:
+    client.headers.update({"Authorization": f"Bearer {auth_token}"})
+    return client
+```
+
+---
+
+## Anti-Patterns
+
+```python
+# Bad: business logic inside route handlers.
+@router.post("/users/")
+async def create_user(payload: UserCreate, db: DbDep):
+    hashed = bcrypt.hash(payload.password)
+    user = User(email=payload.email, hashed_password=hashed)
+    db.add(user)
+    await db.commit()
+    return user
+
+# Good: thin route, transactional service handling.
+@router.post("/users/", response_model=UserResponse, status_code=201)
+async def create_user(payload: UserCreate, db: DbDep):
+    try:
+        return await UserService(db).create(payload)
+    except DuplicateUserError:
+        raise HTTPException(status_code=400, detail="Email already registered")
+
+
+# Bad: sync DB calls in async routes block the event loop.
+@router.get("/items/")
+async def list_items(db: Session = Depends(get_db)):
+    return db.query(Item).all()
+
+# Good: use async SQLAlchemy executions.
+@router.get("/items/")
+async def list_items(db: AsyncSession = Depends(get_db)):
+    result = await db.execute(select(Item))
+    return result.scalars().all()
+```
+
+---
+
+## Best Practices
+
+- Always declare a typed `response_model` to prevent accidental PII/data leaks and output clean OpenAPI schemas.
+- Consolidate standard middleware dependency injections via type-aliasing: `DbDep = Annotated[AsyncSession, Depends(get_db)]`.
+- Wrap database mutation boundaries gracefully within transactions inside your service layer, catching structural database errors directly.
+- Parse JWT parameters defensively, expecting potential string/integer cast mismatches from modern payload variations.
+- Enforce deterministic sorting (e.g., `.order_by(Model.id)`) on all offset/limit paginated endpoints to avoid data skips.
+- Isolate authorization checks from core authentication dependencies to provide precise REST status signals (`401` vs `403`).
+
+### django-security
+
+Django production security settings, authentication and custom user models, authorization/RBAC and DRF permissions, SQL injection and XSS prevention, CSRF, file-upload validation, rate limiting, security headers, and secret management. Use when configuring or reviewing Django security posture.
+
+# Django Security Best Practices
+
+Comprehensive security guidelines for Django applications to protect against common vulnerabilities.
+
+## When to Activate
+
+- Setting up Django authentication and authorization
+- Implementing user permissions and roles
+- Configuring production security settings
+- Reviewing Django application for security issues
+- Deploying Django applications to production
+
+## Core Security Settings
+
+### Production Settings Configuration
+
+```python
+# settings/production.py
+import os
+
+DEBUG = False  # CRITICAL: Never use True in production
+
+ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', '').split(',')
+
+# Security headers
+SECURE_SSL_REDIRECT = True
+SESSION_COOKIE_SECURE = True
+CSRF_COOKIE_SECURE = True
+SECURE_HSTS_SECONDS = 31536000  # 1 year
+SECURE_HSTS_INCLUDE_SUBDOMAINS = True
+SECURE_HSTS_PRELOAD = True
+SECURE_CONTENT_TYPE_NOSNIFF = True
+SECURE_BROWSER_XSS_FILTER = True
+X_FRAME_OPTIONS = 'DENY'
+
+# HTTPS and Cookies
+SESSION_COOKIE_HTTPONLY = True
+CSRF_COOKIE_HTTPONLY = True
+SESSION_COOKIE_SAMESITE = 'Lax'
+CSRF_COOKIE_SAMESITE = 'Lax'
+
+# Secret key (must be set via environment variable)
+SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')
+if not SECRET_KEY:
+    raise ImproperlyConfigured('DJANGO_SECRET_KEY environment variable is required')
+
+# Password validation
+AUTH_PASSWORD_VALIDATORS = [
+    {
+        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
+        'OPTIONS': {
+            'min_length': 12,
+        }
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
+    },
+    {
+        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
+    },
+]
+```
+
+## Authentication
+
+### Custom User Model
+
+```python
+# apps/users/models.py
+from django.contrib.auth.models import AbstractUser
+from django.db import models
+
+class User(AbstractUser):
+    """Custom user model for better security."""
+
+    email = models.EmailField(unique=True)
+    phone = models.CharField(max_length=20, blank=True)
+
+    USERNAME_FIELD = 'email'  # Use email as username
+    REQUIRED_FIELDS = ['username']
+
+    class Meta:
+        db_table = 'users'
+        verbose_name = 'User'
+        verbose_name_plural = 'Users'
+
+    def __str__(self):
+        return self.email
+
+# settings/base.py
+AUTH_USER_MODEL = 'users.User'
+```
+
+### Password Hashing
+
+```python
+# Django uses PBKDF2 by default. For stronger security:
+PASSWORD_HASHERS = [
+    'django.contrib.auth.hashers.Argon2PasswordHasher',
+    'django.contrib.auth.hashers.PBKDF2PasswordHasher',
+    'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+    'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',
+]
+```
+
+### Session Management
+
+```python
+# Session configuration
+SESSION_ENGINE = 'django.contrib.sessions.backends.cache'  # Or 'db'
+SESSION_CACHE_ALIAS = 'default'
+SESSION_COOKIE_AGE = 3600 * 24 * 7  # 1 week
+SESSION_SAVE_EVERY_REQUEST = False
+SESSION_EXPIRE_AT_BROWSER_CLOSE = False  # Better UX, but less secure
+```
+
+## Authorization
+
+### Permissions
+
+```python
+# models.py
+from django.db import models
+from django.contrib.auth.models import Permission
+
+class Post(models.Model):
+    title = models.CharField(max_length=200)
+    content = models.TextField()
+    author = models.ForeignKey(User, on_delete=models.CASCADE)
+
+    class Meta:
+        permissions = [
+            ('can_publish', 'Can publish posts'),
+            ('can_edit_others', 'Can edit posts of others'),
+        ]
+
+    def user_can_edit(self, user):
+        """Check if user can edit this post."""
+        return self.author == user or user.has_perm('app.can_edit_others')
+
+# views.py
+from django.contrib.auth.mixins import LoginRequiredMixin, PermissionRequiredMixin
+from django.views.generic import UpdateView
+
+class PostUpdateView(LoginRequiredMixin, PermissionRequiredMixin, UpdateView):
+    model = Post
+    permission_required = 'app.can_edit_others'
+    raise_exception = True  # Return 403 instead of redirect
+
+    def get_queryset(self):
+        """Only allow users to edit their own posts."""
+        return Post.objects.filter(author=self.request.user)
+```
+
+### Custom Permissions
+
+```python
+# permissions.py
+from rest_framework import permissions
+
+class IsOwnerOrReadOnly(permissions.BasePermission):
+    """Allow only owners to edit objects."""
+
+    def has_object_permission(self, request, view, obj):
+        # Read permissions allowed for any request
+        if request.method in permissions.SAFE_METHODS:
+            return True
+
+        # Write permissions only for owner
+        return obj.author == request.user
+
+class IsAdminOrReadOnly(permissions.BasePermission):
+    """Allow admins to do anything, others read-only."""
+
+    def has_permission(self, request, view):
+        if request.method in permissions.SAFE_METHODS:
+            return True
+        return request.user and request.user.is_staff
+
+class IsVerifiedUser(permissions.BasePermission):
+    """Allow only verified users."""
+
+    def has_permission(self, request, view):
+        return request.user and request.user.is_authenticated and request.user.is_verified
+```
+
+### Role-Based Access Control (RBAC)
+
+```python
+# models.py
+from django.contrib.auth.models import AbstractUser, Group
+
+class User(AbstractUser):
+    ROLE_CHOICES = [
+        ('admin', 'Administrator'),
+        ('moderator', 'Moderator'),
+        ('user', 'Regular User'),
+    ]
+    role = models.CharField(max_length=20, choices=ROLE_CHOICES, default='user')
+
+    def is_admin(self):
+        return self.role == 'admin' or self.is_superuser
+
+    def is_moderator(self):
+        return self.role in ['admin', 'moderator']
+
+# Mixins
+class AdminRequiredMixin:
+    """Mixin to require admin role."""
+
+    def dispatch(self, request, *args, **kwargs):
+        if not request.user.is_authenticated or not request.user.is_admin():
+            from django.core.exceptions import PermissionDenied
+            raise PermissionDenied
+        return super().dispatch(request, *args, **kwargs)
+```
+
+## SQL Injection Prevention
+
+### Django ORM Protection
+
+```python
+# GOOD: Django ORM automatically escapes parameters
+def get_user(username):
+    return User.objects.get(username=username)  # Safe
+
+# GOOD: Using parameters with raw()
+def search_users(query):
+    return User.objects.raw('SELECT * FROM users WHERE username = %s', [query])
+
+# BAD: Never directly interpolate user input
+def get_user_bad(username):
+    return User.objects.raw(f'SELECT * FROM users WHERE username = {username}')  # VULNERABLE!
+
+# GOOD: Using filter with proper escaping
+def get_users_by_email(email):
+    return User.objects.filter(email__iexact=email)  # Safe
+
+# GOOD: Using Q objects for complex queries
+from django.db.models import Q
+def search_users_complex(query):
+    return User.objects.filter(
+        Q(username__icontains=query) |
+        Q(email__icontains=query)
+    )  # Safe
+```
+
+### Extra Security with raw()
+
+```python
+# If you must use raw SQL, always use parameters
+User.objects.raw(
+    'SELECT * FROM users WHERE email = %s AND status = %s',
+    [user_input_email, status]
+)
+```
+
+## XSS Prevention
+
+### Template Escaping
+
+```django
+{# Django auto-escapes variables by default - SAFE #}
+{{ user_input }}  {# Escaped HTML #}
+
+{# Explicitly mark safe only for trusted content #}
+{{ trusted_html|safe }}  {# Not escaped #}
+
+{# Use template filters for safe HTML #}
+{{ user_input|escape }}  {# Same as default #}
+{{ user_input|striptags }}  {# Remove all HTML tags #}
+
+{# JavaScript escaping #}
+<script>
+    var username = {{ username|escapejs }};
+</script>
+```
+
+### Safe String Handling
+
+```python
+from django.utils.safestring import mark_safe
+from django.utils.html import escape
+
+# BAD: Never mark user input as safe without escaping
+def render_bad(user_input):
+    return mark_safe(user_input)  # VULNERABLE!
+
+# GOOD: Escape first, then mark safe
+def render_good(user_input):
+    return mark_safe(escape(user_input))
+
+# GOOD: Use format_html for HTML with variables
+from django.utils.html import format_html
+
+def greet_user(username):
+    return format_html('<span class="user">{}</span>', escape(username))
+```
+
+### HTTP Headers
+
+```python
+# settings.py
+SECURE_CONTENT_TYPE_NOSNIFF = True  # Prevent MIME sniffing
+SECURE_BROWSER_XSS_FILTER = True  # Enable XSS filter
+X_FRAME_OPTIONS = 'DENY'  # Prevent clickjacking
+
+# Custom middleware
+from django.conf import settings
+
+class SecurityHeaderMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        response['X-Content-Type-Options'] = 'nosniff'
+        response['X-Frame-Options'] = 'DENY'
+        response['X-XSS-Protection'] = '1; mode=block'
+        response['Content-Security-Policy'] = "default-src 'self'"
+        return response
+```
+
+## CSRF Protection
+
+### Default CSRF Protection
+
+```python
+# settings.py - CSRF is enabled by default
+CSRF_COOKIE_SECURE = True  # Only send over HTTPS
+CSRF_COOKIE_HTTPONLY = True  # Prevent JavaScript access
+CSRF_COOKIE_SAMESITE = 'Lax'  # Prevent CSRF in some cases
+CSRF_TRUSTED_ORIGINS = ['https://example.com']  # Trusted domains
+
+# Template usage
+<form method="post">
+    {% csrf_token %}
+    {{ form.as_p }}
+    <button type="submit">Submit</button>
+</form>
+
+# AJAX requests
+function getCookie(name) {
+    let cookieValue = null;
+    if (document.cookie && document.cookie !== '') {
+        const cookies = document.cookie.split(';');
+        for (let i = 0; i < cookies.length; i++) {
+            const cookie = cookies[i].trim();
+            if (cookie.substring(0, name.length + 1) === (name + '=')) {
+                cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
+                break;
+            }
+        }
+    }
+    return cookieValue;
+}
+
+fetch('/api/endpoint/', {
+    method: 'POST',
+    headers: {
+        'X-CSRFToken': getCookie('csrftoken'),
+        'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(data)
+});
+```
+
+### Exempting Views (Use Carefully)
+
+```python
+from django.views.decorators.csrf import csrf_exempt
+
+@csrf_exempt  # Only use when absolutely necessary!
+def webhook_view(request):
+    # Webhook from external service
+    pass
+```
+
+## File Upload Security
+
+### File Validation
+
+```python
+import os
+import magic  # pip install python-magic
+from django.core.exceptions import ValidationError
+
+ALLOWED_MIMES = {
+    'image/jpeg', 'image/png', 'image/gif', 'application/pdf',
+}
+
+MIME_TO_EXTENSIONS = {
+    'image/jpeg': {'.jpg', '.jpeg'},
+    'image/png': {'.png'},
+    'image/gif': {'.gif'},
+    'application/pdf': {'.pdf'},
+}
+
+def validate_file_type(value):
+    """Validate file type using magic bytes and cross-check extension."""
+    mime = magic.from_buffer(value.read(2048), mime=True)
+    value.seek(0)
+
+    if mime not in ALLOWED_MIMES:
+        raise ValidationError('Unsupported file type.')
+
+    ext = os.path.splitext(value.name)[1].lower()
+    if ext not in MIME_TO_EXTENSIONS.get(mime, set()):
+        raise ValidationError('File extension does not match file content.')
+
+def validate_file_size(value):
+    """Validate file size (max 5MB)."""
+    if value.size > 5 * 1024 * 1024:
+        raise ValidationError('File too large. Max size is 5MB.')
+
+# models.py
+class Document(models.Model):
+    file = models.FileField(
+        upload_to='documents/',
+        validators=[validate_file_type, validate_file_size]
+    )
+
+```
+
+For environments where installing libmagic is difficult (e.g., minimal containers),
+use the pure-Python `filetype` package as an alternative:
+
+```python
+import os
+from django.core.exceptions import ValidationError
+
+import filetype  # pip install filetype
+
+ALLOWED_MIMES = {
+    'image/jpeg', 'image/png', 'image/gif', 'application/pdf',
+}
+
+MIME_TO_EXTENSIONS = {
+    'image/jpeg': {'.jpg', '.jpeg'},
+    'image/png': {'.png'},
+    'image/gif': {'.gif'},
+    'application/pdf': {'.pdf'},
+}
+
+def validate_file_type(value):
+    """Validate file type using magic bytes."""
+    kind = filetype.guess(value.read(2048))
+    value.seek(0)
+
+    if kind is None or kind.mime not in ALLOWED_MIMES:
+        raise ValidationError('Unsupported file type.')
+
+    ext = os.path.splitext(value.name)[1].lower()
+    if ext not in MIME_TO_EXTENSIONS.get(kind.mime, set()):
+        raise ValidationError('File extension does not match file content.')
+```
+
+### Secure File Storage
+
+```python
+# settings.py
+MEDIA_ROOT = '/var/www/media/'
+MEDIA_URL = '/media/'
+
+# Use a separate domain for media in production
+MEDIA_DOMAIN = 'https://media.example.com'
+
+# Don't serve user uploads directly
+# Use whitenoise or a CDN for static files
+# Use a separate server or S3 for media files
+```
+
+## API Security
+
+### Rate Limiting
+
+```python
+# settings.py
+REST_FRAMEWORK = {
+    'DEFAULT_THROTTLE_CLASSES': [
+        'rest_framework.throttling.AnonRateThrottle',
+        'rest_framework.throttling.UserRateThrottle'
+    ],
+    'DEFAULT_THROTTLE_RATES': {
+        'anon': '100/day',
+        'user': '1000/day',
+        'upload': '10/hour',
+    }
+}
+
+# Custom throttle
+from rest_framework.throttling import UserRateThrottle
+
+class BurstRateThrottle(UserRateThrottle):
+    scope = 'burst'
+    rate = '60/min'
+
+class SustainedRateThrottle(UserRateThrottle):
+    scope = 'sustained'
+    rate = '1000/day'
+```
+
+### Authentication for APIs
+
+```python
+# settings.py
+REST_FRAMEWORK = {
+    'DEFAULT_AUTHENTICATION_CLASSES': [
+        'rest_framework.authentication.TokenAuthentication',
+        'rest_framework.authentication.SessionAuthentication',
+        'rest_framework_simplejwt.authentication.JWTAuthentication',
+    ],
+    'DEFAULT_PERMISSION_CLASSES': [
+        'rest_framework.permissions.IsAuthenticated',
+    ],
+}
+
+# views.py
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import IsAuthenticated
+
+@api_view(['GET', 'POST'])
+@permission_classes([IsAuthenticated])
+def protected_view(request):
+    return Response({'message': 'You are authenticated'})
+```
+
+## Security Headers
+
+### Content Security Policy
+
+```python
+# settings.py
+CSP_DEFAULT_SRC = "'self'"
+CSP_SCRIPT_SRC = "'self' https://cdn.example.com"
+CSP_STYLE_SRC = "'self' 'unsafe-inline'"
+CSP_IMG_SRC = "'self' data: https:"
+CSP_CONNECT_SRC = "'self' https://api.example.com"
+
+# Middleware
+class CSPMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        response = self.get_response(request)
+        response['Content-Security-Policy'] = (
+            f"default-src {CSP_DEFAULT_SRC}; "
+            f"script-src {CSP_SCRIPT_SRC}; "
+            f"style-src {CSP_STYLE_SRC}; "
+            f"img-src {CSP_IMG_SRC}; "
+            f"connect-src {CSP_CONNECT_SRC}"
+        )
+        return response
+```
+
+## Environment Variables
+
+### Managing Secrets
+
+```python
+# Use python-decouple or django-environ
+import environ
+
+env = environ.Env(
+    # set casting, default value
+    DEBUG=(bool, False)
+)
+
+# reading .env file
+environ.Env.read_env()
+
+SECRET_KEY = env('DJANGO_SECRET_KEY')
+DATABASE_URL = env('DATABASE_URL')
+ALLOWED_HOSTS = env.list('ALLOWED_HOSTS')
+
+# .env file (never commit this)
+DEBUG=False
+SECRET_KEY=your-secret-key-here
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+ALLOWED_HOSTS=example.com,www.example.com
+```
+
+## Logging Security Events
+
+```python
+# settings.py
+LOGGING = {
+    'version': 1,
+    'disable_existing_loggers': False,
+    'handlers': {
+        'file': {
+            'level': 'WARNING',
+            'class': 'logging.FileHandler',
+            'filename': '/var/log/django/security.log',
+        },
+        'console': {
+            'level': 'INFO',
+            'class': 'logging.StreamHandler',
+        },
+    },
+    'loggers': {
+        'django.security': {
+            'handlers': ['file', 'console'],
+            'level': 'WARNING',
+            'propagate': True,
+        },
+        'django.request': {
+            'handlers': ['file'],
+            'level': 'ERROR',
+            'propagate': False,
+        },
+    },
+}
+```
+
+## Quick Security Checklist
+
+| Check | Description |
+|-------|-------------|
+| `DEBUG = False` | Never run with DEBUG in production |
+| HTTPS only | Force SSL, secure cookies |
+| Strong secrets | Use environment variables for SECRET_KEY |
+| Password validation | Enable all password validators |
+| CSRF protection | Enabled by default, don't disable |
+| XSS prevention | Django auto-escapes, don't use `&#124;safe` with user input |
+| SQL injection | Use ORM, never concatenate strings in queries |
+| File uploads | Validate file type and size |
+| Rate limiting | Throttle API endpoints |
+| Security headers | CSP, X-Frame-Options, HSTS |
+| Logging | Log security events |
+| Updates | Keep Django and dependencies updated |
+
+Remember: Security is a process, not a product. Regularly review and update your security practices.
+
+### django-tdd
+
+Django testing with pytest-django and factory_boy: TDD workflow, test settings, fixtures, model/view/serializer/DRF-API testing, mocking external services and email, and integration/full-flow tests, plus coverage targets. Use when writing or reviewing Django tests.
+
+# Django Testing with TDD
+
+Test-driven development for Django applications using pytest, factory_boy, and Django REST Framework.
+
+## When to Activate
+
+- Writing new Django applications
+- Implementing Django REST Framework APIs
+- Testing Django models, views, and serializers
+- Setting up testing infrastructure for Django projects
+
+## TDD Workflow for Django
+
+### Red-Green-Refactor Cycle
+
+```python
+# Step 1: RED - Write failing test
+def test_user_creation():
+    user = User.objects.create_user(email='test@example.com', password='testpass123')
+    assert user.email == 'test@example.com'
+    assert user.check_password('testpass123')
+    assert not user.is_staff
+
+# Step 2: GREEN - Make test pass
+# Create User model or factory
+
+# Step 3: REFACTOR - Improve while keeping tests green
+```
+
+## Setup
+
+### pytest Configuration
+
+```ini
+# pytest.ini
+[pytest]
+DJANGO_SETTINGS_MODULE = config.settings.test
+testpaths = tests
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+addopts =
+    --reuse-db
+    --nomigrations
+    --cov=apps
+    --cov-report=html
+    --cov-report=term-missing
+    --strict-markers
+markers =
+    slow: marks tests as slow
+    integration: marks tests as integration tests
+```
+
+### Test Settings
+
+```python
+# config/settings/test.py
+from .base import *
+
+DEBUG = True
+DATABASES = {
+    'default': {
+        'ENGINE': 'django.db.backends.sqlite3',
+        'NAME': ':memory:',
+    }
+}
+
+# Disable migrations for speed
+class DisableMigrations:
+    def __contains__(self, item):
+        return True
+
+    def __getitem__(self, item):
+        return None
+
+MIGRATION_MODULES = DisableMigrations()
+
+# Faster password hashing
+PASSWORD_HASHERS = [
+    'django.contrib.auth.hashers.MD5PasswordHasher',
+]
+
+# Email backend
+EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
+
+# Celery always eager
+CELERY_TASK_ALWAYS_EAGER = True
+CELERY_TASK_EAGER_PROPAGATES = True
+```
+
+### conftest.py
+
+```python
+# tests/conftest.py
+import pytest
+from django.utils import timezone
+from django.contrib.auth import get_user_model
+
+User = get_user_model()
+
+@pytest.fixture(autouse=True)
+def timezone_settings(settings):
+    """Ensure consistent timezone."""
+    settings.TIME_ZONE = 'UTC'
+
+@pytest.fixture
+def user(db):
+    """Create a test user."""
+    return User.objects.create_user(
+        email='test@example.com',
+        password='testpass123',
+        username='testuser'
+    )
+
+@pytest.fixture
+def admin_user(db):
+    """Create an admin user."""
+    return User.objects.create_superuser(
+        email='admin@example.com',
+        password='adminpass123',
+        username='admin'
+    )
+
+@pytest.fixture
+def authenticated_client(client, user):
+    """Return authenticated client."""
+    client.force_login(user)
+    return client
+
+@pytest.fixture
+def api_client():
+    """Return DRF API client."""
+    from rest_framework.test import APIClient
+    return APIClient()
+
+@pytest.fixture
+def authenticated_api_client(api_client, user):
+    """Return authenticated API client."""
+    api_client.force_authenticate(user=user)
+    return api_client
+```
+
+## Factory Boy
+
+### Factory Setup
+
+```python
+# tests/factories.py
+import factory
+from factory import fuzzy
+from datetime import datetime, timedelta
+from django.contrib.auth import get_user_model
+from apps.products.models import Product, Category
+
+User = get_user_model()
+
+class UserFactory(factory.django.DjangoModelFactory):
+    """Factory for User model."""
+
+    class Meta:
+        model = User
+
+    email = factory.Sequence(lambda n: f"user{n}@example.com")
+    username = factory.Sequence(lambda n: f"user{n}")
+    password = factory.PostGenerationMethodCall('set_password', 'testpass123')
+    first_name = factory.Faker('first_name')
+    last_name = factory.Faker('last_name')
+    is_active = True
+
+class CategoryFactory(factory.django.DjangoModelFactory):
+    """Factory for Category model."""
+
+    class Meta:
+        model = Category
+
+    name = factory.Faker('word')
+    slug = factory.LazyAttribute(lambda obj: obj.name.lower())
+    description = factory.Faker('text')
+
+class ProductFactory(factory.django.DjangoModelFactory):
+    """Factory for Product model."""
+
+    class Meta:
+        model = Product
+
+    name = factory.Faker('sentence', nb_words=3)
+    slug = factory.LazyAttribute(lambda obj: obj.name.lower().replace(' ', '-'))
+    description = factory.Faker('text')
+    price = fuzzy.FuzzyDecimal(10.00, 1000.00, 2)
+    stock = fuzzy.FuzzyInteger(0, 100)
+    is_active = True
+    category = factory.SubFactory(CategoryFactory)
+    created_by = factory.SubFactory(UserFactory)
+
+    @factory.post_generation
+    def tags(self, create, extracted, **kwargs):
+        """Add tags to product."""
+        if not create:
+            return
+        if extracted:
+            for tag in extracted:
+                self.tags.add(tag)
+```
+
+### Using Factories
+
+```python
+# tests/test_models.py
+import pytest
+from tests.factories import ProductFactory, UserFactory
+
+def test_product_creation():
+    """Test product creation using factory."""
+    product = ProductFactory(price=100.00, stock=50)
+    assert product.price == 100.00
+    assert product.stock == 50
+    assert product.is_active is True
+
+def test_product_with_tags():
+    """Test product with tags."""
+    tags = [TagFactory(name='electronics'), TagFactory(name='new')]
+    product = ProductFactory(tags=tags)
+    assert product.tags.count() == 2
+
+def test_multiple_products():
+    """Test creating multiple products."""
+    products = ProductFactory.create_batch(10)
+    assert len(products) == 10
+```
+
+## Model Testing
+
+### Model Tests
+
+```python
+# tests/test_models.py
+import pytest
+from django.core.exceptions import ValidationError
+from tests.factories import UserFactory, ProductFactory
+
+class TestUserModel:
+    """Test User model."""
+
+    def test_create_user(self, db):
+        """Test creating a regular user."""
+        user = UserFactory(email='test@example.com')
+        assert user.email == 'test@example.com'
+        assert user.check_password('testpass123')
+        assert not user.is_staff
+        assert not user.is_superuser
+
+    def test_create_superuser(self, db):
+        """Test creating a superuser."""
+        user = UserFactory(
+            email='admin@example.com',
+            is_staff=True,
+            is_superuser=True
+        )
+        assert user.is_staff
+        assert user.is_superuser
+
+    def test_user_str(self, db):
+        """Test user string representation."""
+        user = UserFactory(email='test@example.com')
+        assert str(user) == 'test@example.com'
+
+class TestProductModel:
+    """Test Product model."""
+
+    def test_product_creation(self, db):
+        """Test creating a product."""
+        product = ProductFactory()
+        assert product.id is not None
+        assert product.is_active is True
+        assert product.created_at is not None
+
+    def test_product_slug_generation(self, db):
+        """Test automatic slug generation."""
+        product = ProductFactory(name='Test Product')
+        assert product.slug == 'test-product'
+
+    def test_product_price_validation(self, db):
+        """Test price cannot be negative."""
+        product = ProductFactory(price=-10)
+        with pytest.raises(ValidationError):
+            product.full_clean()
+
+    def test_product_manager_active(self, db):
+        """Test active manager method."""
+        ProductFactory.create_batch(5, is_active=True)
+        ProductFactory.create_batch(3, is_active=False)
+
+        active_count = Product.objects.active().count()
+        assert active_count == 5
+
+    def test_product_stock_management(self, db):
+        """Test stock management."""
+        product = ProductFactory(stock=10)
+        product.reduce_stock(5)
+        product.refresh_from_db()
+        assert product.stock == 5
+
+        with pytest.raises(ValueError):
+            product.reduce_stock(10)  # Not enough stock
+```
+
+## View Testing
+
+### Django View Testing
+
+```python
+# tests/test_views.py
+import pytest
+from django.urls import reverse
+from tests.factories import ProductFactory, UserFactory
+
+class TestProductViews:
+    """Test product views."""
+
+    def test_product_list(self, client, db):
+        """Test product list view."""
+        ProductFactory.create_batch(10)
+
+        response = client.get(reverse('products:list'))
+
+        assert response.status_code == 200
+        assert len(response.context['products']) == 10
+
+    def test_product_detail(self, client, db):
+        """Test product detail view."""
+        product = ProductFactory()
+
+        response = client.get(reverse('products:detail', kwargs={'slug': product.slug}))
+
+        assert response.status_code == 200
+        assert response.context['product'] == product
+
+    def test_product_create_requires_login(self, client, db):
+        """Test product creation requires authentication."""
+        response = client.get(reverse('products:create'))
+
+        assert response.status_code == 302
+        assert response.url.startswith('/accounts/login/')
+
+    def test_product_create_authenticated(self, authenticated_client, db):
+        """Test product creation as authenticated user."""
+        response = authenticated_client.get(reverse('products:create'))
+
+        assert response.status_code == 200
+
+    def test_product_create_post(self, authenticated_client, db, category):
+        """Test creating a product via POST."""
+        data = {
+            'name': 'Test Product',
+            'description': 'A test product',
+            'price': '99.99',
+            'stock': 10,
+            'category': category.id,
+        }
+
+        response = authenticated_client.post(reverse('products:create'), data)
+
+        assert response.status_code == 302
+        assert Product.objects.filter(name='Test Product').exists()
+```
+
+## DRF API Testing
+
+### Serializer Testing
+
+```python
+# tests/test_serializers.py
+import pytest
+from rest_framework.exceptions import ValidationError
+from apps.products.serializers import ProductSerializer
+from tests.factories import ProductFactory
+
+class TestProductSerializer:
+    """Test ProductSerializer."""
+
+    def test_serialize_product(self, db):
+        """Test serializing a product."""
+        product = ProductFactory()
+        serializer = ProductSerializer(product)
+
+        data = serializer.data
+
+        assert data['id'] == product.id
+        assert data['name'] == product.name
+        assert data['price'] == str(product.price)
+
+    def test_deserialize_product(self, db):
+        """Test deserializing product data."""
+        data = {
+            'name': 'Test Product',
+            'description': 'Test description',
+            'price': '99.99',
+            'stock': 10,
+            'category': 1,
+        }
+
+        serializer = ProductSerializer(data=data)
+
+        assert serializer.is_valid()
+        product = serializer.save()
+
+        assert product.name == 'Test Product'
+        assert float(product.price) == 99.99
+
+    def test_price_validation(self, db):
+        """Test price validation."""
+        data = {
+            'name': 'Test Product',
+            'price': '-10.00',
+            'stock': 10,
+        }
+
+        serializer = ProductSerializer(data=data)
+
+        assert not serializer.is_valid()
+        assert 'price' in serializer.errors
+
+    def test_stock_validation(self, db):
+        """Test stock cannot be negative."""
+        data = {
+            'name': 'Test Product',
+            'price': '99.99',
+            'stock': -5,
+        }
+
+        serializer = ProductSerializer(data=data)
+
+        assert not serializer.is_valid()
+        assert 'stock' in serializer.errors
+```
+
+### API ViewSet Testing
+
+```python
+# tests/test_api.py
+import pytest
+from rest_framework.test import APIClient
+from rest_framework import status
+from django.urls import reverse
+from tests.factories import ProductFactory, UserFactory
+
+class TestProductAPI:
+    """Test Product API endpoints."""
+
+    @pytest.fixture
+    def api_client(self):
+        """Return API client."""
+        return APIClient()
+
+    def test_list_products(self, api_client, db):
+        """Test listing products."""
+        ProductFactory.create_batch(10)
+
+        url = reverse('api:product-list')
+        response = api_client.get(url)
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data['count'] == 10
+
+    def test_retrieve_product(self, api_client, db):
+        """Test retrieving a product."""
+        product = ProductFactory()
+
+        url = reverse('api:product-detail', kwargs={'pk': product.id})
+        response = api_client.get(url)
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data['id'] == product.id
+
+    def test_create_product_unauthorized(self, api_client, db):
+        """Test creating product without authentication."""
+        url = reverse('api:product-list')
+        data = {'name': 'Test Product', 'price': '99.99'}
+
+        response = api_client.post(url, data)
+
+        assert response.status_code == status.HTTP_401_UNAUTHORIZED
+
+    def test_create_product_authorized(self, authenticated_api_client, db):
+        """Test creating product as authenticated user."""
+        url = reverse('api:product-list')
+        data = {
+            'name': 'Test Product',
+            'description': 'Test',
+            'price': '99.99',
+            'stock': 10,
+        }
+
+        response = authenticated_api_client.post(url, data)
+
+        assert response.status_code == status.HTTP_201_CREATED
+        assert response.data['name'] == 'Test Product'
+
+    def test_update_product(self, authenticated_api_client, db):
+        """Test updating a product."""
+        product = ProductFactory(created_by=authenticated_api_client.user)
+
+        url = reverse('api:product-detail', kwargs={'pk': product.id})
+        data = {'name': 'Updated Product'}
+
+        response = authenticated_api_client.patch(url, data)
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data['name'] == 'Updated Product'
+
+    def test_delete_product(self, authenticated_api_client, db):
+        """Test deleting a product."""
+        product = ProductFactory(created_by=authenticated_api_client.user)
+
+        url = reverse('api:product-detail', kwargs={'pk': product.id})
+        response = authenticated_api_client.delete(url)
+
+        assert response.status_code == status.HTTP_204_NO_CONTENT
+
+    def test_filter_products_by_price(self, api_client, db):
+        """Test filtering products by price."""
+        ProductFactory(price=50)
+        ProductFactory(price=150)
+
+        url = reverse('api:product-list')
+        response = api_client.get(url, {'price_min': 100})
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data['count'] == 1
+
+    def test_search_products(self, api_client, db):
+        """Test searching products."""
+        ProductFactory(name='Apple iPhone')
+        ProductFactory(name='Samsung Galaxy')
+
+        url = reverse('api:product-list')
+        response = api_client.get(url, {'search': 'Apple'})
+
+        assert response.status_code == status.HTTP_200_OK
+        assert response.data['count'] == 1
+```
+
+## Mocking and Patching
+
+### Mocking External Services
+
+```python
+# tests/test_views.py
+from unittest.mock import patch, Mock
+import pytest
+
+class TestPaymentView:
+    """Test payment view with mocked payment gateway."""
+
+    @patch('apps.payments.services.stripe')
+    def test_successful_payment(self, mock_stripe, client, user, product):
+        """Test successful payment with mocked Stripe."""
+        # Configure mock
+        mock_stripe.Charge.create.return_value = {
+            'id': 'ch_123',
+            'status': 'succeeded',
+            'amount': 9999,
+        }
+
+        client.force_login(user)
+        response = client.post(reverse('payments:process'), {
+            'product_id': product.id,
+            'token': 'tok_visa',
+        })
+
+        assert response.status_code == 302
+        mock_stripe.Charge.create.assert_called_once()
+
+    @patch('apps.payments.services.stripe')
+    def test_failed_payment(self, mock_stripe, client, user, product):
+        """Test failed payment."""
+        mock_stripe.Charge.create.side_effect = Exception('Card declined')
+
+        client.force_login(user)
+        response = client.post(reverse('payments:process'), {
+            'product_id': product.id,
+            'token': 'tok_visa',
+        })
+
+        assert response.status_code == 302
+        assert 'error' in response.url
+```
+
+### Mocking Email Sending
+
+```python
+# tests/test_email.py
+from django.core import mail
+from django.test import override_settings
+
+@override_settings(EMAIL_BACKEND='django.core.mail.backends.locmem.EmailBackend')
+def test_order_confirmation_email(db, order):
+    """Test order confirmation email."""
+    order.send_confirmation_email()
+
+    assert len(mail.outbox) == 1
+    assert order.user.email in mail.outbox[0].to
+    assert 'Order Confirmation' in mail.outbox[0].subject
+```
+
+## Integration Testing
+
+### Full Flow Testing
+
+```python
+# tests/test_integration.py
+import pytest
+from django.urls import reverse
+from tests.factories import UserFactory, ProductFactory
+
+class TestCheckoutFlow:
+    """Test complete checkout flow."""
+
+    def test_guest_to_purchase_flow(self, client, db):
+        """Test complete flow from guest to purchase."""
+        # Step 1: Register
+        response = client.post(reverse('users:register'), {
+            'email': 'test@example.com',
+            'password': 'testpass123',
+            'password_confirm': 'testpass123',
+        })
+        assert response.status_code == 302
+
+        # Step 2: Login
+        response = client.post(reverse('users:login'), {
+            'email': 'test@example.com',
+            'password': 'testpass123',
+        })
+        assert response.status_code == 302
+
+        # Step 3: Browse products
+        product = ProductFactory(price=100)
+        response = client.get(reverse('products:detail', kwargs={'slug': product.slug}))
+        assert response.status_code == 200
+
+        # Step 4: Add to cart
+        response = client.post(reverse('cart:add'), {
+            'product_id': product.id,
+            'quantity': 1,
+        })
+        assert response.status_code == 302
+
+        # Step 5: Checkout
+        response = client.get(reverse('checkout:review'))
+        assert response.status_code == 200
+        assert product.name in response.content.decode()
+
+        # Step 6: Complete purchase
+        with patch('apps.checkout.services.process_payment') as mock_payment:
+            mock_payment.return_value = True
+            response = client.post(reverse('checkout:complete'))
+
+        assert response.status_code == 302
+        assert Order.objects.filter(user__email='test@example.com').exists()
+```
+
+## Testing Best Practices
+
+### DO
+
+- **Use factories**: Instead of manual object creation
+- **One assertion per test**: Keep tests focused
+- **Descriptive test names**: `test_user_cannot_delete_others_post`
+- **Test edge cases**: Empty inputs, None values, boundary conditions
+- **Mock external services**: Don't depend on external APIs
+- **Use fixtures**: Eliminate duplication
+- **Test permissions**: Ensure authorization works
+- **Keep tests fast**: Use `--reuse-db` and `--nomigrations`
+
+### DON'T
+
+- **Don't test Django internals**: Trust Django to work
+- **Don't test third-party code**: Trust libraries to work
+- **Don't ignore failing tests**: All tests must pass
+- **Don't make tests dependent**: Tests should run in any order
+- **Don't over-mock**: Mock only external dependencies
+- **Don't test private methods**: Test public interface
+- **Don't use production database**: Always use test database
+
+## Coverage
+
+### Coverage Configuration
+
+```bash
+# Run tests with coverage
+pytest --cov=apps --cov-report=html --cov-report=term-missing
+
+# Generate HTML report
+open htmlcov/index.html
+```
+
+### Coverage Goals
+
+| Component | Target Coverage |
+|-----------|-----------------|
+| Models | 90%+ |
+| Serializers | 85%+ |
+| Views | 80%+ |
+| Services | 90%+ |
+| Utilities | 80%+ |
+| Overall | 80%+ |
+
+## Quick Reference
+
+| Pattern | Usage |
+|---------|-------|
+| `@pytest.mark.django_db` | Enable database access |
+| `client` | Django test client |
+| `api_client` | DRF API client |
+| `factory.create_batch(n)` | Create multiple objects |
+| `patch('module.function')` | Mock external dependencies |
+| `override_settings` | Temporarily change settings |
+| `force_authenticate()` | Bypass authentication in tests |
+| `assertRedirects` | Check for redirects |
+| `assertTemplateUsed` | Verify template usage |
+| `mail.outbox` | Check sent emails |
+
+Remember: Tests are documentation. Good tests explain how your code should work. Keep them simple, readable, and maintainable.