Initial commit

skills/python-code-quality/mypy-configuration.md

@@ -0,0 +1,374 @@
+# Mypy Type Checking Configuration
+
+Mypy is a static type checker for Python that helps catch bugs before runtime.
+
+## Basic Configuration
+
+Add to `pyproject.toml`:
+
+```toml
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+strict_equality = true
+show_error_codes = true
+show_column_numbers = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = "third_party_package.*"
+ignore_missing_imports = true
+```
+
+## Strictness Levels
+
+### Minimal (Getting Started)
+```toml
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = false
+warn_unused_configs = true
+```
+
+### Moderate (Recommended)
+```toml
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+```
+
+### Strict (Maximum Safety)
+```toml
+[tool.mypy]
+strict = true
+python_version = "3.11"
+```
+
+## Common Configuration Options
+
+### Type Checking Strictness
+
+```toml
+# Require type annotations
+disallow_untyped_defs = true          # Functions must have type hints
+disallow_untyped_calls = true         # Can't call untyped functions
+disallow_incomplete_defs = true       # All params must be typed
+
+# Optional handling
+no_implicit_optional = true           # Optional must be explicit
+strict_optional = true                # None checking enabled
+
+# Any type usage
+disallow_any_unimported = false       # Allow Any from untyped imports
+disallow_any_expr = false             # Forbid Any in expressions
+disallow_any_decorated = false        # Forbid Any in decorators
+disallow_any_explicit = false         # Forbid explicit Any
+```
+
+### Warning Messages
+
+```toml
+warn_return_any = true                # Warn on returning Any
+warn_redundant_casts = true           # Warn on unnecessary casts
+warn_unused_ignores = true            # Warn on unused type: ignore
+warn_unused_configs = true            # Warn on unused config options
+warn_no_return = true                 # Warn on missing returns
+warn_unreachable = true               # Warn on unreachable code
+```
+
+### Error Reporting
+
+```toml
+show_error_codes = true               # Show error codes in messages
+show_column_numbers = true            # Show column numbers
+pretty = true                         # Pretty print errors
+color_output = true                   # Colorize output
+error_summary = true                  # Show error summary
+```
+
+## Type Hints Guide
+
+### Basic Types
+
+```python
+from typing import Any, Optional, Union
+
+# Simple types
+def greet(name: str) -> str:
+    return f"Hello, {name}"
+
+# Optional (can be None)
+def find_user(user_id: int) -> Optional[User]:
+    return user_map.get(user_id)
+
+# Modern Optional syntax (Python 3.10+)
+def find_user(user_id: int) -> User | None:
+    return user_map.get(user_id)
+
+# Union types
+def process(value: Union[int, str]) -> bool:
+    return True
+
+# Modern Union syntax (Python 3.10+)
+def process(value: int | str) -> bool:
+    return True
+```
+
+### Collections
+
+```python
+from typing import List, Dict, Set, Tuple
+
+# Lists
+def process_items(items: List[str]) -> List[int]:
+    return [len(item) for item in items]
+
+# Modern syntax (Python 3.9+)
+def process_items(items: list[str]) -> list[int]:
+    return [len(item) for item in items]
+
+# Dictionaries
+def get_config() -> Dict[str, Any]:
+    return {"key": "value"}
+
+# Modern syntax
+def get_config() -> dict[str, Any]:
+    return {"key": "value"}
+
+# Sets
+def unique_items(items: Set[int]) -> int:
+    return len(items)
+
+# Tuples (fixed size)
+def get_coordinates() -> Tuple[float, float]:
+    return (1.0, 2.0)
+
+# Tuples (variable size)
+def get_numbers() -> Tuple[int, ...]:
+    return (1, 2, 3, 4, 5)
+```
+
+### Callable Types
+
+```python
+from typing import Callable
+
+# Function that takes int and returns str
+Handler = Callable[[int], str]
+
+def process(handler: Handler) -> None:
+    result = handler(42)
+
+# Multiple parameters
+Callback = Callable[[str, int], bool]
+
+# No parameters
+Factory = Callable[[], MyClass]
+```
+
+### Generic Types
+
+```python
+from typing import TypeVar, Generic
+
+T = TypeVar('T')
+
+class Container(Generic[T]):
+    def __init__(self, value: T) -> None:
+        self.value = value
+
+    def get(self) -> T:
+        return self.value
+
+# Usage
+container: Container[int] = Container(42)
+value: int = container.get()
+```
+
+### Protocol Types
+
+```python
+from typing import Protocol
+
+class Drawable(Protocol):
+    def draw(self) -> None: ...
+
+def render(item: Drawable) -> None:
+    item.draw()
+
+# Any class with draw() method works
+class Circle:
+    def draw(self) -> None:
+        print("Drawing circle")
+
+render(Circle())  # Type checks!
+```
+
+## Commands Reference
+
+```bash
+# Check all files
+mypy src
+
+# Check specific file
+mypy src/module.py
+
+# Strict mode
+mypy --strict src
+
+# Show error codes
+mypy --show-error-codes src
+
+# Generate type stubs
+stubgen -p mypackage -o stubs
+
+# Check against installed packages
+mypy --install-types
+mypy --non-interactive --install-types
+```
+
+## Common Errors and Fixes
+
+### Error: "Argument has incompatible type"
+
+```python
+# Problem
+def greet(name: str) -> str:
+    return f"Hello, {name}"
+
+greet(123)  # Error: Argument 1 has incompatible type "int"
+
+# Fix: Pass correct type
+greet("World")
+
+# Or: Convert type
+greet(str(123))
+```
+
+### Error: "Function is missing a return statement"
+
+```python
+# Problem
+def get_value() -> int:
+    if condition:
+        return 42
+    # Missing return!
+
+# Fix: Add return for all paths
+def get_value() -> int:
+    if condition:
+        return 42
+    return 0
+```
+
+### Error: "Need type annotation"
+
+```python
+# Problem
+items = []  # Error: Need type annotation
+
+# Fix: Add type annotation
+items: list[str] = []
+
+# Or: Initialize with values
+items = ["a", "b", "c"]
+```
+
+### Error: "Incompatible return type"
+
+```python
+# Problem
+def get_name() -> str:
+    return None  # Error: Incompatible return
+
+# Fix: Use Optional
+def get_name() -> str | None:
+    return None
+```
+
+## Ignoring Errors
+
+```python
+# Ignore single line
+result = unsafe_function()  # type: ignore
+
+# Ignore with reason
+result = unsafe_function()  # type: ignore[arg-type]
+
+# Ignore entire file
+# mypy: ignore-errors
+```
+
+## Third-Party Package Stubs
+
+### Installing Type Stubs
+
+```bash
+# Install stubs for requests
+uv add --dev types-requests
+
+# Common stubs
+uv add --dev types-requests
+uv add --dev types-redis
+uv add --dev types-PyYAML
+```
+
+### Handling Missing Stubs
+
+```toml
+[[tool.mypy.overrides]]
+module = "untyped_package.*"
+ignore_missing_imports = true
+```
+
+## VSCode Integration
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "python.linting.mypyEnabled": true,
+  "python.linting.enabled": true,
+  "python.analysis.typeCheckingMode": "basic"
+}
+```
+
+## Best Practices
+
+1. **Start gradual**: Enable mypy gradually, module by module
+2. **Use strict mode**: `strict = true` for new projects
+3. **Add type hints everywhere**: Functions, methods, variables
+4. **Use Protocol for duck typing**: Better than inheritance
+5. **Leverage modern syntax**: Use `list` instead of `List` (Python 3.9+)
+6. **Install type stubs**: For all third-party packages
+7. **Run in CI**: Fail builds on type errors
+8. **Document with types**: Types serve as documentation
+
+## Incremental Adoption
+
+```toml
+# Start with specific directories
+[tool.mypy]
+files = ["src/critical_module"]
+strict = true
+
+# Gradually expand
+files = ["src/critical_module", "src/api"]
+
+# Eventually cover everything
+files = ["src"]
+```