Is it possible to have type hints in a separate folder within the same project?

Question

I'm adding type annotations to a package I maintain. According to PEP484 stub files for type annotation (.pyi) can either be distributed alongside the actual code in the same directory or in a third-party package. Having the .pyi files in the same directory, however, seems inelegant and I would much prefer to have them separated; similar to how this is done for headers and implementations in C/C++.

In a nutshell, my current package structure is something like this:

my_project
|   setup.py
|   pyproject.toml
|   ...
|
|___my_package
|   |   __init__.py
|   |___module_1
|   |   |   __init.py
|   |   |   fancy_module.py
|   |   |   fancy_module.pyi
|   |   |   ...
|   |
|   |___module_2
|   |   |   __init__.py
|   |   |   more_files.py
|   |   |   more_files.pyi
|   |   |   ...

and I would like it to be something like this (with type annotations supported by mypy and vscode at least):

my_project
|   setup.py
|   pyproject.toml
|   ...
|
|___my_package
|   |   __init__.py
|   |
|   |___module_1
|   |   |   __init.py
|   |   |   fancy_module.py
|   |   |   ...
|   |
|   |___module_2
|   |   |   __init__.py
|   |   |   more_files.py
|   |   |   ...
|
|___stubs
|   |___module1
|   |   |   fancy_module.pyi
|   |   |   ...
|   |
|   |___module2
|   |   |   more_files.pyi
|   |   |   ...
  

Is this possible or do I need to look into distributing a separate "third-party" package?

Answer 1

I think yes you can do this, just create a "stubs" directory at the root level of your project and place the .pyi files inside it! if you want to sure that mypy and other tools recognize these separate stub files, you can configure them to include the "stubs" directory in their search paths!

but if you prefer third-party package,first of all create a new package for the stub files,for example my_package-stubs, then organize the stub files in the third-party package based on the structure of your main package, something like this :

my_package-stubs
|___my_package
|   |___module_1
|   |   |   fancy_module.pyi
|   |   |   ...
|   |
|   |___module_2
|   |   |   more_files.pyi
|   |   |   ...

now, include my_package-stubs as a dependency in your main package's pyproject.toml orsetup.py, and by doing this, when users install your main package,the stub files from the third-party package will be installed alongside it.

pyproject.toml

[build-system]
requires = [
    "my_package-stubs",
    ...
]

setup.py

setup(
    ...
    install_requires=[
        'my_package-stubs',
        ...
    ],
    ...
)