Course contentsShow
← Python
Lesson 514 of 1,0608. Professional Tooling and PackagingFree lesson

Organizing Packages and Modules

You will learn to group related functionality into sub-packages and utilize __init__.py files to control package exports and namespace visibility.

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?

  1. Simplified Imports: Users don't need to know your internal file structure to find your main features.
  2. 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.
  3. 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.