Description
This has been a frequent discussion topic. We need a simple rule for people to tell if something is meant to be public or part of an internal API.
Right now the contributing guide says:
Code users should be able to import the most relevant functionality from the sub-package's init.py.
I would propose to establish a rule that anything that cannot be imported from a subpackages __init__.py is not considered part of the public API.
This rule is simple.
The one counter argument that I can think of it: There might be pieces that are more special (within in particular subpackage), for example, heavy-ish runtime deps that should not force unconditional imports. If that is the case, it might be worth to:
a) consider moving that code into its own subpackage (if it already has a different dependency set)
b) consider importing within "runtime" code (ie. within a function body)
while otherwise holding on to the general pattern.