@baselane/packs 0.1.4 → 0.1.5

package/packs/python-rules/pack.json

@@ -1,21 +1,86 @@
 {
   "$schema": "https://baselane.dev/schema/workflow-pack-v1.json",
   "id": "python-rules",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "title": "Python rules",
-  "summary": "Python conventions a linter can't check — frozen dataclasses for value objects, Protocols for structural typing, raise ... from, os.environ[] over silent .get() fallbacks — with a reviewer and a ruff guard; style and coverage belong in CI.",
+  "summary": "Full ECC Python corpus: conventions, three framework-aware reviewers (Python/FastAPI/Django), five deep-reference skills, and a ruff guard hook.",
   "scope": "repo",
-  "attribution": { "source": "affaan-m/ECC", "url": "https://github.com/affaan-m/ECC", "license": "MIT" },
+  "attribution": {
+    "source": "affaan-m/ECC",
+    "url": "https://github.com/affaan-m/ECC",
+    "license": "MIT"
+  },
   "context": {
-    "markdown": "## Python conventions (beyond what the linter enforces)\n\n`ruff` and `black` already enforce PEP 8, import order, bare `except`, and mutable default arguments — this pack is the judgment they can't encode. Keep the mechanical checks in CI (`ruff check .`, `bandit -r src/`, `pytest --cov`); the reviewer covers the rest.\n\n### Data shapes\n\n- Model value objects as `@dataclass(frozen=True)` or `NamedTuple`, not a mutable class with public attributes.\n- Use a `Protocol` when a caller needs only an interface, not a concrete base class; use plain `@dataclass` for request/DTO shapes at API and service boundaries.\n- Acquire every resource (files, locks, connections) through a context manager (`with`); use generators for lazy, memory-efficient iteration.\n\n### Types\n\n- Annotate every function signature, including internal helpers — not just the public API a type checker would force.\n\n### Errors\n\n- Catch specific exception types and preserve the chain when wrapping (`raise NewError(...) from err`); never swallow into a bare `except` or drop the cause.\n\n### Boundaries\n\n- Validate external input at the boundary before it reaches business logic; fail fast with a clear message (Pydantic or an explicit check).\n- Read required secrets with `os.environ[\"KEY\"]` so a missing value raises at startup — never `os.environ.get(...)` with a fallback that lets a misconfigured app boot.\n\n### Flag in review (a linter won't)\n\n- A mutable class used where a frozen value object belongs.\n- A concrete base class used where a `Protocol` would decouple the caller.\n- A wrapped exception that drops `from err` and loses the cause.\n- A required secret read via `.get()` with a silent fallback default.\n"
+    "markdown": "## Python conventions (beyond what the linter enforces)\n\n`ruff` and `black` already enforce PEP 8, import order, bare `except`, and mutable default arguments — this pack is the judgment they can't encode. Keep the mechanical checks in CI (`ruff check .`, `bandit -r src/`, `pytest --cov`); the reviewers cover the rest.\n\n### Standards and formatting\n\n- Follow PEP 8 conventions; annotate every function signature, including internal helpers.\n- Format with **black**, sort imports with **isort**, lint with **ruff**.\n- Import order: stdlib, then third-party, then local — enforced by isort.\n\n### Core principles\n\n- **Readability counts.** Code should be obvious; prefer a clear loop over a clever one-liner.\n- **Explicit is better than implicit.** Avoid hidden side effects (e.g. a bare `some_module.setup()` import with no visible call site).\n- **EAFP over LBYL.** Prefer `try`/`except KeyError` over `if key in dictionary` — Python favors asking forgiveness over checking permission first.\n\n### Data shapes\n\n- Model value objects as `@dataclass(frozen=True)` or `NamedTuple`, not a mutable class with public attributes.\n- Use a `Protocol` when a caller needs only an interface, not a concrete base class; use plain `@dataclass` for request/DTO shapes at API and service boundaries.\n- Validate invariants in `__post_init__` (e.g. reject a malformed email or an out-of-range age at construction, not later).\n- Acquire every resource (files, locks, connections, DB transactions) through a context manager (`with`); write custom ones with `@contextlib.contextmanager` or an `__enter__`/`__exit__` class when reuse pays off. Use generators for lazy, memory-efficient iteration and to avoid building large intermediate lists.\n\n### Errors\n\n- Catch specific exception types and preserve the chain when wrapping (`raise NewError(...) from err`); never swallow into a bare `except` or drop the cause.\n- Build a small custom exception hierarchy (`AppError` → `ValidationError`, `NotFoundError`, ...) instead of raising bare `Exception` or built-ins for domain errors.\n\n### Boundaries\n\n- Validate external input at the boundary before it reaches business logic; fail fast with a clear message (Pydantic or an explicit check).\n- Read required secrets with `os.environ[\"KEY\"]` so a missing value raises at startup — never `os.environ.get(...)` with a fallback that lets a misconfigured app boot silently.\n\n### Concurrency\n\n- Use `ThreadPoolExecutor` for I/O-bound work, `ProcessPoolExecutor` for CPU-bound work, and `asyncio`/`aiohttp` for concurrent I/O — pick the tool that matches what's actually blocking.\n- Guard shared mutable state with `threading.Lock`; don't mix sync and async call paths in the same function.\n- Batch queries instead of issuing one per loop iteration (N+1).\n\n### Performance\n\n- Avoid `result += str(item)` in a loop (O(n²) due to string immutability) — use `\"\".join(...)` or `io.StringIO`.\n- Use `__slots__` on high-volume value classes to cut per-instance memory.\n- Prefer a generator over building a full list when the data is only consumed once.\n\n### Anti-patterns (flag in review — a linter won't catch these)\n\n- Mutable default arguments: `def f(x=[])` — use `def f(x=None)` and create the list inside.\n- `type(obj) == list` instead of `isinstance(obj, list)`.\n- `value == None` instead of `value is None`.\n- `from module import *` — namespace pollution.\n- A mutable class used where a frozen value object belongs.\n- A concrete base class used where a `Protocol` would decouple the caller.\n- A wrapped exception that drops `from err` and loses the cause.\n- A required secret read via `.get()` with a silent fallback default.\n\n### Security\n\n- Read secrets from the environment (`os.environ[\"KEY\"]`, or `python-dotenv`'s `load_dotenv()` in development) — never hardcode them.\n- Run **bandit** for static security analysis: `bandit -r src/`.\n- SQL injection: never interpolate user input into a query string — use parameterized queries or the ORM.\n- Command injection: never pass unvalidated input to a shell — use `subprocess` with a list of args, not `shell=True` with a formatted string.\n- Path traversal: validate user-controlled paths with `normpath` and reject `..` segments.\n- Avoid `eval`/`exec` on untrusted input, unsafe deserialization (`pickle`, `yaml.load` without `SafeLoader`), and weak crypto (MD5/SHA1 for anything security-sensitive).\n\n### Testing\n\n- Use **pytest**; follow the TDD cycle (red — write a failing test, green — minimal code to pass, refactor — clean up while green).\n- Target 80%+ coverage overall, 100% on critical paths: `pytest --cov=src --cov-report=term-missing`.\n- Use `pytest.mark` to categorize tests (`unit`, `integration`, `slow`) and `pytest -m \"not slow\"` to skip the slow ones in a fast local loop.\n- Mock external dependencies (`unittest.mock.patch`), not the code under test; prefer `tmp_path` over hand-rolled temp files.\n\n### Reference\n\nSee skills `python-patterns` (idioms, decorators, concurrency, package layout), `python-testing` (pytest fixtures, mocking, parametrization), `fastapi-patterns` (async API layering), and `django-security`/`django-tdd` for framework-specific depth.\n"
   },
+  "skills": [
+    {
+      "name": "python-patterns",
+      "description": "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.",
+      "category": "write",
+      "body": "# Python Development Patterns\n\nIdiomatic Python patterns and best practices for building robust, efficient, and maintainable applications.\n\n## When to Activate\n\n- Writing new Python code\n- Reviewing Python code\n- Refactoring existing Python code\n- Designing Python packages/modules\n\n## Core Principles\n\n### 1. Readability Counts\n\nPython prioritizes readability. Code should be obvious and easy to understand.\n\n```python\n# Good: Clear and readable\ndef get_active_users(users: list[User]) -> list[User]:\n    \"\"\"Return only active users from the provided list.\"\"\"\n    return [user for user in users if user.is_active]\n\n\n# Bad: Clever but confusing\ndef get_active_users(u):\n    return [x for x in u if x.a]\n```\n\n### 2. Explicit is Better Than Implicit\n\nAvoid magic; be clear about what your code does.\n\n```python\n# Good: Explicit configuration\nimport logging\n\nlogging.basicConfig(\n    level=logging.INFO,\n    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'\n)\n\n# Bad: Hidden side effects\nimport some_module\nsome_module.setup()  # What does this do?\n```\n\n### 3. EAFP - Easier to Ask Forgiveness Than Permission\n\nPython prefers exception handling over checking conditions.\n\n```python\n# Good: EAFP style\ndef get_value(dictionary: dict, key: str, default_value: Any = None) -> Any:\n    try:\n        return dictionary[key]\n    except KeyError:\n        return default_value\n\n# Bad: LBYL (Look Before You Leap) style\ndef get_value(dictionary: dict, key: str, default_value: Any = None) -> Any:\n    if key in dictionary:\n        return dictionary[key]\n    else:\n        return default_value\n```\n\n## Type Hints\n\n### Basic Type Annotations\n\n```python\nfrom typing import Optional, List, Dict, Any\n\ndef process_user(\n    user_id: str,\n    data: Dict[str, Any],\n    active: bool = True\n) -> Optional[User]:\n    \"\"\"Process a user and return the updated User or None.\"\"\"\n    if not active:\n        return None\n    return User(user_id, data)\n```\n\n### Modern Type Hints (Python 3.9+)\n\n```python\n# Python 3.9+ - Use built-in types\ndef process_items(items: list[str]) -> dict[str, int]:\n    return {item: len(item) for item in items}\n\n# Python 3.8 and earlier - Use typing module\nfrom typing import List, Dict\n\ndef process_items(items: List[str]) -> Dict[str, int]:\n    return {item: len(item) for item in items}\n```\n\n### Type Aliases and TypeVar\n\n```python\nfrom typing import TypeVar, Union\n\n# Type alias for complex types\nJSON = Union[dict[str, Any], list[Any], str, int, float, bool, None]\n\ndef parse_json(data: str) -> JSON:\n    return json.loads(data)\n\n# Generic types\nT = TypeVar('T')\n\ndef first(items: list[T]) -> T | None:\n    \"\"\"Return the first item or None if list is empty.\"\"\"\n    return items[0] if items else None\n```\n\n### Protocol-Based Duck Typing\n\n```python\nfrom typing import Protocol\n\nclass Renderable(Protocol):\n    def render(self) -> str:\n        \"\"\"Render the object to a string.\"\"\"\n\ndef render_all(items: list[Renderable]) -> str:\n    \"\"\"Render all items that implement the Renderable protocol.\"\"\"\n    return \"\\n\".join(item.render() for item in items)\n```\n\n## Error Handling Patterns\n\n### Specific Exception Handling\n\n```python\n# Good: Catch specific exceptions\ndef load_config(path: str) -> Config:\n    try:\n        with open(path) as f:\n            return Config.from_json(f.read())\n    except FileNotFoundError as e:\n        raise ConfigError(f\"Config file not found: {path}\") from e\n    except json.JSONDecodeError as e:\n        raise ConfigError(f\"Invalid JSON in config: {path}\") from e\n\n# Bad: Bare except\ndef load_config(path: str) -> Config:\n    try:\n        with open(path) as f:\n            return Config.from_json(f.read())\n    except:\n        return None  # Silent failure!\n```\n\n### Exception Chaining\n\n```python\ndef process_data(data: str) -> Result:\n    try:\n        parsed = json.loads(data)\n    except json.JSONDecodeError as e:\n        # Chain exceptions to preserve the traceback\n        raise ValueError(f\"Failed to parse data: {data}\") from e\n```\n\n### Custom Exception Hierarchy\n\n```python\nclass AppError(Exception):\n    \"\"\"Base exception for all application errors.\"\"\"\n    pass\n\nclass ValidationError(AppError):\n    \"\"\"Raised when input validation fails.\"\"\"\n    pass\n\nclass NotFoundError(AppError):\n    \"\"\"Raised when a requested resource is not found.\"\"\"\n    pass\n\n# Usage\ndef get_user(user_id: str) -> User:\n    user = db.find_user(user_id)\n    if not user:\n        raise NotFoundError(f\"User not found: {user_id}\")\n    return user\n```\n\n## Context Managers\n\n### Resource Management\n\n```python\n# Good: Using context managers\ndef process_file(path: str) -> str:\n    with open(path, 'r') as f:\n        return f.read()\n\n# Bad: Manual resource management\ndef process_file(path: str) -> str:\n    f = open(path, 'r')\n    try:\n        return f.read()\n    finally:\n        f.close()\n```\n\n### Custom Context Managers\n\n```python\nfrom contextlib import contextmanager\n\n@contextmanager\ndef timer(name: str):\n    \"\"\"Context manager to time a block of code.\"\"\"\n    start = time.perf_counter()\n    yield\n    elapsed = time.perf_counter() - start\n    print(f\"{name} took {elapsed:.4f} seconds\")\n\n# Usage\nwith timer(\"data processing\"):\n    process_large_dataset()\n```\n\n### Context Manager Classes\n\n```python\nclass DatabaseTransaction:\n    def __init__(self, connection):\n        self.connection = connection\n\n    def __enter__(self):\n        self.connection.begin_transaction()\n        return self\n\n    def __exit__(self, exc_type, exc_val, exc_tb):\n        if exc_type is None:\n            self.connection.commit()\n        else:\n            self.connection.rollback()\n        return False  # Don't suppress exceptions\n\n# Usage\nwith DatabaseTransaction(conn):\n    user = conn.create_user(user_data)\n    conn.create_profile(user.id, profile_data)\n```\n\n## Comprehensions and Generators\n\n### List Comprehensions\n\n```python\n# Good: List comprehension for simple transformations\nnames = [user.name for user in users if user.is_active]\n\n# Bad: Manual loop\nnames = []\nfor user in users:\n    if user.is_active:\n        names.append(user.name)\n\n# Complex comprehensions should be expanded\n# Bad: Too complex\nresult = [x * 2 for x in items if x > 0 if x % 2 == 0]\n\n# Good: Use a generator function\ndef filter_and_transform(items: Iterable[int]) -> list[int]:\n    result = []\n    for x in items:\n        if x > 0 and x % 2 == 0:\n            result.append(x * 2)\n    return result\n```\n\n### Generator Expressions\n\n```python\n# Good: Generator for lazy evaluation\ntotal = sum(x * x for x in range(1_000_000))\n\n# Bad: Creates large intermediate list\ntotal = sum([x * x for x in range(1_000_000)])\n```\n\n### Generator Functions\n\n```python\ndef read_large_file(path: str) -> Iterator[str]:\n    \"\"\"Read a large file line by line.\"\"\"\n    with open(path) as f:\n        for line in f:\n            yield line.strip()\n\n# Usage\nfor line in read_large_file(\"huge.txt\"):\n    process(line)\n```\n\n## Data Classes and Named Tuples\n\n### Data Classes\n\n```python\nfrom dataclasses import dataclass, field\nfrom datetime import datetime\n\n@dataclass\nclass User:\n    \"\"\"User entity with automatic __init__, __repr__, and __eq__.\"\"\"\n    id: str\n    name: str\n    email: str\n    created_at: datetime = field(default_factory=datetime.now)\n    is_active: bool = True\n\n# Usage\nuser = User(\n    id=\"123\",\n    name=\"Alice\",\n    email=\"alice@example.com\"\n)\n```\n\n### Data Classes with Validation\n\n```python\n@dataclass\nclass User:\n    email: str\n    age: int\n\n    def __post_init__(self):\n        # Validate email format\n        if \"@\" not in self.email:\n            raise ValueError(f\"Invalid email: {self.email}\")\n        # Validate age range\n        if self.age < 0 or self.age > 150:\n            raise ValueError(f\"Invalid age: {self.age}\")\n```\n\n### Named Tuples\n\n```python\nfrom typing import NamedTuple\n\nclass Point(NamedTuple):\n    \"\"\"Immutable 2D point.\"\"\"\n    x: float\n    y: float\n\n    def distance(self, other: 'Point') -> float:\n        return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5\n\n# Usage\np1 = Point(0, 0)\np2 = Point(3, 4)\nprint(p1.distance(p2))  # 5.0\n```\n\n## Decorators\n\n### Function Decorators\n\n```python\nimport functools\nimport time\n\ndef timer(func: Callable) -> Callable:\n    \"\"\"Decorator to time function execution.\"\"\"\n    @functools.wraps(func)\n    def wrapper(*args, **kwargs):\n        start = time.perf_counter()\n        result = func(*args, **kwargs)\n        elapsed = time.perf_counter() - start\n        print(f\"{func.__name__} took {elapsed:.4f}s\")\n        return result\n    return wrapper\n\n@timer\ndef slow_function():\n    time.sleep(1)\n\n# slow_function() prints: slow_function took 1.0012s\n```\n\n### Parameterized Decorators\n\n```python\ndef repeat(times: int):\n    \"\"\"Decorator to repeat a function multiple times.\"\"\"\n    def decorator(func: Callable) -> Callable:\n        @functools.wraps(func)\n        def wrapper(*args, **kwargs):\n            results = []\n            for _ in range(times):\n                results.append(func(*args, **kwargs))\n            return results\n        return wrapper\n    return decorator\n\n@repeat(times=3)\ndef greet(name: str) -> str:\n    return f\"Hello, {name}!\"\n\n# greet(\"Alice\") returns [\"Hello, Alice!\", \"Hello, Alice!\", \"Hello, Alice!\"]\n```\n\n### Class-Based Decorators\n\n```python\nclass CountCalls:\n    \"\"\"Decorator that counts how many times a function is called.\"\"\"\n    def __init__(self, func: Callable):\n        functools.update_wrapper(self, func)\n        self.func = func\n        self.count = 0\n\n    def __call__(self, *args, **kwargs):\n        self.count += 1\n        print(f\"{self.func.__name__} has been called {self.count} times\")\n        return self.func(*args, **kwargs)\n\n@CountCalls\ndef process():\n    pass\n\n# Each call to process() prints the call count\n```\n\n## Concurrency Patterns\n\n### Threading for I/O-Bound Tasks\n\n```python\nimport concurrent.futures\nimport threading\n\ndef fetch_url(url: str) -> str:\n    \"\"\"Fetch a URL (I/O-bound operation).\"\"\"\n    import urllib.request\n    with urllib.request.urlopen(url) as response:\n        return response.read().decode()\n\ndef fetch_all_urls(urls: list[str]) -> dict[str, str]:\n    \"\"\"Fetch multiple URLs concurrently using threads.\"\"\"\n    with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:\n        future_to_url = {executor.submit(fetch_url, url): url for url in urls}\n        results = {}\n        for future in concurrent.futures.as_completed(future_to_url):\n            url = future_to_url[future]\n            try:\n                results[url] = future.result()\n            except Exception as e:\n                results[url] = f\"Error: {e}\"\n    return results\n```\n\n### Multiprocessing for CPU-Bound Tasks\n\n```python\ndef process_data(data: list[int]) -> int:\n    \"\"\"CPU-intensive computation.\"\"\"\n    return sum(x ** 2 for x in data)\n\ndef process_all(datasets: list[list[int]]) -> list[int]:\n    \"\"\"Process multiple datasets using multiple processes.\"\"\"\n    with concurrent.futures.ProcessPoolExecutor() as executor:\n        results = list(executor.map(process_data, datasets))\n    return results\n```\n\n### Async/Await for Concurrent I/O\n\n```python\nimport asyncio\n\nasync def fetch_async(url: str) -> str:\n    \"\"\"Fetch a URL asynchronously.\"\"\"\n    import aiohttp\n    async with aiohttp.ClientSession() as session:\n        async with session.get(url) as response:\n            return await response.text()\n\nasync def fetch_all(urls: list[str]) -> dict[str, str]:\n    \"\"\"Fetch multiple URLs concurrently.\"\"\"\n    tasks = [fetch_async(url) for url in urls]\n    results = await asyncio.gather(*tasks, return_exceptions=True)\n    return dict(zip(urls, results))\n```\n\n## Package Organization\n\n### Standard Project Layout\n\n```\nmyproject/\n├── src/\n│   └── mypackage/\n│       ├── __init__.py\n│       ├── main.py\n│       ├── api/\n│       │   ├── __init__.py\n│       │   └── routes.py\n│       ├── models/\n│       │   ├── __init__.py\n│       │   └── user.py\n│       └── utils/\n│           ├── __init__.py\n│           └── helpers.py\n├── tests/\n│   ├── __init__.py\n│   ├── conftest.py\n│   ├── test_api.py\n│   └── test_models.py\n├── pyproject.toml\n├── README.md\n└── .gitignore\n```\n\n### Import Conventions\n\n```python\n# Good: Import order - stdlib, third-party, local\nimport os\nimport sys\nfrom pathlib import Path\n\nimport requests\nfrom fastapi import FastAPI\n\nfrom mypackage.models import User\nfrom mypackage.utils import format_name\n\n# Good: Use isort for automatic import sorting\n# pip install isort\n```\n\n### __init__.py for Package Exports\n\n```python\n# mypackage/__init__.py\n\"\"\"mypackage - A sample Python package.\"\"\"\n\n__version__ = \"1.0.0\"\n\n# Export main classes/functions at package level\nfrom mypackage.models import User, Post\nfrom mypackage.utils import format_name\n\n__all__ = [\"User\", \"Post\", \"format_name\"]\n```\n\n## Memory and Performance\n\n### Using __slots__ for Memory Efficiency\n\n```python\n# Bad: Regular class uses __dict__ (more memory)\nclass Point:\n    def __init__(self, x: float, y: float):\n        self.x = x\n        self.y = y\n\n# Good: __slots__ reduces memory usage\nclass Point:\n    __slots__ = ['x', 'y']\n\n    def __init__(self, x: float, y: float):\n        self.x = x\n        self.y = y\n```\n\n### Generator for Large Data\n\n```python\n# Bad: Returns full list in memory\ndef read_lines(path: str) -> list[str]:\n    with open(path) as f:\n        return [line.strip() for line in f]\n\n# Good: Yields lines one at a time\ndef read_lines(path: str) -> Iterator[str]:\n    with open(path) as f:\n        for line in f:\n            yield line.strip()\n```\n\n### Avoid String Concatenation in Loops\n\n```python\n# Bad: O(n²) due to string immutability\nresult = \"\"\nfor item in items:\n    result += str(item)\n\n# Good: O(n) using join\nresult = \"\".join(str(item) for item in items)\n\n# Good: Using StringIO for building\nfrom io import StringIO\n\nbuffer = StringIO()\nfor item in items:\n    buffer.write(str(item))\nresult = buffer.getvalue()\n```\n\n## Python Tooling Integration\n\n### Essential Commands\n\n```bash\n# Code formatting\nblack .\nisort .\n\n# Linting\nruff check .\npylint mypackage/\n\n# Type checking\nmypy .\n\n# Testing\npytest --cov=mypackage --cov-report=html\n\n# Security scanning\nbandit -r .\n\n# Dependency management\npip-audit\nsafety check\n```\n\n### pyproject.toml Configuration\n\n```toml\n[project]\nname = \"mypackage\"\nversion = \"1.0.0\"\nrequires-python = \">=3.9\"\ndependencies = [\n    \"requests>=2.31.0\",\n    \"pydantic>=2.0.0\",\n]\n\n[project.optional-dependencies]\ndev = [\n    \"pytest>=7.4.0\",\n    \"pytest-cov>=4.1.0\",\n    \"black>=23.0.0\",\n    \"ruff>=0.1.0\",\n    \"mypy>=1.5.0\",\n]\n\n[tool.black]\nline-length = 88\ntarget-version = ['py39']\n\n[tool.ruff]\nline-length = 88\nselect = [\"E\", \"F\", \"I\", \"N\", \"W\"]\n\n[tool.mypy]\npython_version = \"3.9\"\nwarn_return_any = true\nwarn_unused_configs = true\ndisallow_untyped_defs = true\n\n[tool.pytest.ini_options]\ntestpaths = [\"tests\"]\naddopts = \"--cov=mypackage --cov-report=term-missing\"\n```\n\n## Quick Reference: Python Idioms\n\n| Idiom | Description |\n|-------|-------------|\n| EAFP | Easier to Ask Forgiveness than Permission |\n| Context managers | Use `with` for resource management |\n| List comprehensions | For simple transformations |\n| Generators | For lazy evaluation and large datasets |\n| Type hints | Annotate function signatures |\n| Dataclasses | For data containers with auto-generated methods |\n| `__slots__` | For memory optimization |\n| f-strings | For string formatting (Python 3.6+) |\n| `pathlib.Path` | For path operations (Python 3.4+) |\n| `enumerate` | For index-element pairs in loops |\n\n## Anti-Patterns to Avoid\n\n```python\n# Bad: Mutable default arguments\ndef append_to(item, items=[]):\n    items.append(item)\n    return items\n\n# Good: Use None and create new list\ndef append_to(item, items=None):\n    if items is None:\n        items = []\n    items.append(item)\n    return items\n\n# Bad: Checking type with type()\nif type(obj) == list:\n    process(obj)\n\n# Good: Use isinstance\nif isinstance(obj, list):\n    process(obj)\n\n# Bad: Comparing to None with ==\nif value == None:\n    process()\n\n# Good: Use is\nif value is None:\n    process()\n\n# Bad: from module import *\nfrom os.path import *\n\n# Good: Explicit imports\nfrom os.path import join, exists\n\n# Bad: Bare except\ntry:\n    risky_operation()\nexcept:\n    pass\n\n# Good: Specific exception\ntry:\n    risky_operation()\nexcept SpecificError as e:\n    logger.error(f\"Operation failed: {e}\")\n```\n\n__Remember__: Python code should be readable, explicit, and follow the principle of least surprise. When in doubt, prioritize clarity over cleverness.\n"
+    },
+    {
+      "name": "python-testing",
+      "description": "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.",
+      "category": "testing",
+      "body": "# Python Testing Patterns\n\nComprehensive testing strategies for Python applications using pytest, TDD methodology, and best practices.\n\n## When to Activate\n\n- Writing new Python code (follow TDD: red, green, refactor)\n- Designing test suites for Python projects\n- Reviewing Python test coverage\n- Setting up testing infrastructure\n\n## Core Testing Philosophy\n\n### Test-Driven Development (TDD)\n\nAlways follow the TDD cycle:\n\n1. **RED**: Write a failing test for the desired behavior\n2. **GREEN**: Write minimal code to make the test pass\n3. **REFACTOR**: Improve code while keeping tests green\n\n```python\n# Step 1: Write failing test (RED)\ndef test_add_numbers():\n    result = add(2, 3)\n    assert result == 5\n\n# Step 2: Write minimal implementation (GREEN)\ndef add(a, b):\n    return a + b\n\n# Step 3: Refactor if needed (REFACTOR)\n```\n\n### Coverage Requirements\n\n- **Target**: 80%+ code coverage\n- **Critical paths**: 100% coverage required\n- Use `pytest --cov` to measure coverage\n\n```bash\npytest --cov=mypackage --cov-report=term-missing --cov-report=html\n```\n\n## pytest Fundamentals\n\n### Basic Test Structure\n\n```python\nimport pytest\n\ndef test_addition():\n    \"\"\"Test basic addition.\"\"\"\n    assert 2 + 2 == 4\n\ndef test_string_uppercase():\n    \"\"\"Test string uppercasing.\"\"\"\n    text = \"hello\"\n    assert text.upper() == \"HELLO\"\n\ndef test_list_append():\n    \"\"\"Test list append.\"\"\"\n    items = [1, 2, 3]\n    items.append(4)\n    assert 4 in items\n    assert len(items) == 4\n```\n\n### Assertions\n\n```python\n# Equality\nassert result == expected\n\n# Inequality\nassert result != unexpected\n\n# Truthiness\nassert result  # Truthy\nassert not result  # Falsy\nassert result is True  # Exactly True\nassert result is False  # Exactly False\nassert result is None  # Exactly None\n\n# Membership\nassert item in collection\nassert item not in collection\n\n# Comparisons\nassert result > 0\nassert 0 <= result <= 100\n\n# Type checking\nassert isinstance(result, str)\n\n# Exception testing (preferred approach)\nwith pytest.raises(ValueError):\n    raise ValueError(\"error message\")\n\n# Check exception message\nwith pytest.raises(ValueError, match=\"invalid input\"):\n    raise ValueError(\"invalid input provided\")\n\n# Check exception attributes\nwith pytest.raises(ValueError) as exc_info:\n    raise ValueError(\"error message\")\nassert str(exc_info.value) == \"error message\"\n```\n\n## Fixtures\n\n### Basic Fixture Usage\n\n```python\nimport pytest\n\n@pytest.fixture\ndef sample_data():\n    \"\"\"Fixture providing sample data.\"\"\"\n    return {\"name\": \"Alice\", \"age\": 30}\n\ndef test_sample_data(sample_data):\n    \"\"\"Test using the fixture.\"\"\"\n    assert sample_data[\"name\"] == \"Alice\"\n    assert sample_data[\"age\"] == 30\n```\n\n### Fixture with Setup/Teardown\n\n```python\n@pytest.fixture\ndef database():\n    \"\"\"Fixture with setup and teardown.\"\"\"\n    # Setup\n    db = Database(\":memory:\")\n    db.create_tables()\n    db.insert_test_data()\n\n    yield db  # Provide to test\n\n    # Teardown\n    db.close()\n\ndef test_database_query(database):\n    \"\"\"Test database operations.\"\"\"\n    result = database.query(\"SELECT * FROM users\")\n    assert len(result) > 0\n```\n\n### Fixture Scopes\n\n```python\n# Function scope (default) - runs for each test\n@pytest.fixture\ndef temp_file():\n    with open(\"temp.txt\", \"w\") as f:\n        yield f\n    os.remove(\"temp.txt\")\n\n# Module scope - runs once per module\n@pytest.fixture(scope=\"module\")\ndef module_db():\n    db = Database(\":memory:\")\n    db.create_tables()\n    yield db\n    db.close()\n\n# Session scope - runs once per test session\n@pytest.fixture(scope=\"session\")\ndef shared_resource():\n    resource = ExpensiveResource()\n    yield resource\n    resource.cleanup()\n```\n\n### Fixture with Parameters\n\n```python\n@pytest.fixture(params=[1, 2, 3])\ndef number(request):\n    \"\"\"Parameterized fixture.\"\"\"\n    return request.param\n\ndef test_numbers(number):\n    \"\"\"Test runs 3 times, once for each parameter.\"\"\"\n    assert number > 0\n```\n\n### Using Multiple Fixtures\n\n```python\n@pytest.fixture\ndef user():\n    return User(id=1, name=\"Alice\")\n\n@pytest.fixture\ndef admin():\n    return User(id=2, name=\"Admin\", role=\"admin\")\n\ndef test_user_admin_interaction(user, admin):\n    \"\"\"Test using multiple fixtures.\"\"\"\n    assert admin.can_manage(user)\n```\n\n### Autouse Fixtures\n\n```python\n@pytest.fixture(autouse=True)\ndef reset_config():\n    \"\"\"Automatically runs before every test.\"\"\"\n    Config.reset()\n    yield\n    Config.cleanup()\n\ndef test_without_fixture_call():\n    # reset_config runs automatically\n    assert Config.get_setting(\"debug\") is False\n```\n\n### Conftest.py for Shared Fixtures\n\n```python\n# tests/conftest.py\nimport pytest\n\n@pytest.fixture\ndef client():\n    \"\"\"Shared fixture for all tests.\"\"\"\n    app = create_app(testing=True)\n    with app.test_client() as client:\n        yield client\n\n@pytest.fixture\ndef auth_headers(client):\n    \"\"\"Generate auth headers for API testing.\"\"\"\n    response = client.post(\"/api/login\", json={\n        \"username\": \"test\",\n        \"password\": \"test\"\n    })\n    token = response.json[\"token\"]\n    return {\"Authorization\": f\"Bearer {token}\"}\n```\n\n## Parametrization\n\n### Basic Parametrization\n\n```python\n@pytest.mark.parametrize(\"input,expected\", [\n    (\"hello\", \"HELLO\"),\n    (\"world\", \"WORLD\"),\n    (\"PyThOn\", \"PYTHON\"),\n])\ndef test_uppercase(input, expected):\n    \"\"\"Test runs 3 times with different inputs.\"\"\"\n    assert input.upper() == expected\n```\n\n### Multiple Parameters\n\n```python\n@pytest.mark.parametrize(\"a,b,expected\", [\n    (2, 3, 5),\n    (0, 0, 0),\n    (-1, 1, 0),\n    (100, 200, 300),\n])\ndef test_add(a, b, expected):\n    \"\"\"Test addition with multiple inputs.\"\"\"\n    assert add(a, b) == expected\n```\n\n### Parametrize with IDs\n\n```python\n@pytest.mark.parametrize(\"input,expected\", [\n    (\"valid@email.com\", True),\n    (\"invalid\", False),\n    (\"@no-domain.com\", False),\n], ids=[\"valid-email\", \"missing-at\", \"missing-domain\"])\ndef test_email_validation(input, expected):\n    \"\"\"Test email validation with readable test IDs.\"\"\"\n    assert is_valid_email(input) is expected\n```\n\n### Parametrized Fixtures\n\n```python\n@pytest.fixture(params=[\"sqlite\", \"postgresql\", \"mysql\"])\ndef db(request):\n    \"\"\"Test against multiple database backends.\"\"\"\n    if request.param == \"sqlite\":\n        return Database(\":memory:\")\n    elif request.param == \"postgresql\":\n        return Database(\"postgresql://localhost/test\")\n    elif request.param == \"mysql\":\n        return Database(\"mysql://localhost/test\")\n\ndef test_database_operations(db):\n    \"\"\"Test runs 3 times, once for each database.\"\"\"\n    result = db.query(\"SELECT 1\")\n    assert result is not None\n```\n\n## Markers and Test Selection\n\n### Custom Markers\n\n```python\n# Mark slow tests\n@pytest.mark.slow\ndef test_slow_operation():\n    time.sleep(5)\n\n# Mark integration tests\n@pytest.mark.integration\ndef test_api_integration():\n    response = requests.get(\"https://api.example.com\")\n    assert response.status_code == 200\n\n# Mark unit tests\n@pytest.mark.unit\ndef test_unit_logic():\n    assert calculate(2, 3) == 5\n```\n\n### Run Specific Tests\n\n```bash\n# Run only fast tests\npytest -m \"not slow\"\n\n# Run only integration tests\npytest -m integration\n\n# Run integration or slow tests\npytest -m \"integration or slow\"\n\n# Run tests marked as unit but not slow\npytest -m \"unit and not slow\"\n```\n\n### Configure Markers in pytest.ini\n\n```ini\n[pytest]\nmarkers =\n    slow: marks tests as slow\n    integration: marks tests as integration tests\n    unit: marks tests as unit tests\n    django: marks tests as requiring Django\n```\n\n## Mocking and Patching\n\n### Mocking Functions\n\n```python\nfrom unittest.mock import patch, Mock\n\n@patch(\"mypackage.external_api_call\")\ndef test_with_mock(api_call_mock):\n    \"\"\"Test with mocked external API.\"\"\"\n    api_call_mock.return_value = {\"status\": \"success\"}\n\n    result = my_function()\n\n    api_call_mock.assert_called_once()\n    assert result[\"status\"] == \"success\"\n```\n\n### Mocking Return Values\n\n```python\n@patch(\"mypackage.Database.connect\")\ndef test_database_connection(connect_mock):\n    \"\"\"Test with mocked database connection.\"\"\"\n    connect_mock.return_value = MockConnection()\n\n    db = Database()\n    db.connect()\n\n    connect_mock.assert_called_once_with(\"localhost\")\n```\n\n### Mocking Exceptions\n\n```python\n@patch(\"mypackage.api_call\")\ndef test_api_error_handling(api_call_mock):\n    \"\"\"Test error handling with mocked exception.\"\"\"\n    api_call_mock.side_effect = ConnectionError(\"Network error\")\n\n    with pytest.raises(ConnectionError):\n        api_call()\n\n    api_call_mock.assert_called_once()\n```\n\n### Mocking Context Managers\n\n```python\n@patch(\"builtins.open\", new_callable=mock_open)\ndef test_file_reading(mock_file):\n    \"\"\"Test file reading with mocked open.\"\"\"\n    mock_file.return_value.read.return_value = \"file content\"\n\n    result = read_file(\"test.txt\")\n\n    mock_file.assert_called_once_with(\"test.txt\", \"r\")\n    assert result == \"file content\"\n```\n\n### Using Autospec\n\n```python\n@patch(\"mypackage.DBConnection\", autospec=True)\ndef test_autospec(db_mock):\n    \"\"\"Test with autospec to catch API misuse.\"\"\"\n    db = db_mock.return_value\n    db.query(\"SELECT * FROM users\")\n\n    # This would fail if DBConnection doesn't have query method\n    db_mock.assert_called_once()\n```\n\n### Mock Class Instances\n\n```python\nclass TestUserService:\n    @patch(\"mypackage.UserRepository\")\n    def test_create_user(self, repo_mock):\n        \"\"\"Test user creation with mocked repository.\"\"\"\n        repo_mock.return_value.save.return_value = User(id=1, name=\"Alice\")\n\n        service = UserService(repo_mock.return_value)\n        user = service.create_user(name=\"Alice\")\n\n        assert user.name == \"Alice\"\n        repo_mock.return_value.save.assert_called_once()\n```\n\n### Mock Property\n\n```python\n@pytest.fixture\ndef mock_config():\n    \"\"\"Create a mock with a property.\"\"\"\n    config = Mock()\n    type(config).debug = PropertyMock(return_value=True)\n    type(config).api_key = PropertyMock(return_value=\"test-key\")\n    return config\n\ndef test_with_mock_config(mock_config):\n    \"\"\"Test with mocked config properties.\"\"\"\n    assert mock_config.debug is True\n    assert mock_config.api_key == \"test-key\"\n```\n\n## Testing Async Code\n\n### Async Tests with pytest-asyncio\n\n```python\nimport pytest\n\n@pytest.mark.asyncio\nasync def test_async_function():\n    \"\"\"Test async function.\"\"\"\n    result = await async_add(2, 3)\n    assert result == 5\n\n@pytest.mark.asyncio\nasync def test_async_with_fixture(async_client):\n    \"\"\"Test async with async fixture.\"\"\"\n    response = await async_client.get(\"/api/users\")\n    assert response.status_code == 200\n```\n\n### Async Fixture\n\n```python\n@pytest.fixture\nasync def async_client():\n    \"\"\"Async fixture providing async test client.\"\"\"\n    app = create_app()\n    async with app.test_client() as client:\n        yield client\n\n@pytest.mark.asyncio\nasync def test_api_endpoint(async_client):\n    \"\"\"Test using async fixture.\"\"\"\n    response = await async_client.get(\"/api/data\")\n    assert response.status_code == 200\n```\n\n### Mocking Async Functions\n\n```python\n@pytest.mark.asyncio\n@patch(\"mypackage.async_api_call\")\nasync def test_async_mock(api_call_mock):\n    \"\"\"Test async function with mock.\"\"\"\n    api_call_mock.return_value = {\"status\": \"ok\"}\n\n    result = await my_async_function()\n\n    api_call_mock.assert_awaited_once()\n    assert result[\"status\"] == \"ok\"\n```\n\n## Testing Exceptions\n\n### Testing Expected Exceptions\n\n```python\ndef test_divide_by_zero():\n    \"\"\"Test that dividing by zero raises ZeroDivisionError.\"\"\"\n    with pytest.raises(ZeroDivisionError):\n        divide(10, 0)\n\ndef test_custom_exception():\n    \"\"\"Test custom exception with message.\"\"\"\n    with pytest.raises(ValueError, match=\"invalid input\"):\n        validate_input(\"invalid\")\n```\n\n### Testing Exception Attributes\n\n```python\ndef test_exception_with_details():\n    \"\"\"Test exception with custom attributes.\"\"\"\n    with pytest.raises(CustomError) as exc_info:\n        raise CustomError(\"error\", code=400)\n\n    assert exc_info.value.code == 400\n    assert \"error\" in str(exc_info.value)\n```\n\n## Testing Side Effects\n\n### Testing File Operations\n\n```python\nimport tempfile\nimport os\n\ndef test_file_processing():\n    \"\"\"Test file processing with temp file.\"\"\"\n    with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.txt') as f:\n        f.write(\"test content\")\n        temp_path = f.name\n\n    try:\n        result = process_file(temp_path)\n        assert result == \"processed: test content\"\n    finally:\n        os.unlink(temp_path)\n```\n\n### Testing with pytest's tmp_path Fixture\n\n```python\ndef test_with_tmp_path(tmp_path):\n    \"\"\"Test using pytest's built-in temp path fixture.\"\"\"\n    test_file = tmp_path / \"test.txt\"\n    test_file.write_text(\"hello world\")\n\n    result = process_file(str(test_file))\n    assert result == \"hello world\"\n    # tmp_path automatically cleaned up\n```\n\n### Testing with tmpdir Fixture\n\n```python\ndef test_with_tmpdir(tmpdir):\n    \"\"\"Test using pytest's tmpdir fixture.\"\"\"\n    test_file = tmpdir.join(\"test.txt\")\n    test_file.write(\"data\")\n\n    result = process_file(str(test_file))\n    assert result == \"data\"\n```\n\n## Test Organization\n\n### Directory Structure\n\n```\ntests/\n├── conftest.py                 # Shared fixtures\n├── __init__.py\n├── unit/                       # Unit tests\n│   ├── __init__.py\n│   ├── test_models.py\n│   ├── test_utils.py\n│   └── test_services.py\n├── integration/                # Integration tests\n│   ├── __init__.py\n│   ├── test_api.py\n│   └── test_database.py\n└── e2e/                        # End-to-end tests\n    ├── __init__.py\n    └── test_user_flow.py\n```\n\n### Test Classes\n\n```python\nclass TestUserService:\n    \"\"\"Group related tests in a class.\"\"\"\n\n    @pytest.fixture(autouse=True)\n    def setup(self):\n        \"\"\"Setup runs before each test in this class.\"\"\"\n        self.service = UserService()\n\n    def test_create_user(self):\n        \"\"\"Test user creation.\"\"\"\n        user = self.service.create_user(\"Alice\")\n        assert user.name == \"Alice\"\n\n    def test_delete_user(self):\n        \"\"\"Test user deletion.\"\"\"\n        user = User(id=1, name=\"Bob\")\n        self.service.delete_user(user)\n        assert not self.service.user_exists(1)\n```\n\n## Best Practices\n\n### DO\n\n- **Follow TDD**: Write tests before code (red-green-refactor)\n- **Test one thing**: Each test should verify a single behavior\n- **Use descriptive names**: `test_user_login_with_invalid_credentials_fails`\n- **Use fixtures**: Eliminate duplication with fixtures\n- **Mock external dependencies**: Don't depend on external services\n- **Test edge cases**: Empty inputs, None values, boundary conditions\n- **Aim for 80%+ coverage**: Focus on critical paths\n- **Keep tests fast**: Use marks to separate slow tests\n\n### DON'T\n\n- **Don't test implementation**: Test behavior, not internals\n- **Don't use complex conditionals in tests**: Keep tests simple\n- **Don't ignore test failures**: All tests must pass\n- **Don't test third-party code**: Trust libraries to work\n- **Don't share state between tests**: Tests should be independent\n- **Don't catch exceptions in tests**: Use `pytest.raises`\n- **Don't use print statements**: Use assertions and pytest output\n- **Don't write tests that are too brittle**: Avoid over-specific mocks\n\n## Common Patterns\n\n### Testing API Endpoints (FastAPI/Flask)\n\n```python\n@pytest.fixture\ndef client():\n    app = create_app(testing=True)\n    return app.test_client()\n\ndef test_get_user(client):\n    response = client.get(\"/api/users/1\")\n    assert response.status_code == 200\n    assert response.json[\"id\"] == 1\n\ndef test_create_user(client):\n    response = client.post(\"/api/users\", json={\n        \"name\": \"Alice\",\n        \"email\": \"alice@example.com\"\n    })\n    assert response.status_code == 201\n    assert response.json[\"name\"] == \"Alice\"\n```\n\n### Testing Database Operations\n\n```python\n@pytest.fixture\ndef db_session():\n    \"\"\"Create a test database session.\"\"\"\n    session = Session(bind=engine)\n    session.begin_nested()\n    yield session\n    session.rollback()\n    session.close()\n\ndef test_create_user(db_session):\n    user = User(name=\"Alice\", email=\"alice@example.com\")\n    db_session.add(user)\n    db_session.commit()\n\n    retrieved = db_session.query(User).filter_by(name=\"Alice\").first()\n    assert retrieved.email == \"alice@example.com\"\n```\n\n### Testing Class Methods\n\n```python\nclass TestCalculator:\n    @pytest.fixture\n    def calculator(self):\n        return Calculator()\n\n    def test_add(self, calculator):\n        assert calculator.add(2, 3) == 5\n\n    def test_divide_by_zero(self, calculator):\n        with pytest.raises(ZeroDivisionError):\n            calculator.divide(10, 0)\n```\n\n## pytest Configuration\n\n### pytest.ini\n\n```ini\n[pytest]\ntestpaths = tests\npython_files = test_*.py\npython_classes = Test*\npython_functions = test_*\naddopts =\n    --strict-markers\n    --disable-warnings\n    --cov=mypackage\n    --cov-report=term-missing\n    --cov-report=html\nmarkers =\n    slow: marks tests as slow\n    integration: marks tests as integration tests\n    unit: marks tests as unit tests\n```\n\n### pyproject.toml\n\n```toml\n[tool.pytest.ini_options]\ntestpaths = [\"tests\"]\npython_files = [\"test_*.py\"]\npython_classes = [\"Test*\"]\npython_functions = [\"test_*\"]\naddopts = [\n    \"--strict-markers\",\n    \"--cov=mypackage\",\n    \"--cov-report=term-missing\",\n    \"--cov-report=html\",\n]\nmarkers = [\n    \"slow: marks tests as slow\",\n    \"integration: marks tests as integration tests\",\n    \"unit: marks tests as unit tests\",\n]\n```\n\n## Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run specific file\npytest tests/test_utils.py\n\n# Run specific test\npytest tests/test_utils.py::test_function\n\n# Run with verbose output\npytest -v\n\n# Run with coverage\npytest --cov=mypackage --cov-report=html\n\n# Run only fast tests\npytest -m \"not slow\"\n\n# Run until first failure\npytest -x\n\n# Run and stop on N failures\npytest --maxfail=3\n\n# Run last failed tests\npytest --lf\n\n# Run tests with pattern\npytest -k \"test_user\"\n\n# Run with debugger on failure\npytest --pdb\n```\n\n## Quick Reference\n\n| Pattern | Usage |\n|---------|-------|\n| `pytest.raises()` | Test expected exceptions |\n| `@pytest.fixture()` | Create reusable test fixtures |\n| `@pytest.mark.parametrize()` | Run tests with multiple inputs |\n| `@pytest.mark.slow` | Mark slow tests |\n| `pytest -m \"not slow\"` | Skip slow tests |\n| `@patch()` | Mock functions and classes |\n| `tmp_path` fixture | Automatic temp directory |\n| `pytest --cov` | Generate coverage report |\n| `assert` | Simple and readable assertions |\n\n**Remember**: Tests are code too. Keep them clean, readable, and maintainable. Good tests catch bugs; great tests prevent them.\n"
+    },
+    {
+      "name": "fastapi-patterns",
+      "description": "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.",
+      "category": "write",
+      "body": "# FastAPI Patterns\n\nModern, production-grade FastAPI development: project layout, Pydantic v2 schemas, dependency injection, async patterns, auth, transactional service methods, and testing.\n\n## Project Structure\n\n```text\nmy_app/\n|-- app/\n|   |-- main.py               # App factory, lifespan, middleware\n|   |-- config.py             # Settings via pydantic-settings\n|   |-- dependencies.py       # Shared FastAPI dependencies\n|   |-- database.py           # SQLAlchemy engine + session\n|   |-- routers/\n|   |   `-- users.py\n|   |-- models/               # SQLAlchemy ORM models\n|   |   `-- user.py\n|   |-- schemas/              # Pydantic request/response schemas\n|   |   `-- user.py\n|   `-- services/             # Business logic layer\n|       `-- user_service.py\n|-- tests/\n|   |-- conftest.py\n|   `-- test_users.py\n|-- pyproject.toml\n`-- .env\n```\n\n---\n\n## App Factory and Lifespan\n\n```python\n# app/main.py\nfrom contextlib import asynccontextmanager\nfrom fastapi import FastAPI\nfrom fastapi.middleware.cors import CORSMiddleware\n\nfrom app.config import settings\nfrom app.database import engine, Base\nfrom app.routers import users\n\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n    # Automatically create tables on startup for ease of use in dev/demo environments.\n    # For strict production applications, manage schemas via Alembic migrations instead.\n    async with engine.begin() as conn:\n        await conn.run_sync(Base.metadata.create_all)\n    yield\n    # Shutdown: close pooled resources.\n    await engine.dispose()\n\n\ndef create_app() -> FastAPI:\n    app = FastAPI(\n        title=settings.app_name,\n        version=settings.app_version,\n        lifespan=lifespan,\n    )\n\n    app.add_middleware(\n        CORSMiddleware,\n        allow_origins=settings.allowed_origins,\n        allow_credentials=settings.allow_credentials,\n        allow_methods=settings.allowed_methods,\n        allow_headers=settings.allowed_headers,\n    )\n\n    app.include_router(users.router, prefix=\"/users\", tags=[\"users\"])\n\n    return app\n\n\napp = create_app()\n```\n\n---\n\n## Configuration with pydantic-settings\n\n```python\n# app/config.py\nfrom pydantic_settings import BaseSettings, SettingsConfigDict\n\n\nclass Settings(BaseSettings):\n    model_config = SettingsConfigDict(env_file=\".env\", env_file_encoding=\"utf-8\")\n\n    app_name: str = \"My App\"\n    app_version: str = \"0.1.0\"\n    debug: bool = False\n\n    database_url: str\n    secret_key: str\n    algorithm: str = \"HS256\"\n    access_token_expire_minutes: int = 30\n\n    # Pydantic-settings v2 safely evaluates mutable list literals directly\n    allowed_origins: list[str] = [\"http://localhost:3000\"]\n    allowed_methods: list[str] = [\"GET\", \"POST\", \"PATCH\", \"DELETE\", \"OPTIONS\"]\n    allowed_headers: list[str] = [\"Authorization\", \"Content-Type\"]\n    allow_credentials: bool = True\n\n\nsettings = Settings()\n```\n\n---\n\n## Pydantic Schemas (v2)\n\n```python\n# app/schemas/user.py\nfrom datetime import datetime\nfrom pydantic import BaseModel, EmailStr, Field, model_validator\n\n\nclass UserBase(BaseModel):\n    email: EmailStr\n    username: str = Field(min_length=3, max_length=50)\n\n\nclass UserCreate(UserBase):\n    password: str = Field(min_length=8)\n    password_confirm: str\n\n    @model_validator(mode=\"after\")\n    def passwords_match(self) -> \"UserCreate\":\n        if self.password != self.password_confirm:\n            raise ValueError(\"Passwords do not match\")\n        return self\n\n\nclass UserUpdate(BaseModel):\n    username: str | None = Field(default=None, min_length=3, max_length=50)\n    email: EmailStr | None = None\n\n\nclass UserResponse(UserBase):\n    id: int\n    is_active: bool\n    created_at: datetime\n\n    model_config = {\"from_attributes\": True}\n\n\nclass UserListResponse(BaseModel):\n    total: int\n    items: list[UserResponse]\n```\n\n---\n\n## Dependency Injection\n\n```python\n# app/dependencies.py\nfrom typing import Annotated, AsyncGenerator\nfrom fastapi import Depends, HTTPException, status\nfrom fastapi.security import OAuth2PasswordBearer\nfrom jose import JWTError, jwt\nfrom sqlalchemy.ext.asyncio import AsyncSession\n\nfrom app.config import settings\nfrom app.database import AsyncSessionLocal\nfrom app.models.user import User\n\noauth2_scheme = OAuth2PasswordBearer(tokenUrl=\"/users/token\")\n\n\nasync def get_db() -> AsyncGenerator[AsyncSession, None]:\n    async with AsyncSessionLocal() as session:\n        try:\n            yield session\n        except Exception:\n            await session.rollback()\n            raise\n\n\nasync def get_current_user(\n    token: Annotated[str, Depends(oauth2_scheme)],\n    db: Annotated[AsyncSession, Depends(get_db)],\n) -> User:\n    credentials_exception = HTTPException(\n        status_code=status.HTTP_401_UNAUTHORIZED,\n        detail=\"Could not validate credentials\",\n        headers={\"WWW-Authenticate\": \"Bearer\"},\n    )\n    try:\n        payload = jwt.decode(token, settings.secret_key, algorithms=[settings.algorithm])\n        subject = payload.get(\"sub\")\n        if subject is None:\n            raise credentials_exception\n        user_id = int(subject)\n    except (JWTError, TypeError, ValueError):\n        raise credentials_exception\n\n    user = await db.get(User, user_id)\n    if user is None:\n        raise credentials_exception\n    return user\n\n\nasync def get_current_active_user(\n    current_user: Annotated[User, Depends(get_current_user)],\n) -> User:\n    if not current_user.is_active:\n        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=\"Inactive user\")\n    return current_user\n\n\nDbDep = Annotated[AsyncSession, Depends(get_db)]\nCurrentUserDep = Annotated[User, Depends(get_current_user)]\nActiveUserDep = Annotated[User, Depends(get_current_active_user)]\n```\n\n---\n\n## Router and Endpoint Design\n\n```python\n# app/routers/users.py\nfrom typing import Annotated\nfrom fastapi import APIRouter, HTTPException, Query, status\nfrom fastapi.security import OAuth2PasswordRequestForm\n\nfrom app.dependencies import ActiveUserDep, DbDep\nfrom app.schemas.user import UserCreate, UserResponse, UserUpdate, UserListResponse\nfrom app.services.user_service import DuplicateUserError, UserService\n\nrouter = APIRouter()\n\n\n@router.post(\"/\", response_model=UserResponse, status_code=status.HTTP_201_CREATED)\nasync def create_user(payload: UserCreate, db: DbDep) -> UserResponse:\n    service = UserService(db)\n    try:\n        return await service.create(payload)\n    except DuplicateUserError:\n        raise HTTPException(status_code=400, detail=\"Email already registered\")\n\n\n@router.get(\"/me\", response_model=UserResponse)\nasync def get_me(current_user: ActiveUserDep) -> UserResponse:\n    return current_user\n\n\n@router.get(\"/\", response_model=UserListResponse)\nasync def list_users(\n    db: DbDep,\n    current_user: ActiveUserDep,\n    skip: Annotated[int, Query(ge=0)] = 0,\n    limit: Annotated[int, Query(ge=1, le=100)] = 20,\n) -> UserListResponse:\n    service = UserService(db)\n    users, total = await service.list(skip=skip, limit=limit)\n    return UserListResponse(total=total, items=users)\n\n\n@router.patch(\"/{user_id}\", response_model=UserResponse)\nasync def update_user(\n    user_id: int,\n    payload: UserUpdate,\n    db: DbDep,\n    current_user: ActiveUserDep,\n) -> UserResponse:\n    if current_user.id != user_id:\n        raise HTTPException(status_code=403, detail=\"Not authorized\")\n    service = UserService(db)\n    try:\n        user = await service.update(user_id, payload)\n    except DuplicateUserError:\n        raise HTTPException(status_code=400, detail=\"Email already registered\")\n    if user is None:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user\n\n\n@router.post(\"/token\")\nasync def login(\n    form_data: Annotated[OAuth2PasswordRequestForm, Depends()],\n    db: DbDep,\n) -> dict[str, str]:\n    service = UserService(db)\n    token = await service.authenticate(form_data.username, form_data.password)\n    if token is None:\n        raise HTTPException(\n            status_code=status.HTTP_401_UNAUTHORIZED,\n            detail=\"Incorrect username or password\",\n            headers={\"WWW-Authenticate\": \"Bearer\"},\n        )\n    return {\"access_token\": token, \"token_type\": \"bearer\"}\n```\n\n---\n\n## Service Layer\n\n```python\n# app/services/user_service.py\nfrom datetime import datetime, timedelta, timezone\n\nfrom jose import jwt\nfrom passlib.context import CryptContext\nfrom sqlalchemy import func, select\nfrom sqlalchemy.exc import IntegrityError\nfrom sqlalchemy.ext.asyncio import AsyncSession\n\nfrom app.config import settings\nfrom app.models.user import User\nfrom app.schemas.user import UserCreate, UserUpdate\n\npwd_context = CryptContext(schemes=[\"bcrypt\"], deprecated=\"auto\")\n\n\nclass DuplicateUserError(Exception):\n    \"\"\"Raised when a unique user field conflicts with an existing row.\"\"\"\n\n\nclass UserService:\n    def __init__(self, db: AsyncSession) -> None:\n        self.db = db\n\n    async def get_by_email(self, email: str) -> User | None:\n        result = await self.db.execute(select(User).where(User.email == email))\n        return result.scalar_one_or_none()\n\n    async def create(self, payload: UserCreate) -> User:\n        user = User(\n            email=payload.email,\n            username=payload.username,\n            hashed_password=pwd_context.hash(payload.password),\n        )\n        self.db.add(user)\n        try:\n            # Rely on atomic DB constraints rather than race-prone application-level prechecks\n            await self.db.commit()\n        except IntegrityError as exc:\n            await self.db.rollback()\n            raise DuplicateUserError from exc\n        await self.db.refresh(user)\n        return user\n\n    async def list(self, skip: int = 0, limit: int = 20) -> tuple[list[User], int]:\n        total_result = await self.db.execute(select(func.count(User.id)))\n        total = total_result.scalar_one()\n        # Enforce explicit deterministic ordering to ensure reliable pagination\n        result = await self.db.execute(\n            select(User).order_by(User.id).offset(skip).limit(limit)\n        )\n        return list(result.scalars()), total\n\n    async def update(self, user_id: int, payload: UserUpdate) -> User | None:\n        user = await self.db.get(User, user_id)\n        if user is None:\n            return None\n        for field, value in payload.model_dump(exclude_unset=True).items():\n            setattr(user, field, value)\n        try:\n            await self.db.commit()\n        except IntegrityError as exc:\n            await self.db.rollback()\n            raise DuplicateUserError from exc\n        await self.db.refresh(user)\n        return user\n\n    async def authenticate(self, email: str, password: str) -> str | None:\n        user = await self.get_by_email(email)\n        if user is None or not pwd_context.verify(password, user.hashed_password):\n            return None\n        expire = datetime.now(timezone.utc) + timedelta(\n            minutes=settings.access_token_expire_minutes\n        )\n        return jwt.encode(\n            {\"sub\": str(user.id), \"exp\": expire},\n            settings.secret_key,\n            algorithm=settings.algorithm,\n        )\n```\n\n> **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.\n\n---\n\n## Testing with httpx and pytest\n\n```python\n# tests/conftest.py\nimport pytest_asyncio\nfrom httpx import ASGITransport, AsyncClient\nfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine\n\nfrom app.database import Base\nfrom app.dependencies import get_db\nfrom app.main import create_app\n\nTEST_DATABASE_URL = \"sqlite+aiosqlite:///:memory:\"\n\nengine = create_async_engine(TEST_DATABASE_URL)\nTestingSessionLocal = async_sessionmaker(engine, expire_on_commit=False)\n\n\n@pytest_asyncio.fixture(autouse=True)\nasync def setup_db():\n    async with engine.begin() as conn:\n        await conn.run_sync(Base.metadata.create_all)\n    yield\n    async with engine.begin() as conn:\n        await conn.run_sync(Base.metadata.drop_all)\n\n\n@pytest_asyncio.fixture\nasync def db_session():\n    async with TestingSessionLocal() as session:\n        yield session\n        await session.rollback()\n\n\n@pytest_asyncio.fixture\nasync def client(db_session: AsyncSession):\n    app = create_app()\n\n    async def override_get_db():\n        yield db_session\n\n    app.dependency_overrides[get_db] = override_get_db\n\n    async with AsyncClient(\n        transport=ASGITransport(app=app), base_url=\"http://test\"\n    ) as ac:\n        yield ac\n\n\n@pytest_asyncio.fixture\nasync def registered_user(client: AsyncClient) -> dict:\n    resp = await client.post(\"/users/\", json={\n        \"email\": \"test@example.com\",\n        \"username\": \"testuser\",\n        \"password\": \"securepass1\",\n        \"password_confirm\": \"securepass1\",\n    })\n    assert resp.status_code == 201\n    return resp.json()\n\n\n@pytest_asyncio.fixture\nasync def auth_token(client: AsyncClient, registered_user: dict) -> str:\n    resp = await client.post(\"/users/token\", data={\n        \"username\": \"test@example.com\",\n        \"password\": \"securepass1\",\n    })\n    assert resp.status_code == 200\n    return resp.json()[\"access_token\"]\n\n\n@pytest_asyncio.fixture\nasync def auth_client(client: AsyncClient, auth_token: str) -> AsyncClient:\n    client.headers.update({\"Authorization\": f\"Bearer {auth_token}\"})\n    return client\n```\n\n---\n\n## Anti-Patterns\n\n```python\n# Bad: business logic inside route handlers.\n@router.post(\"/users/\")\nasync def create_user(payload: UserCreate, db: DbDep):\n    hashed = bcrypt.hash(payload.password)\n    user = User(email=payload.email, hashed_password=hashed)\n    db.add(user)\n    await db.commit()\n    return user\n\n# Good: thin route, transactional service handling.\n@router.post(\"/users/\", response_model=UserResponse, status_code=201)\nasync def create_user(payload: UserCreate, db: DbDep):\n    try:\n        return await UserService(db).create(payload)\n    except DuplicateUserError:\n        raise HTTPException(status_code=400, detail=\"Email already registered\")\n\n\n# Bad: sync DB calls in async routes block the event loop.\n@router.get(\"/items/\")\nasync def list_items(db: Session = Depends(get_db)):\n    return db.query(Item).all()\n\n# Good: use async SQLAlchemy executions.\n@router.get(\"/items/\")\nasync def list_items(db: AsyncSession = Depends(get_db)):\n    result = await db.execute(select(Item))\n    return result.scalars().all()\n```\n\n---\n\n## Best Practices\n\n- Always declare a typed `response_model` to prevent accidental PII/data leaks and output clean OpenAPI schemas.\n- Consolidate standard middleware dependency injections via type-aliasing: `DbDep = Annotated[AsyncSession, Depends(get_db)]`.\n- Wrap database mutation boundaries gracefully within transactions inside your service layer, catching structural database errors directly.\n- Parse JWT parameters defensively, expecting potential string/integer cast mismatches from modern payload variations.\n- Enforce deterministic sorting (e.g., `.order_by(Model.id)`) on all offset/limit paginated endpoints to avoid data skips.\n- Isolate authorization checks from core authentication dependencies to provide precise REST status signals (`401` vs `403`).\n"
+    },
+    {
+      "name": "django-security",
+      "description": "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.",
+      "category": "review",
+      "body": "# Django Security Best Practices\n\nComprehensive security guidelines for Django applications to protect against common vulnerabilities.\n\n## When to Activate\n\n- Setting up Django authentication and authorization\n- Implementing user permissions and roles\n- Configuring production security settings\n- Reviewing Django application for security issues\n- Deploying Django applications to production\n\n## Core Security Settings\n\n### Production Settings Configuration\n\n```python\n# settings/production.py\nimport os\n\nDEBUG = False  # CRITICAL: Never use True in production\n\nALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', '').split(',')\n\n# Security headers\nSECURE_SSL_REDIRECT = True\nSESSION_COOKIE_SECURE = True\nCSRF_COOKIE_SECURE = True\nSECURE_HSTS_SECONDS = 31536000  # 1 year\nSECURE_HSTS_INCLUDE_SUBDOMAINS = True\nSECURE_HSTS_PRELOAD = True\nSECURE_CONTENT_TYPE_NOSNIFF = True\nSECURE_BROWSER_XSS_FILTER = True\nX_FRAME_OPTIONS = 'DENY'\n\n# HTTPS and Cookies\nSESSION_COOKIE_HTTPONLY = True\nCSRF_COOKIE_HTTPONLY = True\nSESSION_COOKIE_SAMESITE = 'Lax'\nCSRF_COOKIE_SAMESITE = 'Lax'\n\n# Secret key (must be set via environment variable)\nSECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')\nif not SECRET_KEY:\n    raise ImproperlyConfigured('DJANGO_SECRET_KEY environment variable is required')\n\n# Password validation\nAUTH_PASSWORD_VALIDATORS = [\n    {\n        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',\n    },\n    {\n        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',\n        'OPTIONS': {\n            'min_length': 12,\n        }\n    },\n    {\n        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',\n    },\n    {\n        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',\n    },\n]\n```\n\n## Authentication\n\n### Custom User Model\n\n```python\n# apps/users/models.py\nfrom django.contrib.auth.models import AbstractUser\nfrom django.db import models\n\nclass User(AbstractUser):\n    \"\"\"Custom user model for better security.\"\"\"\n\n    email = models.EmailField(unique=True)\n    phone = models.CharField(max_length=20, blank=True)\n\n    USERNAME_FIELD = 'email'  # Use email as username\n    REQUIRED_FIELDS = ['username']\n\n    class Meta:\n        db_table = 'users'\n        verbose_name = 'User'\n        verbose_name_plural = 'Users'\n\n    def __str__(self):\n        return self.email\n\n# settings/base.py\nAUTH_USER_MODEL = 'users.User'\n```\n\n### Password Hashing\n\n```python\n# Django uses PBKDF2 by default. For stronger security:\nPASSWORD_HASHERS = [\n    'django.contrib.auth.hashers.Argon2PasswordHasher',\n    'django.contrib.auth.hashers.PBKDF2PasswordHasher',\n    'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',\n    'django.contrib.auth.hashers.BCryptSHA256PasswordHasher',\n]\n```\n\n### Session Management\n\n```python\n# Session configuration\nSESSION_ENGINE = 'django.contrib.sessions.backends.cache'  # Or 'db'\nSESSION_CACHE_ALIAS = 'default'\nSESSION_COOKIE_AGE = 3600 * 24 * 7  # 1 week\nSESSION_SAVE_EVERY_REQUEST = False\nSESSION_EXPIRE_AT_BROWSER_CLOSE = False  # Better UX, but less secure\n```\n\n## Authorization\n\n### Permissions\n\n```python\n# models.py\nfrom django.db import models\nfrom django.contrib.auth.models import Permission\n\nclass Post(models.Model):\n    title = models.CharField(max_length=200)\n    content = models.TextField()\n    author = models.ForeignKey(User, on_delete=models.CASCADE)\n\n    class Meta:\n        permissions = [\n            ('can_publish', 'Can publish posts'),\n            ('can_edit_others', 'Can edit posts of others'),\n        ]\n\n    def user_can_edit(self, user):\n        \"\"\"Check if user can edit this post.\"\"\"\n        return self.author == user or user.has_perm('app.can_edit_others')\n\n# views.py\nfrom django.contrib.auth.mixins import LoginRequiredMixin, PermissionRequiredMixin\nfrom django.views.generic import UpdateView\n\nclass PostUpdateView(LoginRequiredMixin, PermissionRequiredMixin, UpdateView):\n    model = Post\n    permission_required = 'app.can_edit_others'\n    raise_exception = True  # Return 403 instead of redirect\n\n    def get_queryset(self):\n        \"\"\"Only allow users to edit their own posts.\"\"\"\n        return Post.objects.filter(author=self.request.user)\n```\n\n### Custom Permissions\n\n```python\n# permissions.py\nfrom rest_framework import permissions\n\nclass IsOwnerOrReadOnly(permissions.BasePermission):\n    \"\"\"Allow only owners to edit objects.\"\"\"\n\n    def has_object_permission(self, request, view, obj):\n        # Read permissions allowed for any request\n        if request.method in permissions.SAFE_METHODS:\n            return True\n\n        # Write permissions only for owner\n        return obj.author == request.user\n\nclass IsAdminOrReadOnly(permissions.BasePermission):\n    \"\"\"Allow admins to do anything, others read-only.\"\"\"\n\n    def has_permission(self, request, view):\n        if request.method in permissions.SAFE_METHODS:\n            return True\n        return request.user and request.user.is_staff\n\nclass IsVerifiedUser(permissions.BasePermission):\n    \"\"\"Allow only verified users.\"\"\"\n\n    def has_permission(self, request, view):\n        return request.user and request.user.is_authenticated and request.user.is_verified\n```\n\n### Role-Based Access Control (RBAC)\n\n```python\n# models.py\nfrom django.contrib.auth.models import AbstractUser, Group\n\nclass User(AbstractUser):\n    ROLE_CHOICES = [\n        ('admin', 'Administrator'),\n        ('moderator', 'Moderator'),\n        ('user', 'Regular User'),\n    ]\n    role = models.CharField(max_length=20, choices=ROLE_CHOICES, default='user')\n\n    def is_admin(self):\n        return self.role == 'admin' or self.is_superuser\n\n    def is_moderator(self):\n        return self.role in ['admin', 'moderator']\n\n# Mixins\nclass AdminRequiredMixin:\n    \"\"\"Mixin to require admin role.\"\"\"\n\n    def dispatch(self, request, *args, **kwargs):\n        if not request.user.is_authenticated or not request.user.is_admin():\n            from django.core.exceptions import PermissionDenied\n            raise PermissionDenied\n        return super().dispatch(request, *args, **kwargs)\n```\n\n## SQL Injection Prevention\n\n### Django ORM Protection\n\n```python\n# GOOD: Django ORM automatically escapes parameters\ndef get_user(username):\n    return User.objects.get(username=username)  # Safe\n\n# GOOD: Using parameters with raw()\ndef search_users(query):\n    return User.objects.raw('SELECT * FROM users WHERE username = %s', [query])\n\n# BAD: Never directly interpolate user input\ndef get_user_bad(username):\n    return User.objects.raw(f'SELECT * FROM users WHERE username = {username}')  # VULNERABLE!\n\n# GOOD: Using filter with proper escaping\ndef get_users_by_email(email):\n    return User.objects.filter(email__iexact=email)  # Safe\n\n# GOOD: Using Q objects for complex queries\nfrom django.db.models import Q\ndef search_users_complex(query):\n    return User.objects.filter(\n        Q(username__icontains=query) |\n        Q(email__icontains=query)\n    )  # Safe\n```\n\n### Extra Security with raw()\n\n```python\n# If you must use raw SQL, always use parameters\nUser.objects.raw(\n    'SELECT * FROM users WHERE email = %s AND status = %s',\n    [user_input_email, status]\n)\n```\n\n## XSS Prevention\n\n### Template Escaping\n\n```django\n{# Django auto-escapes variables by default - SAFE #}\n{{ user_input }}  {# Escaped HTML #}\n\n{# Explicitly mark safe only for trusted content #}\n{{ trusted_html|safe }}  {# Not escaped #}\n\n{# Use template filters for safe HTML #}\n{{ user_input|escape }}  {# Same as default #}\n{{ user_input|striptags }}  {# Remove all HTML tags #}\n\n{# JavaScript escaping #}\n<script>\n    var username = {{ username|escapejs }};\n</script>\n```\n\n### Safe String Handling\n\n```python\nfrom django.utils.safestring import mark_safe\nfrom django.utils.html import escape\n\n# BAD: Never mark user input as safe without escaping\ndef render_bad(user_input):\n    return mark_safe(user_input)  # VULNERABLE!\n\n# GOOD: Escape first, then mark safe\ndef render_good(user_input):\n    return mark_safe(escape(user_input))\n\n# GOOD: Use format_html for HTML with variables\nfrom django.utils.html import format_html\n\ndef greet_user(username):\n    return format_html('<span class=\"user\">{}</span>', escape(username))\n```\n\n### HTTP Headers\n\n```python\n# settings.py\nSECURE_CONTENT_TYPE_NOSNIFF = True  # Prevent MIME sniffing\nSECURE_BROWSER_XSS_FILTER = True  # Enable XSS filter\nX_FRAME_OPTIONS = 'DENY'  # Prevent clickjacking\n\n# Custom middleware\nfrom django.conf import settings\n\nclass SecurityHeaderMiddleware:\n    def __init__(self, get_response):\n        self.get_response = get_response\n\n    def __call__(self, request):\n        response = self.get_response(request)\n        response['X-Content-Type-Options'] = 'nosniff'\n        response['X-Frame-Options'] = 'DENY'\n        response['X-XSS-Protection'] = '1; mode=block'\n        response['Content-Security-Policy'] = \"default-src 'self'\"\n        return response\n```\n\n## CSRF Protection\n\n### Default CSRF Protection\n\n```python\n# settings.py - CSRF is enabled by default\nCSRF_COOKIE_SECURE = True  # Only send over HTTPS\nCSRF_COOKIE_HTTPONLY = True  # Prevent JavaScript access\nCSRF_COOKIE_SAMESITE = 'Lax'  # Prevent CSRF in some cases\nCSRF_TRUSTED_ORIGINS = ['https://example.com']  # Trusted domains\n\n# Template usage\n<form method=\"post\">\n    {% csrf_token %}\n    {{ form.as_p }}\n    <button type=\"submit\">Submit</button>\n</form>\n\n# AJAX requests\nfunction getCookie(name) {\n    let cookieValue = null;\n    if (document.cookie && document.cookie !== '') {\n        const cookies = document.cookie.split(';');\n        for (let i = 0; i < cookies.length; i++) {\n            const cookie = cookies[i].trim();\n            if (cookie.substring(0, name.length + 1) === (name + '=')) {\n                cookieValue = decodeURIComponent(cookie.substring(name.length + 1));\n                break;\n            }\n        }\n    }\n    return cookieValue;\n}\n\nfetch('/api/endpoint/', {\n    method: 'POST',\n    headers: {\n        'X-CSRFToken': getCookie('csrftoken'),\n        'Content-Type': 'application/json',\n    },\n    body: JSON.stringify(data)\n});\n```\n\n### Exempting Views (Use Carefully)\n\n```python\nfrom django.views.decorators.csrf import csrf_exempt\n\n@csrf_exempt  # Only use when absolutely necessary!\ndef webhook_view(request):\n    # Webhook from external service\n    pass\n```\n\n## File Upload Security\n\n### File Validation\n\n```python\nimport os\nimport magic  # pip install python-magic\nfrom django.core.exceptions import ValidationError\n\nALLOWED_MIMES = {\n    'image/jpeg', 'image/png', 'image/gif', 'application/pdf',\n}\n\nMIME_TO_EXTENSIONS = {\n    'image/jpeg': {'.jpg', '.jpeg'},\n    'image/png': {'.png'},\n    'image/gif': {'.gif'},\n    'application/pdf': {'.pdf'},\n}\n\ndef validate_file_type(value):\n    \"\"\"Validate file type using magic bytes and cross-check extension.\"\"\"\n    mime = magic.from_buffer(value.read(2048), mime=True)\n    value.seek(0)\n\n    if mime not in ALLOWED_MIMES:\n        raise ValidationError('Unsupported file type.')\n\n    ext = os.path.splitext(value.name)[1].lower()\n    if ext not in MIME_TO_EXTENSIONS.get(mime, set()):\n        raise ValidationError('File extension does not match file content.')\n\ndef validate_file_size(value):\n    \"\"\"Validate file size (max 5MB).\"\"\"\n    if value.size > 5 * 1024 * 1024:\n        raise ValidationError('File too large. Max size is 5MB.')\n\n# models.py\nclass Document(models.Model):\n    file = models.FileField(\n        upload_to='documents/',\n        validators=[validate_file_type, validate_file_size]\n    )\n\n```\n\nFor environments where installing libmagic is difficult (e.g., minimal containers),\nuse the pure-Python `filetype` package as an alternative:\n\n```python\nimport os\nfrom django.core.exceptions import ValidationError\n\nimport filetype  # pip install filetype\n\nALLOWED_MIMES = {\n    'image/jpeg', 'image/png', 'image/gif', 'application/pdf',\n}\n\nMIME_TO_EXTENSIONS = {\n    'image/jpeg': {'.jpg', '.jpeg'},\n    'image/png': {'.png'},\n    'image/gif': {'.gif'},\n    'application/pdf': {'.pdf'},\n}\n\ndef validate_file_type(value):\n    \"\"\"Validate file type using magic bytes.\"\"\"\n    kind = filetype.guess(value.read(2048))\n    value.seek(0)\n\n    if kind is None or kind.mime not in ALLOWED_MIMES:\n        raise ValidationError('Unsupported file type.')\n\n    ext = os.path.splitext(value.name)[1].lower()\n    if ext not in MIME_TO_EXTENSIONS.get(kind.mime, set()):\n        raise ValidationError('File extension does not match file content.')\n```\n\n### Secure File Storage\n\n```python\n# settings.py\nMEDIA_ROOT = '/var/www/media/'\nMEDIA_URL = '/media/'\n\n# Use a separate domain for media in production\nMEDIA_DOMAIN = 'https://media.example.com'\n\n# Don't serve user uploads directly\n# Use whitenoise or a CDN for static files\n# Use a separate server or S3 for media files\n```\n\n## API Security\n\n### Rate Limiting\n\n```python\n# settings.py\nREST_FRAMEWORK = {\n    'DEFAULT_THROTTLE_CLASSES': [\n        'rest_framework.throttling.AnonRateThrottle',\n        'rest_framework.throttling.UserRateThrottle'\n    ],\n    'DEFAULT_THROTTLE_RATES': {\n        'anon': '100/day',\n        'user': '1000/day',\n        'upload': '10/hour',\n    }\n}\n\n# Custom throttle\nfrom rest_framework.throttling import UserRateThrottle\n\nclass BurstRateThrottle(UserRateThrottle):\n    scope = 'burst'\n    rate = '60/min'\n\nclass SustainedRateThrottle(UserRateThrottle):\n    scope = 'sustained'\n    rate = '1000/day'\n```\n\n### Authentication for APIs\n\n```python\n# settings.py\nREST_FRAMEWORK = {\n    'DEFAULT_AUTHENTICATION_CLASSES': [\n        'rest_framework.authentication.TokenAuthentication',\n        'rest_framework.authentication.SessionAuthentication',\n        'rest_framework_simplejwt.authentication.JWTAuthentication',\n    ],\n    'DEFAULT_PERMISSION_CLASSES': [\n        'rest_framework.permissions.IsAuthenticated',\n    ],\n}\n\n# views.py\nfrom rest_framework.decorators import api_view, permission_classes\nfrom rest_framework.permissions import IsAuthenticated\n\n@api_view(['GET', 'POST'])\n@permission_classes([IsAuthenticated])\ndef protected_view(request):\n    return Response({'message': 'You are authenticated'})\n```\n\n## Security Headers\n\n### Content Security Policy\n\n```python\n# settings.py\nCSP_DEFAULT_SRC = \"'self'\"\nCSP_SCRIPT_SRC = \"'self' https://cdn.example.com\"\nCSP_STYLE_SRC = \"'self' 'unsafe-inline'\"\nCSP_IMG_SRC = \"'self' data: https:\"\nCSP_CONNECT_SRC = \"'self' https://api.example.com\"\n\n# Middleware\nclass CSPMiddleware:\n    def __init__(self, get_response):\n        self.get_response = get_response\n\n    def __call__(self, request):\n        response = self.get_response(request)\n        response['Content-Security-Policy'] = (\n            f\"default-src {CSP_DEFAULT_SRC}; \"\n            f\"script-src {CSP_SCRIPT_SRC}; \"\n            f\"style-src {CSP_STYLE_SRC}; \"\n            f\"img-src {CSP_IMG_SRC}; \"\n            f\"connect-src {CSP_CONNECT_SRC}\"\n        )\n        return response\n```\n\n## Environment Variables\n\n### Managing Secrets\n\n```python\n# Use python-decouple or django-environ\nimport environ\n\nenv = environ.Env(\n    # set casting, default value\n    DEBUG=(bool, False)\n)\n\n# reading .env file\nenviron.Env.read_env()\n\nSECRET_KEY = env('DJANGO_SECRET_KEY')\nDATABASE_URL = env('DATABASE_URL')\nALLOWED_HOSTS = env.list('ALLOWED_HOSTS')\n\n# .env file (never commit this)\nDEBUG=False\nSECRET_KEY=your-secret-key-here\nDATABASE_URL=postgresql://user:password@localhost:5432/dbname\nALLOWED_HOSTS=example.com,www.example.com\n```\n\n## Logging Security Events\n\n```python\n# settings.py\nLOGGING = {\n    'version': 1,\n    'disable_existing_loggers': False,\n    'handlers': {\n        'file': {\n            'level': 'WARNING',\n            'class': 'logging.FileHandler',\n            'filename': '/var/log/django/security.log',\n        },\n        'console': {\n            'level': 'INFO',\n            'class': 'logging.StreamHandler',\n        },\n    },\n    'loggers': {\n        'django.security': {\n            'handlers': ['file', 'console'],\n            'level': 'WARNING',\n            'propagate': True,\n        },\n        'django.request': {\n            'handlers': ['file'],\n            'level': 'ERROR',\n            'propagate': False,\n        },\n    },\n}\n```\n\n## Quick Security Checklist\n\n| Check | Description |\n|-------|-------------|\n| `DEBUG = False` | Never run with DEBUG in production |\n| HTTPS only | Force SSL, secure cookies |\n| Strong secrets | Use environment variables for SECRET_KEY |\n| Password validation | Enable all password validators |\n| CSRF protection | Enabled by default, don't disable |\n| XSS prevention | Django auto-escapes, don't use `&#124;safe` with user input |\n| SQL injection | Use ORM, never concatenate strings in queries |\n| File uploads | Validate file type and size |\n| Rate limiting | Throttle API endpoints |\n| Security headers | CSP, X-Frame-Options, HSTS |\n| Logging | Log security events |\n| Updates | Keep Django and dependencies updated |\n\nRemember: Security is a process, not a product. Regularly review and update your security practices.\n"
+    },
+    {
+      "name": "django-tdd",
+      "description": "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.",
+      "category": "testing",
+      "body": "# Django Testing with TDD\n\nTest-driven development for Django applications using pytest, factory_boy, and Django REST Framework.\n\n## When to Activate\n\n- Writing new Django applications\n- Implementing Django REST Framework APIs\n- Testing Django models, views, and serializers\n- Setting up testing infrastructure for Django projects\n\n## TDD Workflow for Django\n\n### Red-Green-Refactor Cycle\n\n```python\n# Step 1: RED - Write failing test\ndef test_user_creation():\n    user = User.objects.create_user(email='test@example.com', password='testpass123')\n    assert user.email == 'test@example.com'\n    assert user.check_password('testpass123')\n    assert not user.is_staff\n\n# Step 2: GREEN - Make test pass\n# Create User model or factory\n\n# Step 3: REFACTOR - Improve while keeping tests green\n```\n\n## Setup\n\n### pytest Configuration\n\n```ini\n# pytest.ini\n[pytest]\nDJANGO_SETTINGS_MODULE = config.settings.test\ntestpaths = tests\npython_files = test_*.py\npython_classes = Test*\npython_functions = test_*\naddopts =\n    --reuse-db\n    --nomigrations\n    --cov=apps\n    --cov-report=html\n    --cov-report=term-missing\n    --strict-markers\nmarkers =\n    slow: marks tests as slow\n    integration: marks tests as integration tests\n```\n\n### Test Settings\n\n```python\n# config/settings/test.py\nfrom .base import *\n\nDEBUG = True\nDATABASES = {\n    'default': {\n        'ENGINE': 'django.db.backends.sqlite3',\n        'NAME': ':memory:',\n    }\n}\n\n# Disable migrations for speed\nclass DisableMigrations:\n    def __contains__(self, item):\n        return True\n\n    def __getitem__(self, item):\n        return None\n\nMIGRATION_MODULES = DisableMigrations()\n\n# Faster password hashing\nPASSWORD_HASHERS = [\n    'django.contrib.auth.hashers.MD5PasswordHasher',\n]\n\n# Email backend\nEMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'\n\n# Celery always eager\nCELERY_TASK_ALWAYS_EAGER = True\nCELERY_TASK_EAGER_PROPAGATES = True\n```\n\n### conftest.py\n\n```python\n# tests/conftest.py\nimport pytest\nfrom django.utils import timezone\nfrom django.contrib.auth import get_user_model\n\nUser = get_user_model()\n\n@pytest.fixture(autouse=True)\ndef timezone_settings(settings):\n    \"\"\"Ensure consistent timezone.\"\"\"\n    settings.TIME_ZONE = 'UTC'\n\n@pytest.fixture\ndef user(db):\n    \"\"\"Create a test user.\"\"\"\n    return User.objects.create_user(\n        email='test@example.com',\n        password='testpass123',\n        username='testuser'\n    )\n\n@pytest.fixture\ndef admin_user(db):\n    \"\"\"Create an admin user.\"\"\"\n    return User.objects.create_superuser(\n        email='admin@example.com',\n        password='adminpass123',\n        username='admin'\n    )\n\n@pytest.fixture\ndef authenticated_client(client, user):\n    \"\"\"Return authenticated client.\"\"\"\n    client.force_login(user)\n    return client\n\n@pytest.fixture\ndef api_client():\n    \"\"\"Return DRF API client.\"\"\"\n    from rest_framework.test import APIClient\n    return APIClient()\n\n@pytest.fixture\ndef authenticated_api_client(api_client, user):\n    \"\"\"Return authenticated API client.\"\"\"\n    api_client.force_authenticate(user=user)\n    return api_client\n```\n\n## Factory Boy\n\n### Factory Setup\n\n```python\n# tests/factories.py\nimport factory\nfrom factory import fuzzy\nfrom datetime import datetime, timedelta\nfrom django.contrib.auth import get_user_model\nfrom apps.products.models import Product, Category\n\nUser = get_user_model()\n\nclass UserFactory(factory.django.DjangoModelFactory):\n    \"\"\"Factory for User model.\"\"\"\n\n    class Meta:\n        model = User\n\n    email = factory.Sequence(lambda n: f\"user{n}@example.com\")\n    username = factory.Sequence(lambda n: f\"user{n}\")\n    password = factory.PostGenerationMethodCall('set_password', 'testpass123')\n    first_name = factory.Faker('first_name')\n    last_name = factory.Faker('last_name')\n    is_active = True\n\nclass CategoryFactory(factory.django.DjangoModelFactory):\n    \"\"\"Factory for Category model.\"\"\"\n\n    class Meta:\n        model = Category\n\n    name = factory.Faker('word')\n    slug = factory.LazyAttribute(lambda obj: obj.name.lower())\n    description = factory.Faker('text')\n\nclass ProductFactory(factory.django.DjangoModelFactory):\n    \"\"\"Factory for Product model.\"\"\"\n\n    class Meta:\n        model = Product\n\n    name = factory.Faker('sentence', nb_words=3)\n    slug = factory.LazyAttribute(lambda obj: obj.name.lower().replace(' ', '-'))\n    description = factory.Faker('text')\n    price = fuzzy.FuzzyDecimal(10.00, 1000.00, 2)\n    stock = fuzzy.FuzzyInteger(0, 100)\n    is_active = True\n    category = factory.SubFactory(CategoryFactory)\n    created_by = factory.SubFactory(UserFactory)\n\n    @factory.post_generation\n    def tags(self, create, extracted, **kwargs):\n        \"\"\"Add tags to product.\"\"\"\n        if not create:\n            return\n        if extracted:\n            for tag in extracted:\n                self.tags.add(tag)\n```\n\n### Using Factories\n\n```python\n# tests/test_models.py\nimport pytest\nfrom tests.factories import ProductFactory, UserFactory\n\ndef test_product_creation():\n    \"\"\"Test product creation using factory.\"\"\"\n    product = ProductFactory(price=100.00, stock=50)\n    assert product.price == 100.00\n    assert product.stock == 50\n    assert product.is_active is True\n\ndef test_product_with_tags():\n    \"\"\"Test product with tags.\"\"\"\n    tags = [TagFactory(name='electronics'), TagFactory(name='new')]\n    product = ProductFactory(tags=tags)\n    assert product.tags.count() == 2\n\ndef test_multiple_products():\n    \"\"\"Test creating multiple products.\"\"\"\n    products = ProductFactory.create_batch(10)\n    assert len(products) == 10\n```\n\n## Model Testing\n\n### Model Tests\n\n```python\n# tests/test_models.py\nimport pytest\nfrom django.core.exceptions import ValidationError\nfrom tests.factories import UserFactory, ProductFactory\n\nclass TestUserModel:\n    \"\"\"Test User model.\"\"\"\n\n    def test_create_user(self, db):\n        \"\"\"Test creating a regular user.\"\"\"\n        user = UserFactory(email='test@example.com')\n        assert user.email == 'test@example.com'\n        assert user.check_password('testpass123')\n        assert not user.is_staff\n        assert not user.is_superuser\n\n    def test_create_superuser(self, db):\n        \"\"\"Test creating a superuser.\"\"\"\n        user = UserFactory(\n            email='admin@example.com',\n            is_staff=True,\n            is_superuser=True\n        )\n        assert user.is_staff\n        assert user.is_superuser\n\n    def test_user_str(self, db):\n        \"\"\"Test user string representation.\"\"\"\n        user = UserFactory(email='test@example.com')\n        assert str(user) == 'test@example.com'\n\nclass TestProductModel:\n    \"\"\"Test Product model.\"\"\"\n\n    def test_product_creation(self, db):\n        \"\"\"Test creating a product.\"\"\"\n        product = ProductFactory()\n        assert product.id is not None\n        assert product.is_active is True\n        assert product.created_at is not None\n\n    def test_product_slug_generation(self, db):\n        \"\"\"Test automatic slug generation.\"\"\"\n        product = ProductFactory(name='Test Product')\n        assert product.slug == 'test-product'\n\n    def test_product_price_validation(self, db):\n        \"\"\"Test price cannot be negative.\"\"\"\n        product = ProductFactory(price=-10)\n        with pytest.raises(ValidationError):\n            product.full_clean()\n\n    def test_product_manager_active(self, db):\n        \"\"\"Test active manager method.\"\"\"\n        ProductFactory.create_batch(5, is_active=True)\n        ProductFactory.create_batch(3, is_active=False)\n\n        active_count = Product.objects.active().count()\n        assert active_count == 5\n\n    def test_product_stock_management(self, db):\n        \"\"\"Test stock management.\"\"\"\n        product = ProductFactory(stock=10)\n        product.reduce_stock(5)\n        product.refresh_from_db()\n        assert product.stock == 5\n\n        with pytest.raises(ValueError):\n            product.reduce_stock(10)  # Not enough stock\n```\n\n## View Testing\n\n### Django View Testing\n\n```python\n# tests/test_views.py\nimport pytest\nfrom django.urls import reverse\nfrom tests.factories import ProductFactory, UserFactory\n\nclass TestProductViews:\n    \"\"\"Test product views.\"\"\"\n\n    def test_product_list(self, client, db):\n        \"\"\"Test product list view.\"\"\"\n        ProductFactory.create_batch(10)\n\n        response = client.get(reverse('products:list'))\n\n        assert response.status_code == 200\n        assert len(response.context['products']) == 10\n\n    def test_product_detail(self, client, db):\n        \"\"\"Test product detail view.\"\"\"\n        product = ProductFactory()\n\n        response = client.get(reverse('products:detail', kwargs={'slug': product.slug}))\n\n        assert response.status_code == 200\n        assert response.context['product'] == product\n\n    def test_product_create_requires_login(self, client, db):\n        \"\"\"Test product creation requires authentication.\"\"\"\n        response = client.get(reverse('products:create'))\n\n        assert response.status_code == 302\n        assert response.url.startswith('/accounts/login/')\n\n    def test_product_create_authenticated(self, authenticated_client, db):\n        \"\"\"Test product creation as authenticated user.\"\"\"\n        response = authenticated_client.get(reverse('products:create'))\n\n        assert response.status_code == 200\n\n    def test_product_create_post(self, authenticated_client, db, category):\n        \"\"\"Test creating a product via POST.\"\"\"\n        data = {\n            'name': 'Test Product',\n            'description': 'A test product',\n            'price': '99.99',\n            'stock': 10,\n            'category': category.id,\n        }\n\n        response = authenticated_client.post(reverse('products:create'), data)\n\n        assert response.status_code == 302\n        assert Product.objects.filter(name='Test Product').exists()\n```\n\n## DRF API Testing\n\n### Serializer Testing\n\n```python\n# tests/test_serializers.py\nimport pytest\nfrom rest_framework.exceptions import ValidationError\nfrom apps.products.serializers import ProductSerializer\nfrom tests.factories import ProductFactory\n\nclass TestProductSerializer:\n    \"\"\"Test ProductSerializer.\"\"\"\n\n    def test_serialize_product(self, db):\n        \"\"\"Test serializing a product.\"\"\"\n        product = ProductFactory()\n        serializer = ProductSerializer(product)\n\n        data = serializer.data\n\n        assert data['id'] == product.id\n        assert data['name'] == product.name\n        assert data['price'] == str(product.price)\n\n    def test_deserialize_product(self, db):\n        \"\"\"Test deserializing product data.\"\"\"\n        data = {\n            'name': 'Test Product',\n            'description': 'Test description',\n            'price': '99.99',\n            'stock': 10,\n            'category': 1,\n        }\n\n        serializer = ProductSerializer(data=data)\n\n        assert serializer.is_valid()\n        product = serializer.save()\n\n        assert product.name == 'Test Product'\n        assert float(product.price) == 99.99\n\n    def test_price_validation(self, db):\n        \"\"\"Test price validation.\"\"\"\n        data = {\n            'name': 'Test Product',\n            'price': '-10.00',\n            'stock': 10,\n        }\n\n        serializer = ProductSerializer(data=data)\n\n        assert not serializer.is_valid()\n        assert 'price' in serializer.errors\n\n    def test_stock_validation(self, db):\n        \"\"\"Test stock cannot be negative.\"\"\"\n        data = {\n            'name': 'Test Product',\n            'price': '99.99',\n            'stock': -5,\n        }\n\n        serializer = ProductSerializer(data=data)\n\n        assert not serializer.is_valid()\n        assert 'stock' in serializer.errors\n```\n\n### API ViewSet Testing\n\n```python\n# tests/test_api.py\nimport pytest\nfrom rest_framework.test import APIClient\nfrom rest_framework import status\nfrom django.urls import reverse\nfrom tests.factories import ProductFactory, UserFactory\n\nclass TestProductAPI:\n    \"\"\"Test Product API endpoints.\"\"\"\n\n    @pytest.fixture\n    def api_client(self):\n        \"\"\"Return API client.\"\"\"\n        return APIClient()\n\n    def test_list_products(self, api_client, db):\n        \"\"\"Test listing products.\"\"\"\n        ProductFactory.create_batch(10)\n\n        url = reverse('api:product-list')\n        response = api_client.get(url)\n\n        assert response.status_code == status.HTTP_200_OK\n        assert response.data['count'] == 10\n\n    def test_retrieve_product(self, api_client, db):\n        \"\"\"Test retrieving a product.\"\"\"\n        product = ProductFactory()\n\n        url = reverse('api:product-detail', kwargs={'pk': product.id})\n        response = api_client.get(url)\n\n        assert response.status_code == status.HTTP_200_OK\n        assert response.data['id'] == product.id\n\n    def test_create_product_unauthorized(self, api_client, db):\n        \"\"\"Test creating product without authentication.\"\"\"\n        url = reverse('api:product-list')\n        data = {'name': 'Test Product', 'price': '99.99'}\n\n        response = api_client.post(url, data)\n\n        assert response.status_code == status.HTTP_401_UNAUTHORIZED\n\n    def test_create_product_authorized(self, authenticated_api_client, db):\n        \"\"\"Test creating product as authenticated user.\"\"\"\n        url = reverse('api:product-list')\n        data = {\n            'name': 'Test Product',\n            'description': 'Test',\n            'price': '99.99',\n            'stock': 10,\n        }\n\n        response = authenticated_api_client.post(url, data)\n\n        assert response.status_code == status.HTTP_201_CREATED\n        assert response.data['name'] == 'Test Product'\n\n    def test_update_product(self, authenticated_api_client, db):\n        \"\"\"Test updating a product.\"\"\"\n        product = ProductFactory(created_by=authenticated_api_client.user)\n\n        url = reverse('api:product-detail', kwargs={'pk': product.id})\n        data = {'name': 'Updated Product'}\n\n        response = authenticated_api_client.patch(url, data)\n\n        assert response.status_code == status.HTTP_200_OK\n        assert response.data['name'] == 'Updated Product'\n\n    def test_delete_product(self, authenticated_api_client, db):\n        \"\"\"Test deleting a product.\"\"\"\n        product = ProductFactory(created_by=authenticated_api_client.user)\n\n        url = reverse('api:product-detail', kwargs={'pk': product.id})\n        response = authenticated_api_client.delete(url)\n\n        assert response.status_code == status.HTTP_204_NO_CONTENT\n\n    def test_filter_products_by_price(self, api_client, db):\n        \"\"\"Test filtering products by price.\"\"\"\n        ProductFactory(price=50)\n        ProductFactory(price=150)\n\n        url = reverse('api:product-list')\n        response = api_client.get(url, {'price_min': 100})\n\n        assert response.status_code == status.HTTP_200_OK\n        assert response.data['count'] == 1\n\n    def test_search_products(self, api_client, db):\n        \"\"\"Test searching products.\"\"\"\n        ProductFactory(name='Apple iPhone')\n        ProductFactory(name='Samsung Galaxy')\n\n        url = reverse('api:product-list')\n        response = api_client.get(url, {'search': 'Apple'})\n\n        assert response.status_code == status.HTTP_200_OK\n        assert response.data['count'] == 1\n```\n\n## Mocking and Patching\n\n### Mocking External Services\n\n```python\n# tests/test_views.py\nfrom unittest.mock import patch, Mock\nimport pytest\n\nclass TestPaymentView:\n    \"\"\"Test payment view with mocked payment gateway.\"\"\"\n\n    @patch('apps.payments.services.stripe')\n    def test_successful_payment(self, mock_stripe, client, user, product):\n        \"\"\"Test successful payment with mocked Stripe.\"\"\"\n        # Configure mock\n        mock_stripe.Charge.create.return_value = {\n            'id': 'ch_123',\n            'status': 'succeeded',\n            'amount': 9999,\n        }\n\n        client.force_login(user)\n        response = client.post(reverse('payments:process'), {\n            'product_id': product.id,\n            'token': 'tok_visa',\n        })\n\n        assert response.status_code == 302\n        mock_stripe.Charge.create.assert_called_once()\n\n    @patch('apps.payments.services.stripe')\n    def test_failed_payment(self, mock_stripe, client, user, product):\n        \"\"\"Test failed payment.\"\"\"\n        mock_stripe.Charge.create.side_effect = Exception('Card declined')\n\n        client.force_login(user)\n        response = client.post(reverse('payments:process'), {\n            'product_id': product.id,\n            'token': 'tok_visa',\n        })\n\n        assert response.status_code == 302\n        assert 'error' in response.url\n```\n\n### Mocking Email Sending\n\n```python\n# tests/test_email.py\nfrom django.core import mail\nfrom django.test import override_settings\n\n@override_settings(EMAIL_BACKEND='django.core.mail.backends.locmem.EmailBackend')\ndef test_order_confirmation_email(db, order):\n    \"\"\"Test order confirmation email.\"\"\"\n    order.send_confirmation_email()\n\n    assert len(mail.outbox) == 1\n    assert order.user.email in mail.outbox[0].to\n    assert 'Order Confirmation' in mail.outbox[0].subject\n```\n\n## Integration Testing\n\n### Full Flow Testing\n\n```python\n# tests/test_integration.py\nimport pytest\nfrom django.urls import reverse\nfrom tests.factories import UserFactory, ProductFactory\n\nclass TestCheckoutFlow:\n    \"\"\"Test complete checkout flow.\"\"\"\n\n    def test_guest_to_purchase_flow(self, client, db):\n        \"\"\"Test complete flow from guest to purchase.\"\"\"\n        # Step 1: Register\n        response = client.post(reverse('users:register'), {\n            'email': 'test@example.com',\n            'password': 'testpass123',\n            'password_confirm': 'testpass123',\n        })\n        assert response.status_code == 302\n\n        # Step 2: Login\n        response = client.post(reverse('users:login'), {\n            'email': 'test@example.com',\n            'password': 'testpass123',\n        })\n        assert response.status_code == 302\n\n        # Step 3: Browse products\n        product = ProductFactory(price=100)\n        response = client.get(reverse('products:detail', kwargs={'slug': product.slug}))\n        assert response.status_code == 200\n\n        # Step 4: Add to cart\n        response = client.post(reverse('cart:add'), {\n            'product_id': product.id,\n            'quantity': 1,\n        })\n        assert response.status_code == 302\n\n        # Step 5: Checkout\n        response = client.get(reverse('checkout:review'))\n        assert response.status_code == 200\n        assert product.name in response.content.decode()\n\n        # Step 6: Complete purchase\n        with patch('apps.checkout.services.process_payment') as mock_payment:\n            mock_payment.return_value = True\n            response = client.post(reverse('checkout:complete'))\n\n        assert response.status_code == 302\n        assert Order.objects.filter(user__email='test@example.com').exists()\n```\n\n## Testing Best Practices\n\n### DO\n\n- **Use factories**: Instead of manual object creation\n- **One assertion per test**: Keep tests focused\n- **Descriptive test names**: `test_user_cannot_delete_others_post`\n- **Test edge cases**: Empty inputs, None values, boundary conditions\n- **Mock external services**: Don't depend on external APIs\n- **Use fixtures**: Eliminate duplication\n- **Test permissions**: Ensure authorization works\n- **Keep tests fast**: Use `--reuse-db` and `--nomigrations`\n\n### DON'T\n\n- **Don't test Django internals**: Trust Django to work\n- **Don't test third-party code**: Trust libraries to work\n- **Don't ignore failing tests**: All tests must pass\n- **Don't make tests dependent**: Tests should run in any order\n- **Don't over-mock**: Mock only external dependencies\n- **Don't test private methods**: Test public interface\n- **Don't use production database**: Always use test database\n\n## Coverage\n\n### Coverage Configuration\n\n```bash\n# Run tests with coverage\npytest --cov=apps --cov-report=html --cov-report=term-missing\n\n# Generate HTML report\nopen htmlcov/index.html\n```\n\n### Coverage Goals\n\n| Component | Target Coverage |\n|-----------|-----------------|\n| Models | 90%+ |\n| Serializers | 85%+ |\n| Views | 80%+ |\n| Services | 90%+ |\n| Utilities | 80%+ |\n| Overall | 80%+ |\n\n## Quick Reference\n\n| Pattern | Usage |\n|---------|-------|\n| `@pytest.mark.django_db` | Enable database access |\n| `client` | Django test client |\n| `api_client` | DRF API client |\n| `factory.create_batch(n)` | Create multiple objects |\n| `patch('module.function')` | Mock external dependencies |\n| `override_settings` | Temporarily change settings |\n| `force_authenticate()` | Bypass authentication in tests |\n| `assertRedirects` | Check for redirects |\n| `assertTemplateUsed` | Verify template usage |\n| `mail.outbox` | Check sent emails |\n\nRemember: Tests are documentation. Good tests explain how your code should work. Keep them simple, readable, and maintainable.\n"
+    }
+  ],
   "agents": [
     {
       "name": "python-reviewer",
-      "description": "Reviews changed Python against the Python standards: type hints, immutability, specific exceptions, boundary validation, and env-var secrets. Reports file:line + severity. Use after any Python change.",
-      "tools": ["Read", "Grep", "Glob", "Bash"],
+      "description": "Expert Python code reviewer for PEP 8, Pythonic idioms, type hints, security (injection, unsafe deserialization, weak crypto), error handling, concurrency, and code quality. Reports file:line + severity. Use for all Python code changes.",
+      "tools": [
+        "Read",
+        "Grep",
+        "Glob",
+        "Bash"
+      ],
       "model": "sonnet",
-      "prompt": "You are a Python reviewer. Read the changed Python files and check them against the conventions in context: frozen dataclasses/NamedTuples for value objects, Protocols for structural typing, context managers for resources, full signature annotations, specific-exception handling with `raise ... from`, boundary input validation, and `os.environ[...]` secrets that fail fast. PEP 8, import order, and coverage are the linter/CI's job — don't re-litigate them. Cite the exact file:line for each finding, name the concrete failure mode, and give severity. If the change is sound, say so plainly rather than inventing findings."
+      "prompt": "You are a senior Python code reviewer ensuring high standards of Pythonic code and best practices.\n\nWhen invoked:\n1. Run `git diff -- '*.py'` to see recent Python file changes\n2. Run static analysis tools if available (ruff, mypy, pylint, black --check)\n3. Focus on modified `.py` files\n4. Begin review immediately\n\n## Review Priorities\n\n### CRITICAL — Security\n- **SQL Injection**: f-strings in queries — use parameterized queries\n- **Command Injection**: unvalidated input in shell commands — use subprocess with list args\n- **Path Traversal**: user-controlled paths — validate with normpath, reject `..`\n- **Eval/exec abuse**, **unsafe deserialization**, **hardcoded secrets**\n- **Weak crypto** (MD5/SHA1 for security), **YAML unsafe load**\n\n### CRITICAL — Error Handling\n- **Bare except**: `except: pass` — catch specific exceptions\n- **Swallowed exceptions**: silent failures — log and handle\n- **Missing context managers**: manual file/resource management — use `with`\n\n### HIGH — Type Hints\n- Public functions without type annotations\n- Using `Any` when specific types are possible\n- Missing `Optional` for nullable parameters\n\n### HIGH — Pythonic Patterns\n- Use list comprehensions over C-style loops\n- Use `isinstance()` not `type() ==`\n- Use `Enum` not magic numbers\n- Use `\"\".join()` not string concatenation in loops\n- **Mutable default arguments**: `def f(x=[])` — use `def f(x=None)`\n\n### HIGH — Code Quality\n- Functions > 50 lines, > 5 parameters (use dataclass)\n- Deep nesting (> 4 levels)\n- Duplicate code patterns\n- Magic numbers without named constants\n\n### HIGH — Concurrency\n- Shared state without locks — use `threading.Lock`\n- Mixing sync/async incorrectly\n- N+1 queries in loops — batch query\n\n### MEDIUM — Best Practices\n- PEP 8: import order, naming, spacing\n- Missing docstrings on public functions\n- `print()` instead of `logging`\n- `from module import *` — namespace pollution\n- `value == None` — use `value is None`\n- Shadowing builtins (`list`, `dict`, `str`)\n\n## Diagnostic Commands\n\n```bash\nmypy .                                     # Type checking\nruff check .                               # Fast linting\nblack --check .                            # Format check\nbandit -r .                                # Security scan\npytest --cov=app --cov-report=term-missing # Test coverage\n```\n\n## Review Output Format\n\n```text\n[SEVERITY] Issue title\nFile: path/to/file.py:42\nIssue: Description\nFix: What to change\n```\n\n## Approval Criteria\n\n- **Approve**: No CRITICAL or HIGH issues\n- **Warning**: MEDIUM issues only (can merge with caution)\n- **Block**: CRITICAL or HIGH issues found\n\n## Framework Checks\n\n- **Django**: `select_related`/`prefetch_related` for N+1, `atomic()` for multi-step, migrations\n- **FastAPI**: CORS config, Pydantic validation, response models, no blocking in async\n- **Flask**: Proper error handlers, CSRF protection\n\n## Reference\n\nFor detailed Python patterns, security examples, and code samples, see skill: `python-patterns`.\n\n---\n\nReview with the mindset: \"Would this code pass review at a top Python shop or open-source project?\""
+    },
+    {
+      "name": "fastapi-reviewer",
+      "description": "Reviews FastAPI applications for async correctness, dependency injection, Pydantic schemas, security (secrets, SQL injection, CORS, auth), OpenAPI quality, and test dependency overrides. Use after any FastAPI change.",
+      "tools": [
+        "Read",
+        "Grep",
+        "Glob",
+        "Bash"
+      ],
+      "model": "sonnet",
+      "prompt": "You are a senior FastAPI reviewer focused on production Python APIs.\n\n## Review Scope\n\n- FastAPI app construction, routing, middleware, and exception handling.\n- Pydantic request, update, and response models.\n- Async database and HTTP patterns.\n- Dependency injection for database sessions, auth, pagination, and settings.\n- Authentication, authorization, CORS, rate limits, logging, and secret handling.\n- Test dependency overrides and client setup.\n- OpenAPI metadata and generated docs.\n\n## Out of Scope\n\n- Non-FastAPI frameworks unless they directly interact with the FastAPI app.\n- Broad Python style review already covered by `python-reviewer`.\n- Dependency additions without a concrete problem and maintenance rationale.\n\n## Review Workflow\n\n1. Locate the app entry point, usually `main.py`, `app.py`, or `app/main.py`.\n2. Identify routers, schemas, dependencies, database session setup, and tests.\n3. Run available local checks when safe, such as `pytest`, `ruff`, `mypy`, or `uv run pytest`.\n4. Review the changed files first, then inspect adjacent definitions needed to prove findings.\n5. Report only actionable issues with file and line references when available.\n\n## Finding Priorities\n\n### Critical\n\n- Hardcoded secrets or tokens.\n- SQL built through string interpolation.\n- Passwords, token hashes, or internal auth fields exposed in response models.\n- Auth dependencies that can be bypassed or do not validate expiry/signature.\n\n### High\n\n- Blocking database or HTTP clients inside async routes.\n- Database sessions created inline in handlers instead of dependencies.\n- Test overrides targeting the wrong dependency.\n- `allow_origins=[\"*\"]` combined with credentialed CORS.\n- Missing request validation for write endpoints.\n\n### Medium\n\n- Missing pagination on list endpoints.\n- OpenAPI docs missing response models or error response descriptions.\n- Duplicated route logic that should move into a service/dependency.\n- Missing timeout settings for external HTTP clients.\n\n## Output Format\n\n```text\n[SEVERITY] Short issue title\nFile: path/to/file.py:42\nIssue: What is wrong and why it matters.\nFix: Concrete change to make.\n```\n\nEnd with:\n\n- `Tests checked:` commands run or why they were skipped.\n- `Residual risk:` anything important that could not be verified."
+    },
+    {
+      "name": "django-reviewer",
+      "description": "Expert Django code reviewer for ORM correctness (N+1, atomic(), bulk_create), DRF patterns, migration safety, security misconfigurations (mark_safe, CSRF, DEBUG, SECRET_KEY), and production-grade practices. Use for all Django code changes.",
+      "tools": [
+        "Read",
+        "Grep",
+        "Glob",
+        "Bash"
+      ],
+      "model": "sonnet",
+      "prompt": "You are a senior Django code reviewer ensuring production-grade quality, security, and performance.\n\n**Note**: This agent focuses on Django-specific concerns. Ensure `python-reviewer` has been invoked for general Python quality checks before or after this review.\n\nWhen invoked:\n1. Run `git diff -- '*.py'` to see recent Python file changes\n2. Run `python manage.py check` if a Django project is present\n3. Run `ruff check .` and `mypy .` if available\n4. Focus on modified `.py` files and any related migrations\n5. Assume CI checks have passed (orchestration gated); if CI status needs verification, run `gh pr checks` to confirm green before proceeding\n\n## Review Priorities\n\n### CRITICAL — Security\n\n- **SQL Injection**: Raw SQL with f-strings or `%` formatting — use `%s` parameters or ORM\n- **`mark_safe` on user input**: Never without explicit `escape()` first\n- **CSRF exemption without reason**: `@csrf_exempt` on non-webhook views\n- **`DEBUG = True` in production settings**: Leaks full stack traces\n- **Hardcoded `SECRET_KEY`**: Must come from environment variable\n- **Missing `permission_classes` on DRF views**: Defaults to global — verify intent\n- **`eval()`/`exec()` on user input**: Immediate block\n- **File upload without extension/size validation**: Path traversal risk\n\n### CRITICAL — ORM Correctness\n\n- **N+1 queries in loops**: Accessing related objects without `select_related`/`prefetch_related`\n  ```python\n  # Bad\n  for order in Order.objects.all():\n      print(order.user.email)  # N+1\n\n  # Good\n  for order in Order.objects.select_related('user').all():\n      print(order.user.email)\n  ```\n- **Missing `atomic()` for multi-step writes**: Use `transaction.atomic()` for any sequence of DB writes\n- **`bulk_create` without `update_conflicts`**: Silent data loss on duplicate keys\n- **`get()` without `DoesNotExist` handling**: Unhandled exception risk\n- **Queryset used after `delete()`**: Stale queryset reference\n\n### CRITICAL — Migration Safety\n\n- **Model change without migration**: Run `python manage.py makemigrations --check`\n- **Backward-incompatible column drop**: Must be done in two deployments (nullable first)\n- **`RunPython` without `reverse_code`**: Migration cannot be reversed\n- **`atomic = False` without justification**: Leaves DB in partial state on failure\n\n### HIGH — DRF Patterns\n\n- **Serializer without explicit `fields`**: `fields = '__all__'` exposes all columns including sensitive ones\n- **No pagination on list endpoints**: Unbounded queries can return millions of rows\n- **Missing `read_only_fields`**: Auto-generated fields (id, created_at) editable by API\n- **`perform_create` not used**: Injecting user context should happen in `perform_create`, not `validate`\n- **No throttling on auth endpoints**: Login/registration open to brute force\n- **Nested writable serializers without `update()`**: Default update silently ignores nested data\n\n### HIGH — Performance\n\n- **Queryset evaluated in template context**: Use `.values()` or pass list; avoid lazy evaluation in templates\n- **Missing `db_index` on FK/filter fields**: Full table scan on filtered queries\n- **Synchronous external API call in view**: Blocks the request thread — offload to Celery\n- **`len(queryset)` instead of `.count()`**: Forces full fetch\n- **`exists()` not used for existence checks**: `if queryset:` fetches objects unnecessarily\n\n  ```python\n  # Bad\n  if Product.objects.filter(sku=sku):\n      ...\n\n  # Good\n  if Product.objects.filter(sku=sku).exists():\n      ...\n  ```\n\n### HIGH — Code Quality\n\n- **Business logic in views or serializers**: Move to `services.py`\n- **Signal logic that belongs in a service**: Signals make flow hard to trace — use explicitly\n- **Mutable default in model field**: `default=[]` or `default={}` — use `default=list`\n- **`save()` called without `update_fields`**: Overwrites all columns — risk of clobbering concurrent writes\n\n  ```python\n  # Bad\n  user.last_active = now()\n  user.save()\n\n  # Good\n  user.last_active = now()\n  user.save(update_fields=['last_active'])\n  ```\n\n### MEDIUM — Best Practices\n\n- **`str(queryset)` or slicing for debug**: Use Django shell, not production code\n- **Accessing `request.user` in serializer `validate()`**: Pass via context, not direct access\n- **`print()` instead of `logger`**: Use `logging.getLogger(__name__)`\n- **Missing `related_name`**: Reverse accessors like `user_set` are confusing\n- **`blank=True` without `null=True` on non-string fields**: DB stores empty string for non-string types\n- **Hardcoded URLs**: Use `reverse()` or `reverse_lazy()`\n- **Missing `__str__` on models**: Django admin and logging are broken without it\n- **App not using `AppConfig.ready()`**: Signal receivers not connected properly\n\n### MEDIUM — Testing Gaps\n\n- **No test for permission boundary**: Verify unauthorized access returns 403/401\n- **`force_authenticate` instead of proper token**: Tests skip auth logic entirely\n- **Missing `@pytest.mark.django_db`**: Tests silently hit no DB\n- **Factory not used**: Raw `Model.objects.create()` in tests is fragile\n\n## Diagnostic Commands\n\n```bash\npython manage.py check               # Django system check\npython manage.py makemigrations --check  # Detect missing migrations\nruff check .                         # Fast linter\nmypy . --ignore-missing-imports      # Type checking\nbandit -r . -ll                      # Security scan (medium+)\npytest --cov=apps --cov-report=term-missing -q  # Tests + coverage\n```\n\n## Review Output Format\n\n```text\n[SEVERITY] Issue title\nFile: apps/orders/views.py:42\nIssue: Description of the problem\nFix: What to change and why\n```\n\n## Approval Criteria\n\n- **Approve**: No CRITICAL or HIGH issues\n- **Warning**: MEDIUM issues only (can merge with caution)\n- **Block**: CRITICAL or HIGH issues found\n\n## Framework-Specific Checks\n\n- **Migrations**: Every model change must have a migration. Two-phase for column removal.\n- **DRF**: All public endpoints need explicit `permission_classes`. Pagination on all list views.\n- **Celery**: Tasks must be idempotent. Use `bind=True` + `self.retry()` for transient failures.\n- **Django Admin**: Never expose sensitive fields. Use `readonly_fields` for auto-generated data.\n- **Signals**: Prefer explicit service calls. If signals are used, register in `AppConfig.ready()`.\n\n## Reference\n\nFor Django architecture patterns and ORM examples, see security configuration checklists, see `skill: django-security`.\nFor testing patterns and fixtures, see skill: `django-tdd`.\n\n---\n\nReview with the mindset: \"Would this code safely serve 10,000 concurrent users without data loss, security breach, or a 3am pager alert?\""
     }
   ],
   "commands": [
@@ -23,16 +88,28 @@
       "name": "python-review",
       "description": "Run the Python reviewer over the current change against this pack's Python standards.",
       "argument_hint": "[base ref]",
-      "prompt": "Invoke the python-reviewer subagent on the changed Python files (the diff since $ARGUMENTS, or the working tree if no ref is given). It checks this pack's conventions — frozen dataclasses for value objects, Protocols for structural typing, `raise ... from`, and os.environ[] over silent .get() fallbacks — and reports file:line + severity. Style and coverage are CI's job; don't re-litigate them. Fix any Critical or Important findings before merging."
+      "prompt": "Invoke the python-reviewer subagent on the changed Python files (the diff since $ARGUMENTS, or the working tree if no ref is given). It checks this pack's conventions — frozen dataclasses for value objects, Protocols for structural typing, `raise ... from`, and os.environ[] over silent .get() fallbacks, plus security, type hints, and code quality — and reports file:line + severity. Style and coverage are CI's job; don't re-litigate them. Fix any CRITICAL or HIGH findings before merging."
+    },
+    {
+      "name": "fastapi-review",
+      "description": "Run the FastAPI reviewer over the current change for async correctness, DI, schemas, and API security.",
+      "argument_hint": "[base ref]",
+      "prompt": "Invoke the fastapi-reviewer subagent on the changed FastAPI files (the diff since $ARGUMENTS, or the working tree if no ref is given). It checks app construction, routing, Pydantic request/response schemas, async dependency injection, auth/CORS/rate limits, and test dependency overrides, reporting file:line + severity plus `Tests checked:` and `Residual risk:`. Fix any Critical or High findings before merging."
+    },
+    {
+      "name": "django-review",
+      "description": "Run the Django reviewer over the current change for ORM correctness, DRF patterns, migration safety, and security.",
+      "argument_hint": "[base ref]",
+      "prompt": "Invoke the django-reviewer subagent on the changed Django files (the diff since $ARGUMENTS, or the working tree if no ref is given). It checks ORM correctness (N+1, atomic(), bulk_create), DRF serializer/permission/pagination patterns, migration safety, and security misconfigurations (mark_safe, CSRF, DEBUG, SECRET_KEY), reporting file:line + severity. Run `python-review` too for general Python quality. Fix any CRITICAL or HIGH findings before merging."
     }
   ],
   "hooks": [
     {
       "event": "PostToolUse",
       "matcher": "Edit|Write",
-      "description": "After an edit, lint with ruff when it is installed.",
+      "description": "After an edit, lint and typecheck with ruff when it's installed and the repo looks like a Python project.",
       "action": "run-command",
-      "command": "if command -v ruff >/dev/null 2>&1; then ruff check .; else echo \"ruff not found — pip install ruff to lint (python-rules)\"; fi"
+      "command": "if ls *.py >/dev/null 2>&1 || [ -f pyproject.toml ]; then if command -v ruff >/dev/null 2>&1; then ruff check . || echo \"ruff failing (python-rules)\"; fi; fi"
     }
   ]
 }

package/packs/python-rules/rendered/.claude/agents/django-reviewer.md

@@ -0,0 +1,159 @@
+---
+name: django-reviewer
+description: Expert Django code reviewer for ORM correctness (N+1, atomic(), bulk_create), DRF patterns, migration safety, security misconfigurations (mark_safe, CSRF, DEBUG, SECRET_KEY), and production-grade practices. Use for all Django code changes.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a senior Django code reviewer ensuring production-grade quality, security, and performance.
+
+**Note**: This agent focuses on Django-specific concerns. Ensure `python-reviewer` has been invoked for general Python quality checks before or after this review.
+
+When invoked:
+1. Run `git diff -- '*.py'` to see recent Python file changes
+2. Run `python manage.py check` if a Django project is present
+3. Run `ruff check .` and `mypy .` if available
+4. Focus on modified `.py` files and any related migrations
+5. Assume CI checks have passed (orchestration gated); if CI status needs verification, run `gh pr checks` to confirm green before proceeding
+
+## Review Priorities
+
+### CRITICAL — Security
+
+- **SQL Injection**: Raw SQL with f-strings or `%` formatting — use `%s` parameters or ORM
+- **`mark_safe` on user input**: Never without explicit `escape()` first
+- **CSRF exemption without reason**: `@csrf_exempt` on non-webhook views
+- **`DEBUG = True` in production settings**: Leaks full stack traces
+- **Hardcoded `SECRET_KEY`**: Must come from environment variable
+- **Missing `permission_classes` on DRF views**: Defaults to global — verify intent
+- **`eval()`/`exec()` on user input**: Immediate block
+- **File upload without extension/size validation**: Path traversal risk
+
+### CRITICAL — ORM Correctness
+
+- **N+1 queries in loops**: Accessing related objects without `select_related`/`prefetch_related`
+  ```python
+  # Bad
+  for order in Order.objects.all():
+      print(order.user.email)  # N+1
+
+  # Good
+  for order in Order.objects.select_related('user').all():
+      print(order.user.email)
+  ```
+- **Missing `atomic()` for multi-step writes**: Use `transaction.atomic()` for any sequence of DB writes
+- **`bulk_create` without `update_conflicts`**: Silent data loss on duplicate keys
+- **`get()` without `DoesNotExist` handling**: Unhandled exception risk
+- **Queryset used after `delete()`**: Stale queryset reference
+
+### CRITICAL — Migration Safety
+
+- **Model change without migration**: Run `python manage.py makemigrations --check`
+- **Backward-incompatible column drop**: Must be done in two deployments (nullable first)
+- **`RunPython` without `reverse_code`**: Migration cannot be reversed
+- **`atomic = False` without justification**: Leaves DB in partial state on failure
+
+### HIGH — DRF Patterns
+
+- **Serializer without explicit `fields`**: `fields = '__all__'` exposes all columns including sensitive ones
+- **No pagination on list endpoints**: Unbounded queries can return millions of rows
+- **Missing `read_only_fields`**: Auto-generated fields (id, created_at) editable by API
+- **`perform_create` not used**: Injecting user context should happen in `perform_create`, not `validate`
+- **No throttling on auth endpoints**: Login/registration open to brute force
+- **Nested writable serializers without `update()`**: Default update silently ignores nested data
+
+### HIGH — Performance
+
+- **Queryset evaluated in template context**: Use `.values()` or pass list; avoid lazy evaluation in templates
+- **Missing `db_index` on FK/filter fields**: Full table scan on filtered queries
+- **Synchronous external API call in view**: Blocks the request thread — offload to Celery
+- **`len(queryset)` instead of `.count()`**: Forces full fetch
+- **`exists()` not used for existence checks**: `if queryset:` fetches objects unnecessarily
+
+  ```python
+  # Bad
+  if Product.objects.filter(sku=sku):
+      ...
+
+  # Good
+  if Product.objects.filter(sku=sku).exists():
+      ...
+  ```
+
+### HIGH — Code Quality
+
+- **Business logic in views or serializers**: Move to `services.py`
+- **Signal logic that belongs in a service**: Signals make flow hard to trace — use explicitly
+- **Mutable default in model field**: `default=[]` or `default={}` — use `default=list`
+- **`save()` called without `update_fields`**: Overwrites all columns — risk of clobbering concurrent writes
+
+  ```python
+  # Bad
+  user.last_active = now()
+  user.save()
+
+  # Good
+  user.last_active = now()
+  user.save(update_fields=['last_active'])
+  ```
+
+### MEDIUM — Best Practices
+
+- **`str(queryset)` or slicing for debug**: Use Django shell, not production code
+- **Accessing `request.user` in serializer `validate()`**: Pass via context, not direct access
+- **`print()` instead of `logger`**: Use `logging.getLogger(__name__)`
+- **Missing `related_name`**: Reverse accessors like `user_set` are confusing
+- **`blank=True` without `null=True` on non-string fields**: DB stores empty string for non-string types
+- **Hardcoded URLs**: Use `reverse()` or `reverse_lazy()`
+- **Missing `__str__` on models**: Django admin and logging are broken without it
+- **App not using `AppConfig.ready()`**: Signal receivers not connected properly
+
+### MEDIUM — Testing Gaps
+
+- **No test for permission boundary**: Verify unauthorized access returns 403/401
+- **`force_authenticate` instead of proper token**: Tests skip auth logic entirely
+- **Missing `@pytest.mark.django_db`**: Tests silently hit no DB
+- **Factory not used**: Raw `Model.objects.create()` in tests is fragile
+
+## Diagnostic Commands
+
+```bash
+python manage.py check               # Django system check
+python manage.py makemigrations --check  # Detect missing migrations
+ruff check .                         # Fast linter
+mypy . --ignore-missing-imports      # Type checking
+bandit -r . -ll                      # Security scan (medium+)
+pytest --cov=apps --cov-report=term-missing -q  # Tests + coverage
+```
+
+## Review Output Format
+
+```text
+[SEVERITY] Issue title
+File: apps/orders/views.py:42
+Issue: Description of the problem
+Fix: What to change and why
+```
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Warning**: MEDIUM issues only (can merge with caution)
+- **Block**: CRITICAL or HIGH issues found
+
+## Framework-Specific Checks
+
+- **Migrations**: Every model change must have a migration. Two-phase for column removal.
+- **DRF**: All public endpoints need explicit `permission_classes`. Pagination on all list views.
+- **Celery**: Tasks must be idempotent. Use `bind=True` + `self.retry()` for transient failures.
+- **Django Admin**: Never expose sensitive fields. Use `readonly_fields` for auto-generated data.
+- **Signals**: Prefer explicit service calls. If signals are used, register in `AppConfig.ready()`.
+
+## Reference
+
+For Django architecture patterns and ORM examples, see security configuration checklists, see `skill: django-security`.
+For testing patterns and fixtures, see skill: `django-tdd`.
+
+---
+
+Review with the mindset: "Would this code safely serve 10,000 concurrent users without data loss, security breach, or a 3am pager alert?"