Should __all__ itself be included?

[sobolevn]

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 #5569 it looks inconsistent.

Maybe we should:

• Add a note to CONTRIBUTING.md about adding __all__ for newly added stubs?
• Start checking __all__ on modified modules to slowly fix all files?

Refs #1287

[srittau]

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.

[Avasam]

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__)

[hauntsaninja]

You should fix it upstream ;-)

[Avasam]

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.

[srittau]

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.