stub-package for python modules or extensions?

[szabolcsdombi]

Hi, thank you very much for providing examples for PEP 561

Just for curiosity I have installed this library with

pip install https://github.com/ethanhs/stub-package/archive/refs/heads/master.zip

and found that my VSCode can see the typehints:

despite there is no typedpkg installed.

I am not interested in type hinting packages. I usually make Python extensions or modules with type hints in .pyi stub files.
in this context:

• packages are folders of python code with or without an __init__.py.
• modules are modulename.py files.
• extensions are mymodule.___.pyd or mymodule.___.so files.

This repository is a great example to add stub files for packages, but would it be correct to use it for modules or extensions?

I currently have:

setup(
    name='mymodule',
    ext_modules=[Extension(name='mymodule', ...)],
    data_files=[('.', ['mymodule.pyi'])],
)

This is obviously not correct as '.' is not a package, but it seemed to work and I used it here.

Moving mymodule.pyi to mymodule-stubs/__init__.pyi and changing the setup code to:

setup(
    name='mymodule',
    ext_modules=[Extension(name='mymodule', ...)],
    package_data={'mymodule-stubs': ['__init__.pyi']},
    packages=['mymodule-stubs'],
)

This might be also inappropiate as mymodule is an extension not a package.

[ethanhs]

Hi, PEP 561 doesn't support single module packages, see https://peps.python.org/pep-0561/#packaging-type-information

I would recommend putting a folder of the same name of the module that includes either an __init__.pyi or making a separate -stubs package if you are worried about the folder conflicting with the module. Hopefully that makes sense?

[szabolcsdombi]

This PEP does not support distributing typing information as part of module-only distributions or single-file modules within namespace packages.
The single-file module should be refactored into a package and indicate that the package supports typing as described above.

Indeed I missed this information.

---

I would recommend putting a folder of the same name of the module that includes either an init.pyi or making a separate -stubs package if you are worried about the folder conflicting with the module. Hopefully that makes sense?

Makes sense. The package folder with -stubs ending sounds safer.

This works so far for an extension only distribution.

One thing that still bothers me is the naming. According to pypa/distutils#108 (comment) the folder name shoud contain an underscore while the packages and package_data entries should contain dash.

Is this correct?

[ethanhs]

Henry is incorrect there, see for example mypy's test data for stub packages: https://github.com/python/mypy/tree/master/test-data/packages/typedpkg-stubs

The point of the -stubs prefix is that it is meant only for type-checkers, it shouldn't be importable.

[szabolcsdombi]

Thank you for the clarification!