# Type Hints: Saying What a Value Should Be

A type hint is a label on a variable, a parameter or a return value that says what kind of value belongs there, such as float, list\[float\] or a string that may be None, so people and tools can see what a function expects without reading its body.

Apprentice · Python · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Add type hints to a variable, a function's parameters and its return value, and explain that Python doesn't check them as it runs
- Write type hints for lists, dictionaries and values that may be None

## Key takeaways

- A type hint names the kind of value that belongs in a variable, a parameter or a return value, so a reader knows what to pass in without reading the function's body.
- A hint for a collection names what's inside it too, list[float] for a list of floats and dict[str, int] for a dictionary whose keys are text and whose values are whole numbers.
- str | None, read "a string or None", is the hint for a value that may be missing, such as the answer when a member isn't on the list.
- Python doesn't check hints as the code runs, so a wrong value still goes in. A type checker such as mypy reads them without running anything.

You'll meet type hints the first time you open a library's documentation or a teammate's code and see a line such as `def send_email(to: str, subject: str) -> bool:`. VS Code shows them as you type a call, and web frameworks such as FastAPI read them to check what a request holds. Writing them on your own functions answers the question everyone who calls a function asks: what do I pass in, and what comes back?

The example is Peak Fitness, a gym with three membership plans: basic at $25.00 a month, plus at $40.00 and premium at $60.00.

## What does this function want?

Here's a function from the gym's front desk. It works out what a member pays for a few months:

```python
def membership_cost(price, months):
    return price * months


print(membership_cost(29.5, 3))
print(membership_cost("29.5", 3))
```

```text
88.5
29.529.529.5
```

The first call gives the right answer. The second gets the price as text, `"29.5"` in quotes, the way a value arrives from `input()`, a form or a CSV file. `*` on text repeats it, so the function hands back `29.529.529.5` with no error at all: a wrong answer that looks a lot like a price.

Nothing in `def membership_cost(price, months):` says the price must be a number. To find out, you'd read the body, and in a long function that takes a while.

## Type hints: a label on each blank

Think of a paper form. Each blank has a small label under it: *Amount ($)*, *Number of months*. The label doesn't stop anyone writing nonsense, but it tells every reader what belongs there.

A **type hint** is that label for your code. (Some textbooks call it a *type annotation*.) It goes after a colon, and the return value's hint goes after `->`, read "returns":

```python
def membership_cost(price: float, months: int) -> float:
    return price * months


print(membership_cost(29.5, 3))
print(membership_cost("29.5", 3))
```

```text
88.5
29.529.529.5
```

Read the first line aloud: "membership_cost takes a price, a float, and months, an int, and returns a float." The four basic hints are `int` (a whole number), `float` (a number with a decimal point), `str` (text) and `bool` (`True` or `False`). An `int` is fine where a `float` is hinted, since 30 is a price too.

![A paper sign-up form beside the line def membership_cost(price: float, months: int) -> float: each blank on the form has a label (Price: a decimal number, Months: a whole number, Total: a decimal number), and each label matches a type hint in the line of code](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/815247f962d440bc8e5d64edd3965c85.webp)

Look back at the output, though: it's the same as before. **Python doesn't check hints as the code runs.** They're for people and for tools. VS Code shows them when you hover over a call, and a **type checker** such as mypy reads them without running anything, and points at the second call before a member ever sees `29.529.529.5`.

A variable can have a hint too, written the same way:

```python
member_name: str = "Rosa"
visits: int = 12
is_student: bool = True
print(member_name, visits, is_student)
```

```text
Rosa 12 True
```

Most code hints its functions and leaves variables alone, because Python can tell a variable's type from the value it starts with.

## Hints for lists and dictionaries

A list's hint names what's in it, in square brackets: `list[float]` is read "a list of floats". A dictionary's hint names its keys, then its values: `dict[str, int]` is read "a dict from str to int", text keys with whole-number values.

```python
def average_visits(visits: list[int]) -> float:
    return sum(visits) / len(visits)


plan_prices: dict[str, float] = {"basic": 25.0, "plus": 40.0, "premium": 60.0}
weekly_visits: list[int] = [3, 4, 2, 5]
print(average_visits(weekly_visits))
print(plan_prices["plus"])
```

```text
3.5
40.0
```

A variable's hint earns its place when the value doesn't say enough: `checkins: list[str] = []` starts empty, and only the hint says it will hold names.

## Maybe a value, maybe None

Some members rent a locker and some don't. A function that looks up a member's locker number has two possible answers: a number, or `None`, Python's value for "nothing here". Its hint says so with `|`, read "or":

```python
def locker_for(name: str, lockers: dict[str, int]) -> int | None:
    if name in lockers:
        return lockers[name]
    return None


lockers: dict[str, int] = {"Rosa": 14, "Dev": 27}
print(locker_for("Rosa", lockers))
print(locker_for("Mia", lockers))
```

```text
14
None
```

`int | None` is read "an int or None". Anyone who calls `locker_for` sees from the first line that the answer can be missing, and checks for `None` before using it as a number. A function that only prints and never returns a value is hinted `-> None`. In older code and some textbooks you'll see `Optional[int]`, from the `typing` module: it means the same as `int | None`.

## Do it: say which classes still have room

Peak Fitness's app shows how many spots are left in each class. The app's developers asked for a function whose first line says exactly what it takes and what it gives back.

- `class_name`: the class to look up, as text, such as `"spin"`.
- `spots`: a dictionary from each class's name to how many spots are left in it.

**Your job:** finish `spots_left(class_name, spots)`, with type hints, so it returns how many spots are left in the class.

- Hint `class_name` as `str`, `spots` as `dict[str, int]`, and the return value as `int | None`.
- When the class is in `spots`, return its number of spots, even when that's `0`.
- When the class isn't in `spots`, return `None`.

Worked through: with `spots = {"spin": 4, "yoga": 0, "boxing": 12}`, `spots_left("spin", spots)` returns `4`. `spots_left("yoga", spots)` returns `0`: the class is full. `spots_left("pilates", spots)` returns `None`, because Peak Fitness has no pilates class.

Practiced live on the lesson page: write the Python right there and check it.

## Check yourself

2 questions to try on the lesson page.

## So what

A function's first line, with its hints, tells every reader and every tool what goes in and what comes out, which is the start of catching a wrong value before it reaches a member's bill.

## Key terms

- [Type Hint](https://www.ask-codey.com/glossary/type-hint)
- [Union Type](https://www.ask-codey.com/glossary/union-type)
- [None](https://www.ask-codey.com/glossary/none)
- [Static Typing](https://www.ask-codey.com/glossary/static-typing)

## Related

- [Parameters and Return Values](https://www.ask-codey.com/lessons/python-functions-parameters-and-return)
- [Checking Types with mypy](https://www.ask-codey.com/lessons/python-type-checking-with-mypy)

Source: https://www.ask-codey.com/lessons/python-type-hints
