Type stubs for single-file top-level modules
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.8k
- Forks
- 302
- Avg merge
- 23h
- Merged PRs (30d)
- 8
Description
PEP 561 currently states the following:
Package maintainers who wish to support type checking of their code MUST add a marker file named
py.typedto their package supporting typing.
I consider this requirement to be problematic for Python libraries that are written in another programing language and distributed as compiled .so files. PEP 561 currently does not provide a way to mark .so files residing directly in site-packages/ to be typed, resulting in typed shared libraries needing to introduce an intermediary __init__.py file such as the following:
from ._native import *
__doc__ = _native.__doc__
if hasattr(_native, "__all__"):
__all__ = _native.__all__
While this works for static type checkers I think this is obviously suboptimal because it has several undesired side-effects. Let's take the following as an example:
site-packages
├── my_project
│ ├── __init__.py
│ ├── _native.cpython-36m-x86_64-linux-gnu.so
│ └── py.typed
The unintended side-effects are:
- You can import
my_project._native. _nativeshows up in the documentation generated by pydoc. E.g. under PACKAGE CONTENTS for the documentation ofmy_projectand invoking e.g.help(my_project.foobar)will tell you thatfoobarresides in the modulemy_project._native.my_project.__file__now is the__init__.pyfile instead of the.sofile, potentially misleading developers into thinking the package is implemented in Python
So I really think PEP 561 should be amended to provide some way of marking single-file packages as "typed" without having to resort to hacks such as defining an intermediary __init__.py since that introduces a bunch of undesired side-effects that have the potential to confuse API users.
What do you think about this?
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading PEP 561 and the issue's examples of single-file compiled modules, then compare the stated behavior with how pydoc reports package contents and file. Done means proposing and documenting an accepted way to mark directly installed .so modules as typed without the intermediary init.py side effects.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100