Packages with only __init__.py - Possible issues?

Question

Considering a Python Project structure such as the following, where there are "empty" packages with __init__ files simply pulling code from the lib folder:

.
├── foo
│   ├── fred
│   │   └── __init__.py
│   ├── henk
│   │   └── __init__.py
│   ├── _lib
│   │   ├── classes
│   │   │   ├── corge.py
│   │   │   ├── _stuff.py
│   │   │   └── thud.py
│   │   └── utils
│   │       ├── bar.py
│   │       └── _stuff.py
│   └── __init__.py
└── script.py

---

# foo/__init__.py:
from foo import henk, fred

# foo/fred/__init__.py:
from foo._lib.classes.corge import Corge

# foo/_lib/classes/corge.py:
from foo._lib.classes._stuff import *
class Corge():
    pass

---

The reason for this is, while a bit unorthodox looking, it seems to help with code autocompletion. Irrelevant/internal modules from a package don't show up in tools tips, like such in Spyder IDE:

For context, I didn't want _stuff or thud showing up at that level; this file structure achieved this.

---

It's been working so far, and so I've been wondering if there are any potential side effects since I've never seen this structure before? Could this be unfriendly to contributing developers or their tools?

Any other ways to achieve a similar goal (not clutter namespace for users) would be very welcome.

Answer 1

Yes, this is sensible. And no, this is not the correct way to do things.

The pattern where you have a top-level module that re-exports symbols from private modules is somewhat common for larger projects. However, the main selling point for these modules is that your public API is defined in a single place, not that this would help to hide implementation details.

To control which symbols are intended to be accessed from outside a module, the following techniques are used instead:

• If something should be internal, give it a name that starts with a leading underscore. Python has no C-like reserved names that could interfere here.
• To control which symbols are exported by default, assign their names to the __all__ list. Technically this is just the default export list that is used for from module import *.
• To some degree, you can del variables that are no longer required. However, this requires a precise understanding of what is evaluated when.