How can someone tell what to pass to a function before calling it? A function named `generate_stats(measures)` does not reveal that `measures` should be a list or tuple. Type hints make intended argument and return types visible in the function signature, helping callers use the function correctly. section 6.3
Annotate a function signature
```python from statistics import mean, stdev def generate_stats(measures: list) -> tuple: return mean(measures), stdev(measures) ``` Use `parameter: type` for an argument and `-> type` for the return value. Calling `help(generate_stats)` displays the annotated signature: `generate_stats(measures: list) -> tuple`. The hints describe the intended inputs and output; they do not enforce those types at runtime. section 6.3.2 section 6.3.1
Start with the simplest useful hint, then add detail where it helps a caller:
- Annotate a variable with a colon, as in `number: int = 3`. Python remains dynamically typed: a later assignment can give that variable a value of another type. section 6.3.1
- Put a parameter's type before its default value: `multiplier: int = 1`. A custom class can also serve as a parameter type. section 6.3.3
- Specify container contents when `list` alone is too broad: `list[Task]` distinguishes task objects from strings. Use forms such as `dict[int, str]` or `tuple[float, ...]` when their contents matter. section 6.3.3
- Use `|` for alternatives, such as `list[float] | tuple[float, ...]`. `Sequence[float]` from `typing` can express the shared sequence requirement instead. section 6.3.3 section 6.3.4
Table 6.1 Type hints for common built-in container objects (view table figure)
| A dict of keys using int objects and values using str objects |
||
| A dict of keys using int objects and values using list objects of int objects |
||
Compare common container annotations when choosing how precisely to describe a function's inputs. section 6.3.3
Hints also help an IDE flag incompatible arguments while you code. They complement rather than replace documentation or runtime checks. One important distinction: a data class uses field annotations to identify fields and generate methods such as `__init__`; an unannotated attribute will not become a field through that mechanism. section 6.3.2 section 9.2.2
