python
Clarify the method of distribution for stub files with extension only packages.
PEP-0561 does not mention extension packages, packages that consist of just an .so file. Given that PEP-484 mentions extension modules as a use case for stub files, could the typing documentation make it more clear what the ideal layout of an extension only package is? It appears to be valid to have a package structure like the following:
.../site-packages/
mypackage/
__init__.pyi
py.typed
mypackage.cpython-37m-x86_64-linux-gnu.so
@ethanhs suggested in https://github.com/python/peps/issues/2318 that this is the correct way of doing things.
That looks sensible. These days it's the rare package that is just a single .so file though... :-)
If it's a rare enough case that the recommendation should be to package it more like a multi-file package then that seems reasonable to me too. PEP-561 does allude to this when it says:
The single-file module should be refactored into a package and indicate that the package supports typing as described above.
It wasn't clear to me if this applied to single .so file projects as well. But a single .so is a single-file module so I suppose it does. I'd be happy with either approach.
To clarify, this multi-file approach would look like the following:
.../site-packages/
mypackage/
__init__.py # Contains `from ._mypackage import *`
py.typed
_mypackage.cpython-37m-x86_64-linux-gnu.so
_mypackage.pyi
I'll add one detail to the package structure. A single-file extension module can contain submodules. (For example, pybind11 and nanobind have helper functions def_submodule to easily create submodules.) So in general, we can have multiple pyi files corresponding to one .so:
.../site-packages/
mypackage/
__init__.pyi
submodule1.pyi
submodule2/
__init__.pyi
nested.pyi
py.typed
mypackage.cpython-37m-x86_64-linux-gnu.so
