Copilot instructions

1---
2applyTo: "**/*.py"
3---
4 
5## Context
6 
7This instruction file applies to all Python source files. The project uses Python 3.11+ with strict type annotations enforced by `mypy --strict`. All code must pass `ruff format` and `ruff check` with zero warnings. `logging` is mandatory — `print()` is never acceptable in production code. Dependencies are managed via `pyproject.toml` with version pinning.
8 
9---
10 
11## Coding Standards
12 
13- **Python version:** 3.11+ minimum; use `match` expressions, `ExceptionGroup`, `tomllib` where appropriate
14- **Type annotations on everything:** All function parameters and return types; `mypy --strict` must pass
15- **`logging` not `print()`:** `logging.getLogger(__name__)` in every module; parameterised messages only
16- **No bare `except:`:** Always catch a specific exception class; bare `except` masks `SystemExit` and `KeyboardInterrupt`
17- **No `import *`:** Explicit imports only — `from module import NameA, NameB`
18- **Pydantic or `@dataclass(frozen=True)` for domain objects:** Never raw `dict` as a domain object
19- **Constructor injection:** No module-level singleton instances; inject via FastAPI `Depends` or `__init__` parameters
20- **`async def` for all I/O:** Never blocking calls (`requests`, `time.sleep`) inside `async def` functions
21- **Settings via `BaseSettings`:** All configuration via `pydantic_settings.BaseSettings`; no hardcoded values
22- **`pyproject.toml`:** All project metadata, dependencies, and tool config in `pyproject.toml` — no `setup.py`
23 
24---
25 
26## Preferred Patterns
27 
28### Type-Annotated Function
29 
30```python
31# ✅ CORRECT
32import logging
33from typing import Sequence
34 
35logger = logging.getLogger(__name__)
36 
37async def find_orders(customer_id: str, statuses: list[str]) -> Sequence[Order]:
38    logger.info("Fetching orders: customer_id=%s, statuses=%s", customer_id, statuses)
39    return await order_repo.find_by_customer(customer_id, statuses)
40 
41# ❌ WRONG — no annotations, print() instead of logging
42def find_orders(customer_id, statuses):
43    print(f"Fetching orders for {customer_id}")
44    return order_repo.find_by_customer(customer_id, statuses)
45```
46 
47### Specific Exception Handling
48 
49```python
50# ✅ CORRECT
51try:
52    result = await external_service.call(payload)
53except ServiceUnavailableError as exc:
54    logger.error("External service unavailable", exc_info=True)
55    raise DependencyError("Payment service") from exc
56 
57# ❌ WRONG — bare except catches SystemExit, KeyboardInterrupt
58try:
59    result = await external_service.call(payload)
60except:
61    pass
62```
63 
64### Pydantic Domain Object
65 
66```python
67# ✅ CORRECT
68from pydantic import BaseModel, field_validator
69 
70class OrderId(BaseModel):
71    model_config = {"frozen": True}
72    value: str
73 
74    @field_validator("value")
75    @classmethod
76    def must_be_non_empty(cls, v: str) -> str:
77        if not v.strip():
78            raise ValueError("OrderId must not be empty")
79        return v
80 
81# ❌ WRONG — raw dict as domain object
82def process_order(order: dict) -> dict:
83    ...
84```
85 
86### Settings via BaseSettings
87 
88```python
89# ✅ CORRECT
90from pydantic_settings import BaseSettings
91 
92class AppSettings(BaseSettings):
93    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
94 
95    database_url: str
96    secret_key: str
97    kafka_bootstrap_servers: str
98 
99# ❌ WRONG — hardcoded configuration
100DATABASE_URL = "postgresql://user:password@localhost/db"
101```
102 
103---
104 
105## Anti-Patterns — Do NOT Generate
106 
107```python
108# WRONG: print() instead of logging [BLOCKER]
109print(f"Processing order {order_id}")
110 
111# WRONG: bare except [BLOCKER]
112try:
113    do_something()
114except:
115    pass
116 
117# WRONG: import star [MAJOR]
118from myapp.models import *
119 
120# WRONG: mutable default argument [MAJOR]
121def add_item(item: str, items: list[str] = []) -> list[str]:
122    items.append(item)
123    return items
124 
125# WRONG: blocking I/O in async function [MAJOR]
126async def fetch_data(url: str) -> bytes:
127    import requests
128    return requests.get(url).content  # blocks event loop
129 
130# WRONG: module-level singleton (global state) [MAJOR]
131db_engine = create_engine(DATABASE_URL)
132 
133# WRONG: missing type annotations [MAJOR]
134def process(data):
135    return data["value"]
136 
137# WRONG: Optional.get() equivalent — unguarded attribute access [MINOR]
138result = repo.find_by_id(id)
139return result.value  # AttributeError if None
140```
141 
142---
143 
144## Dependencies & Versions
145 
146| Technology | Version | Notes |
147|-----------|---------|-------|
148| Python | 3.11+ | Required for `ExceptionGroup`, `tomllib`, improved typing |
149| Pydantic | 2.x | `model_config` dict replaces `class Config:` |
150| pydantic-settings | 2.x | `BaseSettings` for environment configuration |
151| mypy | 1.x | Run with `--strict`; must pass with zero errors |
152| Ruff | 0.4+ | Replaces Black + Flake8 + isort; `ruff format` + `ruff check` |
153| pytest | 7.x+ | Async tests via `pytest-asyncio`; fixtures over `setUp/tearDown` |
154| pytest-asyncio | 0.23+ | `asyncio_mode = "auto"` in `pyproject.toml` |
155| httpx | 0.27+ | Async HTTP client; `AsyncClient` for async routes |
156 
157---
158 
159## Test Conventions
160 
161- Use `pytest` with `pytest-asyncio` for async tests — never `unittest.TestCase`
162- Mock external dependencies with `unittest.mock.AsyncMock` or `pytest-mock`
163- Use `Testcontainers` (via `testcontainers-python`) for database integration tests
164- Test file mirrors source: `src/myapp/orders.py` → `tests/test_orders.py`
165- One test class per domain class; one test method per behaviour
166- Use `pytest.mark.parametrize` for boundary value and equivalence class tests
167- Never use `time.sleep()` in tests — use `asyncio.wait_for()` or `anyio.fail_after()`
168