py.typed precludes adding type stubs to Typeshed

[JonathonReinhart]

TL;DR

As I understand, PR #507 precludes the addition of pyelftools stubs to typeshed.

Problem

The purpose of the py.typed marker is to inform static type checkers that a package containing said file includes type information (in the package), either inline (as part of the .py source) or as stubs (separate .pyi files).

elftools currently does neither of those.

The problem is that adding py.typed to a package that does not provide type information breaks the final step of PEP 561 Type Checker Module Resolution Order (MRO):

4. Packages with a py.typed marker file - if there is nothing overriding the installed package, and it opts into type checking, the types bundled with the package SHOULD be used (be they in .pyi type stub files or inline in .py files).

5. Typeshed (if used) - Provides the stdlib types and several third party libraries.

So the net result (and point of this comment) is: By adding py.typed to this library, mypy will never consult Typeshed -- where I was starting to add stubs: python/typeshed#11262

Forward

As I see it, there are two paths forward. In order of preference (mine, and the Python typing community in general):

1. Keep py.typed, and commit to allowing type information to be added in this repository (preferably inline in the .py source, or secondarily as separate .pyi stubs)

   • Pros: Type information is in the same repo as the implementation, and always in-sync (version-wise).
   • Cons: None really, unless one truly dislikes Python typing

2. Remove py.typed, enabling stubs to be published on Typeshed.

References

• https://peps.python.org/pep-0561/
• https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-library-stubs-or-py-typed-marker
• https://mypy.readthedocs.io/en/stable/running_mypy.html#how-imports-are-found
• https://github.com/python/typeshed/blob/main/CONTRIBUTING.md

cc @fzakaria

[fzakaria]

Why not contribute your PYI files here directly ?
python/typeshed#11262

I contributed the py.typed because nothing existed in typeshed and my linters (mypy or pyright) can infer quite a lot of types themselves without any additional type info.

Unfortunately as you discovered, they refuse to do so unless the py.typed existed.
At the time, it felt like a net-win to me.

[gsingh93]

@JonathonReinhart as mentioned in the last comment, could you create a PR against this repo with your .pyi files?

[pmhahn]

Can be closed once the final PRs from #514 are merged