Define stubs for pytypes

[dbarnett]

Could typeshed include stubs for the pytypes library?

Currently if I enable runtime checking with decorators like @pytypes.typechecked I ironically lose static type information for the code and all the types come out to Any.

[JelleZijlstra]

We definitely could! It might be even better though if the library itself bundled stubs or inline type information.

[dbarnett]

Isn't that blocked on PEP 561 though?

[JelleZijlstra]

PEP 561 was accepted years ago.

[dbarnett]

Ah, I found pytypes has Stewori/pytypes#74 tracking this. I can follow up there.

Thanks for helping me get my bearings!

[dbarnett]

Actually, I'm working on bundling the types inside pytypes, but having trouble telling if I'm doing it right. Do you know if there's any sort of developer guide beyond what's in PEP 561? Would you consider posting a pointer to something like that in typeshed's README to help get more libraries bundling their own types and not putting maintenance burden on typeshed?

A couple specific things I'm stuck on:

• If I install a local copy of the library with types correctly defined, should mypy/pytype/pyls pick them up, or do I need to do anything special to make that work, like flush some cache? I'm installing everything into a virtualenv with python setup.py install, but no matter what I do it simply won't pick up the types I've added.
• If I explicitly add stubs in a .pyi file but don't list every type that's in the .py file, will typecheckers still pick up some types from the .py, or will it give "no such attribute" errors for anything I don't explicitly include in the .pyi? Does .pyi "extend" or "replace" the definitions in .py?
• If there are typechecker errors in the .py files and I add the py.typed marker, will that cause any ill effects?

[dbarnett]

Aha, one big piece I was missing is that I'd been banging on all this stuff to fix pytype behavior, but pytype doesn't support PEP 561 at all yet, just typeshed (google/pytype#151). If I focus on mypy then a lot more starts to make sense.

In mypy the .pyi files do "replace" instead of "extending" definitions from .py, so any definitions not omitted from the .pyi will give you "Module has no attribute" errors from mypy.

It seems to fail gracefully if there are type checker issues in the library with bundled types, so IIUC you don't need to have all your code perfect with no typechecker complaints before adding py.typed, just if any type definitions are invalid mypy complains in code that tries to use those bad definitions.

Still, if there's a guide you could create or point to, there's plenty of useful context there that would have been great to learn about upfront.

[srittau]

Unfortunately, the typing documentation is a bit spread out between various PEPs, Python's typing documentation, and mypy's documentation, with a few sprinkles in typeshed's CONTRIBUTING file. I don't know about any comprehensive guide.