feat: add attach_stub function to load imports from type stubs

[tlambert03]

following on the discussion at scientific-python/specs#139, here is an implementation that loads imports from type stubs for your consideration

[stefanv]

I like it! Does this then address all type checker concerns, or are there other outstanding ones?

I'd love for @jni and @tupui to cast an eye over this PR and share their impressions.

[tlambert03]

Does this then address all type checker concerns, or are there other outstanding ones?

I think this does it. With the pyi file being the source of truth, it’s sort of a “type checking first” approach, that also works at runtime. Really I think the only downside here is that note I included about making sure the stub gets included in the wheel/sdist. I can imagine someone missing that note in the readme, having it work locally, then shipping an unimportable package (lacking the stubs)

[stefanv]

Thanks very much for this @tlambert03. I'm going to merge for now, since @jni liked the implementation in scientific-python/specs#139 (comment)

It would be the cherry on top if you could also update the high level description of https://github.com/scientific-python/specs/blob/main/spec-0001/index.md (feel free to add yourself as co-author there).