Pylerno
English

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

python
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

  1. The annotation states that average receives numeric data and may return None.
  2. An early return handles the empty list before division.
  3. The demonstration calls show a normal average and the deliberate empty result.
text
90.0
None
Line-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.

Check your understanding

What does this program print?

python
x: int = "7"
print(type(x).__name__)
Choose one answer

Search documentation

Share this page