In this lesson, you will learn how to structure your projects using sub-packages and __init__.py files to create clean, professional, and intuitive API boundaries.
As your project grows beyond a single module, keeping everything in one flat directory becomes messy. By organizing your logic into sub-packages—directories containing related modules—you improve maintainability. The secret to controlling how your users interact with these packages is the __init__.py file.
Controlling the Namespace
When you import a package, Python executes its __init__.py file. You can use this file to "expose" specific classes or functions from deep within your sub-packages, making them appear as if they reside at the top level of your package. This allows you to hide complex internal implementation details (private modules) while providing a clean public interface.
Consider this directory structure:
my_project/
└── src/
└── my_app/
├── __init__.py
├── core/
│ └── engine.py
└── utils/
└── helpers.py
If you want to allow a user to write from my_app import Engine instead of forcing them to write from my_app.core.engine import Engine, you can define that in your top-level __init__.py:
# src/my_app/__init__.py
from .core.engine import Engine
__all__ = ["Engine"]
Why use __init__.py?
- Simplified Imports: Users don't need to know your internal file structure to find your main features.
- Encapsulation: By only importing what you want into
__init__.py, you signal to other developers which parts of your code are intended for public use versus which are private implementation details. - Namespace Flattening: You can group related functions from different modules into one convenient package access point.
By defining an __all__ list within __init__.py, you also explicitly state what gets exported when a user performs a from my_app import *, which prevents accidental pollution of the user's namespace. This approach transforms a collection of loose files into a cohesive, professional library.
Key Takeaway: Use __init__.py to curate your package's public API and simplify imports while keeping your internal implementation neatly organized in sub-packages.