python-type-hints

## Quick Reference

| Type | Syntax (3.9+) | Example |
|------|---------------|---------|
| List | `list[str]` | `names: list[str] = []` |
| Dict | `dict[str, int]` | `ages: dict[str, int] = {}` |
| Optional | `str \| None` | `name: str \| None = None` |
| Union | `int \| str` | `value: int \| str` |
| Callable | `Callable[[int], str]` | `func: Callable[[int], str]` |

| Feature | Version | Syntax |
|---------|---------|--------|
| Type params | 3.12+ | `def first[T](items: list[T]) -> T:` |
| type alias | 3.12+ | `type Point = tuple[float, float]` |
| Self | 3.11+ | `def copy(self) -> Self:` |
| TypeIs | 3.13+ | `def is_str(x) -> TypeIs[str]:` |

| Construct | Use Case |
|-----------|----------|
| `Protocol` | Structural subtyping (duck typing) |
| `TypedDict` | Dict with specific keys |
| `Literal["a", "b"]` | Specific values only |
| `Final[str]` | Cannot be reassigned |

## When to Use This Skill

Use for **static type checking**:
- Adding type hints to functions and classes
- Creating typed dictionaries with TypedDict
- Defining protocols for duck typing
- Configuring mypy or pyright
- Writing generic functions and classes

**Related skills:**
- For Python fundamentals: see `python-fundamentals-313`
- For testing: see `python-testing`
- For FastAPI schemas: see `python-fastapi`

---

# Python Type Hints Complete Guide

## Overview

Type hints enable static type checking, better IDE support, and self-documenting code. Python's typing system is gradual - you can add types incrementally.

## Modern Type Hints (Python 3.9+)

### Built-in Generic Types

```python
# Python 3.9+ - Use built-in types directly
# No need for typing.List, typing.Dict, etc.

def process_items(items: list[str]) -> dict[str, int]:
    return {item: len(item) for item in items}

# Collections
names: list[str] = ["Alice", "Bob"]
ages: dict[str, int] = {"Alice": 30, "Bob": 25}
coordinates: tuple[float, float] = (1.0, 2.0)
unique_ids: set[int] = {1, 2, 3}
frozen_data: frozenset[str] = frozenset(