For this programs types are indeed "useless" at runtime in the sense that they do not modify the behavior of the app/library of the author.

...heh. I get what you are saying. That's the Old World™ view of type hints, right? That's still the most popular conception of type hints. In the Old World™, type hints were only used at runtime when an author explicitly intended those type hints to be used at runtime (e.g., by decorating a callable with @beartype). It was thus reasonable to "optimize away" type hints not intended to be used at runtime via TYPE_CHECKING blocks.

Two modern trends upend that Old World™ mentality. Welcome to the New World™, where the Old World™ sucks and is considered harmful. 😆

Hybrid Runtime-static Type-checking Import Hooks

beartype_all(), beartype_package(), beartype_packages() operate on any arbitrary packages. If your package is one of those packages and if your package has prematurely optimized away type hints via TYPE_CHECKING blocks, your package is now runtime-hostile (i.e., incompatible with those import hooks).

You may not care about this as a package developer, but your users probably do. Do @beartype users care that increasingly many upstream packages are runtime-hostile? They do. They are complaining on the @beartype issue tracker about runtime-hostile packages on a daily basis. I've had to field like twenty gazillion issues over the past two weeks about this exact same topic. I've had to respond by internally blacklisting two popular third-party packages that are runtime-hostile: xarray and Pydantic. Yes, the Pydantic. Let's not ask why a runtime type-checker like Pydantic is itself runtime-hostile.

This is now @beartype's issue. Inappropriate assumptions made by other package developers have made this @beartype's issue without our consent. I sigh! I sigh so hard and then I faceplant onto the bed. 😮‍💨

Python 3.14: PEP 649 Means That Runtime-Hostile Code Will Explode

This is PEP 649:

def muh_func(muh_forward_ref: MuhUndefinedClass): pass
class MuhUndefinedClass(object): pass

See what magic we did there? The muh_func function is annotated by a type that has yet to be defined! The above code raises exceptions under CPython < 3.14 but works under CPython ≥ 3.14. PEP 649 is the dark magic that makes this worky.

PEP 649 is... intense. Basically, PEP 649 means that CPython ≥ 3.14 will now be doing something like what @beartype is currently doing. Specifically, CPython ≥ 3.14 will be dynamically replacing type hints that refer to undefined types with forward reference proxies (i.e., low-level C-based objects that transparently proxy isinstance() and issubclass() calls against undefined types by deferring the dynamic importation of those types to the last possible moment).

Here's where Ruff enters the picture and destroys everything. If a package follows Ruff's insane runtime-hostile advice to prematurely optimize away type hints under CPython ≥ 3.14, what happens? Consider this code snippet lifted directly from the Ruff TCH003 documentation:

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from pathlib import Path


def func(path: Path) -> str:
    return str(path)

Recall that TYPE_CHECKING evaluates to False at runtime. Also note that from __future__ import annotations reduces to a noop under CPython ≥ 3.14. That statement no longer does anything or means anything. So, the above reduces to:

def func(path: Path) -> str:
    return str(path)

Crucially, Ruff's advice has been rendered insane. Do you see? Path is undefined at runtime. Moreover, the package that Path resides in (i.e., pathlib) has been optimized away from runtime introspection. So what happens when somebody tries to introspect the type hints of the above func function by accessing the func.__annotations__ dunder dictionary? Previously, that "just worked." You at least got a string back. It may not have been a usable string – but at least you had a string. You could do something with even an usable string (e.g., log a warning, raise an exception).

Now, however, the following code snippet that previously "worked" explodes horribly under Python ≥ 3.14:

def func(path: Path) -> str:
    return str(path)

print(func.__annotations__['path'])  # <-- this blows up horribly

# This also blows up horribly, even though we're trying *MUCH*
# harder to safely get this type hint with the PEP 649 API.
import inspect
print(inspect.get_annotations(func, format=inspect.FORWARDREF)['path'])  # <-- even this blows up

This isn't CPython 3.14's fault. This isn't PEP 649's fault. This is entirely the fault of third-party static linters like Ruff that have no idea what they're doing. They don't. Ruff developers are not CPython developers. You should believe what CPython developers say and only what CPython developers say. Conversely, you should not believe what Ruff developers say.

Of course, I'm not a CPython developer either. By the above logic, you should ignore everything I say.

^{gods, what am I saying!?!?}