So cool! This is fairly huge for typing. PEP 649 + 749 + 810 doesn't fully resolve all circular imports, of course. But this K-K-Killer Combo should resolve the subset of circular imports that are confined to type hints. Since type hints are lazily resolved under PEP 649 + 749 and since PEP 810 enables module-scoped lazy imports, hints that refer to module-scoped lazy imports now circumvent the need for nonsensical if TYPE_CHECKING: kludges that mypy and pyright spawned.

Indeed, PEP 810 itself notes this obvious advantage:

Type annotations frequently require imports that are never used at runtime. The common workaround is to wrap them in if TYPE_CHECKING: blocks [1]. With lazy imports, annotation-only imports impose no runtime penalty, eliminating the need for such guards and making annotated codebases cleaner.

PEP 810: So Big I Can No Longer See the Sun

PEP 810 is also literally huge. There are seven (!) authors on this beast. Because I am lazy by definition, I've only sped-read the standard. But it looks like @beartype should just implicitly support PEP 810 "out of the box." @beartype shouldn't need to do anything special here to support lazy imports. They just work on all existing @beartype versions. Way to go, PEP 810 authors! How often does that happen? 🤔

Actually, on second thought, @beartype might need to do something explicit here in outlier edge cases like:

from beartype import beartype
from lazy import superfun_lazysun
from types import ModuleType

@beartype
def get_module_superfun_attr(superfun_module: ModuleType) -> object:
    return getattr(superfun_module, 'superfun_attr')

# This should just work. But does it? Probably not. @beartype probably needs to do something here.
print(get_module_superfun_attr(superfun_lazysun))

Specifically, @beartype should define a PEP 810-compliant reducer from types.ModuleType to the union types.ModuleType | types.LazyImportType. Maybe? Hmm... maybe not. It's unknown whether a lazy-imported attribute actually is a valid module until after it's been successfully reified by a call to the types.LazyImportType.resolve() method. If that call raises no exception, it's a module; else, it obviously isn't. Kind of annoying trying to generate type-checking code supporting that. My face is frozen in a rictus of horror.

I suppose what @beartype could do is define a PEP 810-compliant reducer from the simple type types.ModuleType to an insane @beartype-specific custom type with an insane metaclass defining an __instancecheck__() dunder method resembling:

from types import (
    LazyImportType,  # <-- only do this under Python >= 3.15, obviously *sigh*
    ModuleType,
)

class _BeartypeCrazyModuleCheckerMetaclass(type):
    def __instancecheck__(cls: type, obj: object) -> bool:
        if isinstance(obj, ModuleType):
            return True
        elif isinstance(obj, LazyImportType):
            try:
                obj.resolve()
                return True
            except:
                pass
        
        return False

class BeartypeCrazyModuleChecker(object, metaclass=_BeartypeCrazyModuleCheckerMetaclass):
    pass

Let's ignore this until somebody justifiably complains about this. Will I even remember we had this discussion, though!?!? My memory is a guppy fish in motion. 🐠 ^{<-- dumb @leycec so sad}

UPDATE: I just enshrined this as a new feature request. Please, nobody care... please. I'm begging you on a Monday night. 🥺