Feature: support type stubs?

[tlambert03]

As mentioned in #75 (comment), one benefit of static API analysis is the ability to pick up stuff like @typing.overload-decorated functions, and other stuff that doesn't make it into a runtime representation.

This got me thinking: would it be within scope to support type stub / .pyi files?

as an example, consider this terrible, awful, very bad module:

# mymodule.py
globals()['f'] = lambda x: str(x)

Yes, this is a silly thing to do, but there are some cases where meta-programming is particularly powerful in python, so it's not out of the realm of "reasonable" possibilities to inject names into a namespace dynamically. If I'm ever tempted to do something like that, I'd always provide a type stub:

# mymodule.pyi
def f(x: int) -> str: ...

currently, griffe would find nothing:

from griffe import load
mod = load('mymodule')
print(mod.members)  # {}

... but perhaps it could also look for type stubs to find that info? Whether a type stub should simply override an actual py module, or whether there should be some attempt to merge is another question. (I'd tend to simply override if present, as type checkers seem to do)

[pawamoy]

It's already supported! But maybe I forgot to support the case where the name passed to load_module is found as a file and not a folder.

[tlambert03]

Excellent! Sorry I missed that 😂

[tlambert03]

Found one more case where stubs are being missed:

my_package/
├── __init__.py
└── __init__.pyi

The top level __init__.pyi is never getting merged. Fix submitted in #78