Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Clarify the method of distribution for stub files with extension only packages. #1061

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AWhetter opened this issue Feb 10, 2022 · 3 comments
Labels
topic: documentation Documentation-related issues and PRs

Comments

@AWhetter
Copy link

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 python/peps#2318 that this is the correct way of doing things.

@AWhetter AWhetter added the topic: documentation Documentation-related issues and PRs label Feb 10, 2022
@gvanrossum
Copy link
Member

That looks sensible. These days it's the rare package that is just a single .so file though... :-)

@AWhetter
Copy link
Author

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

@wojdyr
Copy link

wojdyr commented Dec 29, 2023

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
topic: documentation Documentation-related issues and PRs
Projects
None yet
Development

No branches or pull requests

3 participants