Function Type Hints
Learn how parameter and return hints document the values that cross a function boundary. You will read primitive hints, use None for action-only functions, and distinguish annotations from runtime conversion, validation, and testing.
A function header can record the kinds of values that cross its boundary. The extra notation is called a type hint:
The calculation is unchanged. The hints tell a reader that fahrenheit is
expected to be a floating-point number and that the function is expected to
return a floating-point number.
Read Parameter and Return Hints Separately
Start inside the parentheses:
def repeat(text: str, times: int) -> str:
text: strsays thattextis expected to refer to a string;times: intsays thattimesis expected to refer to an integer;-> strsays that the function is expected to return a string.
The colon at the end still begins the indented function body. The arrow and the type before that colon form the return hint.
Read a hinted interface
Predict the result, run the code, then change either argument while keeping its expected type.
Ready to run.
Hints make the interface easier to inspect before you read the body. They are especially useful when a function has several inputs or when the returned value is stored far from the call.
Use None When a Function Only Performs an Action
A function that displays a message but does not return a useful value can use
-> None:
This does not mean the function returns the text "None". It records the same
behavior learned earlier: when the function reaches its end without an explicit
return, the call returns the value None.
Hints Describe; Python Still Runs the Values
Ordinary Python does not enforce type hints during a call:
The call displays haha. The hint says that callers should supply an integer,
but the runtime operation is still string repetition. A hint does not convert a
value and does not replace validation.
Editors and separate static type-checking tools can compare annotated interfaces with the code that uses them. A later chapter shows how to run such a checker. For now, treat hints as precise notes about a function boundary.
Hint the Interface, Not Every Obvious Local Name
This interface benefits from hints:
The local name error is clearly produced by subtracting two numbers, so an
extra annotation there would add little. Parameters and return values usually
provide the most useful starting points.
Exercise: Read a return hint
What type of value is this function expected to return?
def word_count(text: str) -> int:
Answer it first, then check.
HintLook after the arrow
Parameter hints are inside the parentheses. The return hint follows ->.
SolutionThe function is expected to return an integer
The header ends with -> int, so the expected return type is int.
Exercise: Match hints to parameters
Which statement correctly describes this interface?
def label_score(name: str, score: float) -> str:
Select one choice, then check.
HintRead one boundary at a time
Read name: str, then score: float, then -> str.
SolutionThe function expects text and a number
name is expected to be a string, score a float, and the returned value a
string.
Exercise: Separate hints from runtime enforcement
What happens when ordinary Python runs this call?
Select one choice, then check.
HintEvaluate the operation that actually runs
For a string, multiplication by 2 repeats the string.
SolutionThe call returns gogo
The runtime value is a string, so value * 2 performs string repetition.
A separate checker could report the inconsistent call without changing this
runtime behavior.
Exercise: Add hints without changing the calculation
Add hints stating that both parameters and the returned value are floats. Keep the function body unchanged.
Annotate a function boundary
Ready to run.
HintAnnotate the complete interface
Write target: float, prediction: float, and -> float in the function
header.
SolutionHint both parameters and the return value
Write:
The annotations change the documented interface, not the calculation.
Exercise: Describe an action-only function
Which return hint best describes this function?
Select one choice, then check.
HintRecall print versus return
The body has no explicit return statement.
SolutionUse a None return hint
-> None records that the function performs an action and does not provide a
useful returned value to its caller.
Use Hints to Clarify Value Flow
Type hints add the most value when they make a function boundary easier to read. They do not make a program correct by themselves. Clear names, suitable runtime checks, and tests still describe and verify parts of the behavior that a type alone cannot express.