Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

typing.Never is the bottom type in Python’s static type system. Introduced in Python 3.11 (PEP 673), it represents a type that contains no values. Because it has no instances, a variable or parameter annotated with Never can never be assigned a value at runtime without violating static type constraints. In type theory, a bottom type is the strict subtype of all other types. This means Never is implicitly compatible with int, str, list, or any user-defined class. It is the structural inverse of object, which is the true top type (the strict supertype of all types). This contrasts with typing.Any, which is the dynamic type that bypasses type checking by acting as both a supertype and a subtype to all types to facilitate gradual typing. 
from typing import Never


# Syntactic application in a function signature
def terminate_process() -> Never:
    raise SystemExit(1)


# Syntactic application in variable annotation

# (Static type checkers will flag any assignment to this variable as an error)
impossible_state: Never

​
Exhaustiveness Checking

The primary application of Never in static type analysis is exhaustiveness checking. Using the typing.assert_never() function, developers can statically verify that all possible cases in a match statement or a Union have been handled. assert_never() is typed to accept an argument of type Never. If a type checker determines that a branch of code is reachable (meaning the variable has not been narrowed down to Never), passing that variable to assert_never() will trigger a static type error. 
from typing import assert_never

def process_value(val: int | str) -> None:
    match val:
        case int():
            print("Handling integer")
        case str():
            print("Handling string")
        case _:
            # Static type checkers verify 'val' is narrowed to 'Never' here.
            # If the function signature expands to `int | str | float`, 
            # 'val' would be 'float' here, and assert_never() would flag an error.
            assert_never(val)

​
Relationship with NoReturn

Never and typing.NoReturn are treated as strictly equivalent by static type checkers (such as mypy or pyright). They share the exact same internal semantics. Never was introduced to provide a more mathematically accurate and context-independent name for the bottom type. While NoReturn conceptually implies a function’s return signature (indicating a function that halts execution or loops infinitely), Never is semantically appropriate for any type hint context, including variable annotations, argument types, and generic type parameters.

​
Structural Properties

  • Uninstantiable: There is no valid Python object that satisfies the Never type.
  • Universal Subtype: Because it is the bottom type, a function returning Never can be safely used in contexts expecting a function returning any other type (e.g., Callable[[], int] can accept a Callable[[], Never]).
  • Intersection Identity: In type algebra, the intersection of any type T and Never evaluates to Never.
  • Union Identity: The union of any type T and Never evaluates to T (e.g., Union[int, Never] simplifies to int).
Master Python with Deep Grasping Methodology!Learn More