@sentry/warden 0.24.0 → 0.25.0

package/src/builtin-skills/code-review/references/python.md

@@ -0,0 +1,77 @@
+# Python Bug Review Notes
+
+Use this when reviewing Python, Django, Flask, FastAPI, Celery, or Python service code. These notes refine the core `code-review` skill; they do not add style, architecture, security, or performance-only scope.
+
+## Runtime Boundaries
+
+- Type hints are not runtime validation. Treat request data, query params, env vars, external API responses, database rows, task payloads, and deserialized files as shape-unknown until validated.
+- Pydantic models, DRF serializers, dataclasses, typed dicts, Django model fields, migrations, and existing tests can prove the intended contract. Read them before reporting a mismatch.
+- Decorators and framework hooks can change call order, transaction scope, auth context, and exception behavior. Verify the effective path.
+- Background tasks and management commands often run outside request transactions and sessions. Check idempotency, tenant/account context, and retry behavior before reporting.
+
+## High-Signal Patterns
+
+| Pattern | Bug Shape | Safer Shape |
+|---------|-----------|-------------|
+| Mutable defaults | Function, dataclass, or model defaults reuse lists, dicts, sets, or objects across calls or instances. | Use `None` plus initialization, `default_factory`, or framework-specific callable defaults. |
+| Falsey fallback | `value or default` treats `0`, `False`, or `""` as absent when those are valid values. | Check `is None`, missing keys, or explicit sentinel values. |
+| Missing `None` handling | `.first()`, `.get()`, optional config, env values, cache reads, or external responses are dereferenced without proving presence. | Add explicit absence handling or enforce presence at the boundary. |
+| Swallowed errors | Broad `except` returns success, empty data, or partial defaults that callers treat as complete. | Propagate failure, return explicit partial state, or compensate rolled-back work. |
+| Transaction gaps | Multiple writes, task enqueues, cache updates, or file operations can partially succeed when a later step fails. | Use transactions, `on_commit`, idempotency keys, or compensation. |
+| Async mismatch | Coroutine is not awaited, blocking I/O runs in an async endpoint, or async context managers are entered incorrectly. | Await coroutines, use async clients, and keep blocking work out of event-loop paths. |
+| Iterator exhaustion | Generators, queryset iterators, request streams, or file objects are consumed once and then reused as if still populated. | Materialize intentionally or pass a fresh iterator/stream. |
+| Timezone and precision | Naive and aware datetimes are mixed, date boundaries use server local time, or decimal money is converted to float. | Normalize timezone and use `Decimal` or integer minor units for money. |
+| Query and migration drift | Renamed fields, changed defaults, non-null constraints, data migrations, or backfills miss existing rows or write wrong records. | Include backward-compatible migrations and scoped update filters. |
+| Task retry side effects | Celery or queue retries duplicate emails, charges, state transitions, or external calls. | Make side effects idempotent or persist completion before retryable boundaries. |
+
+## False-Positive Controls
+
+- Django ORM, SQLAlchemy, and Pydantic can enforce contracts. Verify the exact model, serializer, or schema before reporting.
+- `get_or_create`, `update_or_create`, database constraints, and transactions can mitigate duplicate or partial-write paths.
+- A broad `except` is not a finding if the caller receives explicit failure state and no partial success is claimed.
+- Mutable values are safe when created inside the function or supplied by a documented immutable factory.
+- QuerySet laziness is not a bug by itself. Show the changed evaluation order that produces wrong data.
+- Type-checker-only issues are findings only when they deterministically break runtime behavior, packaging, or CI.
+
+## Minimal Examples
+
+**Report: mutable default**
+
+```python
+def collect_errors(error, bucket=[]):
+    bucket.append(error)
+    return bucket
+```
+
+Every call shares the same list, so unrelated requests can see stale errors.
+
+**Report: swallowed partial failure**
+
+```python
+try:
+    charge_customer(invoice)
+    mark_paid(invoice)
+except Exception:
+    return {"ok": True}
+```
+
+The caller receives success even if charging or persistence failed.
+
+**Report: missing absence handling**
+
+```python
+profile = Profile.objects.filter(user_id=user_id).first()
+return profile.timezone
+```
+
+If profiles are optional or not yet created, this crashes instead of following the expected fallback.
+
+**Do not report: dataclass default factory**
+
+```python
+@dataclass
+class Batch:
+    items: list[str] = field(default_factory=list)
+```
+
+Each instance receives a fresh list.