Python Return Annotation

A Python return annotation is a syntactic construct used to specify the expected data type of the value returned by a function or method. Introduced in PEP 3107 and standardized for type hinting in PEP 484, it attaches metadata to the function signature without altering its runtime execution behavior.

def function_name(parameters) -> return_type:
    # function body
    pass

Syntax and Mechanics

The annotation is defined using the right arrow token (->) placed immediately after the closing parenthesis of the parameter list and before the colon that initiates the function block. The return_type can be any valid Python expression, though it is conventionally a class, a string (for forward references), or a construct from the typing module. Runtime Behavior The Python interpreter evaluates the return annotation expression at function definition time. However, Python is dynamically typed; the interpreter does not enforce type compliance during execution. Returning a value that contradicts the annotation will not raise a TypeError or RuntimeError. Enforcement is strictly the domain of static type checkers (e.g., mypy, pyright). Internal Storage When the Python interpreter constructs the function object, it stores the evaluated return annotation in the function’s __annotations__ dunder attribute. This attribute is a dictionary where the reserved key 'return' maps to the specified type object.

def serialize_data(payload: dict) -> str:
    return str(payload)


# The interpreter stores the metadata in the __annotations__ dictionary
print(serialize_data.__annotations__)

# Output: {'payload': <class 'dict'>, 'return': <class 'str'>}

Annotation Variants

Void Returns Functions that do not explicitly return a value (implicitly returning None) are annotated with the None literal.

def write_to_log(message: str) -> None:
    print(f"LOG: {message}")

Complex and Compound Types Return annotations support complex type definitions using built-in generics (PEP 585) and the union operator (| via PEP 604), or their legacy equivalents from the typing module.

# Returning a dictionary with string keys and integer values, or None
def fetch_metrics() -> dict[str, int] | None:
    pass

NoReturn For functions that are guaranteed to never return control to the caller (e.g., functions that unconditionally raise an exception or terminate the process), the return annotation utilizes typing.NoReturn.

from typing import NoReturn

def trigger_fatal_error(code: int) -> NoReturn:
    raise SystemExit(code)

Forward References If the return type is a class that has not yet been defined in the current scope, the annotation must be provided as a string literal to prevent a NameError during definition-time evaluation. Alternatively, from __future__ import annotations (PEP 563) can be used to defer the evaluation of all annotations in the module.

def factory_method() -> 'MyClass':
    return MyClass()

class MyClass:
    pass

Tired of Poor Python Skills? Fix That With Deep Grasping!Learn More

Functions

Decorators

Methods

Comprehensions

Classes

Constructors

Context Managers

Pattern Matching

Generics

Type Declarations

Type Aliases

Type Expressions

Type Qualifiers

Type Narrowing

Variables

Attributes

Properties

Parameters

Error Handling

Annotation Syntax

Conditional Statements

Control Flow Statements

Loops

Imports

Built-In Types

Comments & Documentation

Access Operators

Arithmetic Operators

Assignment Operators

Comparison Operators

Logical Operators

Membership Operators

Identity Operators

Unary Operators

Bitwise Operators

Shift Operators

Python Return Annotation

Syntax and Mechanics

Annotation Variants

​Syntax and Mechanics

​Annotation Variants

Syntax and Mechanics

Annotation Variants