Type hints
Read a function contract and handle None before using its result.
On this page
The concept
Type hints communicate intended inputs and outputs to readers and static tools. list[float] describes the element type, and float | None describes two possible return forms. Python does not automatically enforce those annotations at runtime. Validation is still necessary for untrusted input.
An empty average needs a policy. Returning None makes absence explicit instead of inventing a numeric result. Callers must narrow the result with an is None check before performing a numeric operation. This is a useful first example of making an edge case visible in an interface.
Worked example
def average(numbers: list[float]) -> float | None:
if not numbers:
return None
return sum(numbers) / len(numbers)
scores: list[float] = [80.0, 90.0, 100.0]
print(average(scores))
print(average([]))Trace the result
- The annotation states that average receives numeric data and may return None.
- An early return handles the empty list before division.
- The demonstration calls show a normal average and the deliberate empty result.
90.0
NoneLine-by-line walkthrough
Lines 1–4: def average(numbers: list[float]) -> float | None:
Define the function average with input names numbers. Definition stores the operation rather than executing its body. An ordinary call executes a normal function; a coroutine runs when awaited/scheduled, and a generator advances when consumed. Decorators can provide a context-manager or wrapper interface. Indented statements below belong to this operation.
Lines 2–3: if not numbers:
Evaluate not numbers. Execute the indented body if it is truthy; otherwise follow the alternative branch, if present. Branch order and indentation are part of the behavior.
Line 3: return None
Evaluate None and return that value to the caller. This ends the current function call; subsequent statements on this execution path do not run.
Line 4: return sum(numbers) / len(numbers)
Evaluate sum(numbers) / len(numbers) and return that value to the caller. This ends the current function call; subsequent statements on this execution path do not run.
Line 7: scores: list[float] = [80.0, 90.0, 100.0]
Declare the intended type of scores as list[float] and initialize it with [80.0, 90.0, 100.0]. The annotation communicates a contract; it does not perform runtime conversion.
Line 8: print(average(scores))
Evaluate the print arguments from the current state and display them. sep controls separators and end controls the ending when those options are provided. Displaying a value does not return that value from the surrounding function.
Line 9: print(average([]))
Evaluate the print arguments from the current state and display them. sep controls separators and end controls the ending when those options are provided. Displaying a value does not return that value from the surrounding function.
Common mistake
An annotation does not convert a value. Writing -> int does not make an arbitrary returned object an integer.