typeshed
typeshed copied to clipboard
python
Should `__all__` itself be included?
Our CONTRIBUTING.md guide says that all names in __all__ should be included. But, should __all__ itself be defined?
I've seen that some modules do have __all__ inside. Some - don't.
It is not related to the original source: some modules with __all__ defined in the source code do not have __all__ defined in stubs. Some are very accurate and even include different versions.
As @srittau said in https://github.com/python/typeshed/issues/5569 it looks inconsistent.
Maybe we should:
- [ ] Add a note to
CONTRIBUTING.mdabout adding__all__for newly added stubs? - [x] Start checking
__all__on modified modules to slowly fix all files?
Refs https://github.com/python/typeshed/issues/1287
We already have a recommendation to that effect in the Type Stubs document. At some point, we should redirect to that from CONTRIBUTING, but in the meantime, we could just copy that recommendation.
Related question: What should be done when __all__ is wrong? Specifically when it includes a symbol that can't be imported at runtime / doesn't exist. Should the stub omit those entries as a service to stub users? (and add a stubtest allowlist entry for that __all__)
You should fix it upstream ;-)
Fair, but a decision still has to be taken in the mean time while developping stubs >.<
I think the best is to type-ignore it if stubtest is to flag a difference in __all__. stubtest suppressions are too vague and imo less preferable. And if the fix upstream is to add the missing element, then stubs will already have said element.
Concerning the original question: Doesn't __all__ dictate which elements are imported when doing star-imports? In which case, __all__ should be exactly like the source (absent if absent, present if present) for type-checkers to be accurate. It's also easier to validate with tooling this way.
I think there is consensus that __all__ should be included iff it's included in the implementation. There is also already a recommendation to do so in the type stubs style guide at typing.readthedocs.io, so I think we can close this here.