py-type-safetylisted
Install: claude install-skill CodeSigils/py-review-skill
# Python Type-Safety Review
Use these rules only after reading the changed code. Prefer findings that would
be caught by a type checker or prevent a realistic runtime bug.
## Review Rules
### Rule: type-public-signatures
**Impact:** MEDIUM-HIGH
**Applies when:** Public functions, methods, classes, or exported helpers are added or changed.
**Skip when:** The code is private test scaffolding or a throwaway script with no typed boundary.
**Python:** any
**Tools:** mypy | pyright | project-configured
**Review signal:** Public parameters or return values are unannotated, especially at package/API boundaries.
**Incorrect:**
```python
def find_user(user_id):
return repository.get(user_id)
```
**Correct:**
```python
def find_user(user_id: str) -> User | None:
return repository.get(user_id)
```
**Reason:** Public annotations make absence and data shape explicit. Without them, callers and type checkers lose the contract at the boundary.
### Rule: type-any-leak
**Impact:** HIGH
**Applies when:** `Any`, `dict[str, Any]`, raw JSON, or untyped third-party results cross into domain code.
**Skip when:** The value remains at a narrow dynamic boundary and is immediately validated or converted.
**Python:** any
**Tools:** mypy | pyright | project-configured
**Review signal:** `Any` appears in return types, domain objects, or widely reused helper signatures.
**Incorrect:**
```python
def load_user(payload: dict[str, Any]) -> Any:
return payload["user"]
```
**Correct:**
```pyth