Python packages allow you to organize modules into structured directories. A package is simply a folder that contains a group of related module files. Packages help manage large projects by grouping related functionality together.
Packages allow developers to build hierarchical module structures using dotted names such as:
sound.effects.echo
sound.effects.surround
This makes large projects easy to maintain and navigate.
Packages are useful because they:
A package works like a library where books (modules) are stored on clearly labeled shelves (directories).
A package is simply a directory containing a special file named __init__.py.
This file tells Python that the directory should be treated as a package.
Example package structure:
sound/ # Top-level package
__init__.py
formats/ # Subpackage for format conversions
__init__.py
wavread.py
aiffread.py
effects/ # Subpackage for effects
__init__.py
echo.py
surround.py
filters/ # Subpackage for filters
__init__.py
equalizer.py
__init__.py can be an empty file, or it can contain initialization code for the package.
This imports the complete path of the module.
import sound.effects.echo
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
Here the entire path must be used when calling the function.
This imports only the module inside the package.
from sound.effects import echo
echo.echofilter(input, output, delay=0.7, atten=4)
This imports only the echo module from inside the effects package.
This imports only the desired function.
from sound.effects.echo import echofilter
echofilter(input, output, delay=0.7, atten=4)
This makes the function available directly.
When using:
from sound.effects import echo
Python checks:
Correct imports:
import sound.effects.echo
from sound.effects import echo
from sound.effects.echo import echofilter
Incorrect:
import sound.effects.echo.echofilter # invalid
The file __init__.py:
Example:
__init__.py inside sound/effects:
__all__ = ["echo", "surround", "reverse"]
This ensures only the listed modules are imported when using:
from sound.effects import *
When using:
from sound.effects import *
Python will import only the module names defined in __all__ inside __init__.py.
Example __init__.py:
__all__ = ["echo", "surround", "reverse"]
This prevents unwanted modules from being imported by default.
Note: Avoid using * in large projects to maintain clarity.
Modules inside a package can import each other.
from sound.effects import echo
Inside sound/effects/surround.py:
from . import echo # import from same package
from .. import formats # import from parent package
from ..filters import equalizer
Relative imports:
Note: Relative imports do not work when running a module directly as a script.
Python allows a package to be split across multiple directories by modifying its __path__ attribute.
Example:
import sound
sound.__path__.append("/additional/path/sound")
After this, Python searches for modules in both directories.
This is useful for:
Python packages provide a structured way to group modules and manage large projects.
With features like hierarchical imports, __init__.py, relative imports, and package path extension, packages offer flexibility and scalability.
Packages are widely used in:
They are essential for organizing and maintaining complex Python codebases.
