How to bring docstrings into package scope with import * in __init__.py?

Question

I have a Python package in which the implementation is split (for maintainability) into two internal submodules. From the user point of view the package should appear as one unit, though, so in the package's __init__.py both submodules are imported with import *, as follows:

# filesystem layout:
mypkg/
    __init__.py
    subA.py # defines class A
    subB.py # defines class B

and

# __init__.py
from .subA import *
from .subB import *

This works as intended from the package functionality point of view:

>>> import mypkg
>>> a = mypkg.A() # works
>>> b = mypkg.B() # works

and if looking up inline help for these classes directly, everything is also good:

>>> help(mypkg.A) # works
>>> help(mypkg.subA.A) # also works

The problem is that if I just look up the help for the top-level package, cf.

>>> help(mypkg)

then the classes and functions from the submodules do not "voluntarily" appear at all (although variables from them do appear in the DATA section). Is this expected/correct behaviour, and is there a way to bypass it so that the users do not have to know about the submodules that exist for implementation/maintenance convenience only?

Answer 1

The best solution I know of is just to add the relevant documented objects (classes, functions, data) to __all__ in your __init__.py.