Python `typing.cast` method vs colon type hints

Question

What the difference between using the Python typing.cast method

x = cast(str, x)

compared with using type hints/colon notation/left hand side type annotation?

x: str

I've seen the use of the cast method in codebases but don't have an apparent reason to use it instead of type hint notation, which is more concise.

Answer 1

I will answer you through a well-written example:

def get_name(can_return_name: bool) -> str | None:
    in_name = input('Enter your name: ')
    return in_name if can_return_name else None

def do_something_with_name() -> None:
    name: str = get_name(True)
    print(name.capitalize())

Here, you'd expect Pyright or mypy to say that name's type is str, even if the return type of get_name is str | None, but this is not the case:

if the function you are calling (in this case get_name) has a return type, the column notation type will be ignored completely, and Pyright will tell you that you can't call .capitalize on a name, as it could be None

In this case though, you are completely sure that name will be str and not None, so you can use cast, like such:

def do_something_with_name() -> None:
    name: str = cast(str, get_name(True))
    print(name.capitalize())

get_name's value will be unchanged, but static type checkers will treat them as the first argument's type.

in fact, as python's documentation states, the cast function does in fact nothing at all.

It can be defined with the new Python 3.12 generics as such (will be valid when PEP 718 will be accepted, thanks to @InSync):

def cast[T](var: object) -> T:
    return var

cast[str](get_name(True))