Package Import

A Python package import is the mechanism by which the Python interpreter resolves, compiles, executes, and binds external directories of modules into the current local namespace. Structurally, a standard Python package is a directory containing a special __init__.py file alongside Python modules (.py files) or nested sub-packages.

When an import statement is executed, Python performs a specific resolution sequence:

1. Cache Check: It inspects the sys.modules dictionary to determine if the package or module has already been loaded. If present, it binds the cached object to the local namespace.
2. Path Resolution: If not cached, Python’s import machinery (Finders and Loaders) searches the directories listed in sys.path (which includes the current directory, PYTHONPATH, standard library paths, and installed site-packages).
3. Initialization: Upon locating the package, Python executes the package’s __init__.py file from top to bottom. This initializes the package’s namespace.
4. Binding: The resulting module object is bound to a variable name in the current scope.

Import Syntax and Namespace Binding

Regardless of the specific import syntax used, Python executes the entire target module and caches the resulting module object in sys.modules (memory). The import syntax strictly dictates which identifiers are bound to the local namespace, not what is loaded into memory.

Absolute Imports Absolute imports specify the full path to the module or attribute starting from any top-level directory listed in sys.path.

# Binds the top-level package to the local namespace.

# Submodules are NOT accessible as attributes unless explicitly imported or defined in __init__.py.
import package


# Executes the submodule, caches it in sys.modules, and binds the top-level package locally.

# The submodule must be accessed via package.submodule.
import package.submodule


# Binds only the submodule to the local namespace. 

# The top-level package is loaded into sys.modules but not bound locally.
from package import submodule


# Binds a specific class, function, or variable directly to the local namespace.
from package.submodule import TargetClass

Aliasing The as keyword modifies the binding step, assigning the resolved module object to a custom identifier in the local namespace to prevent name collisions.

import package.submodule as custom_name
from package.submodule import TargetClass as TC

Relative Imports Relative imports use dot notation to specify location relative to the current module’s position in the package hierarchy. They are strictly evaluated based on the __name__ attribute of the current module and cannot be used in top-level scripts executed directly.

# Imports a module from the same directory (current package)
from . import sibling_module


# Imports an attribute from a module in the same directory
from .sibling_module import TargetClass


# Imports from the parent package
from .. import parent_module


# Imports from a sibling package (up one level, then down into sibling)
from ..sibling_package import module

The Role of __init__.py

The __init__.py file serves as the entry point for the package. When a package or any of its modules is imported for the first time, __init__.py is executed. It is commonly used to lift attributes from submodules into the package’s root namespace, abstracting the internal directory structure.

# Inside package/__init__.py
from .submodule_a import CoreClass
from .submodule_b import helper_function

The __all__ Attribute

Within __init__.py (or any module), the __all__ attribute is a sequence of strings (typically a list or tuple) defining the public API of that package. It strictly controls namespace binding when the wildcard import syntax (from package import *) is utilized.

# Inside package/__init__.py
__all__ = ('CoreClass', 'helper_function')

from .submodule_a import CoreClass
from .submodule_b import helper_function
from .submodule_c import internal_function # Will not be exported via wildcard

Namespace Packages (PEP 420)

Python 3.3+ supports implicit namespace packages, which allow a single Python package to be split across multiple directories on disk without requiring an __init__.py file. During the resolution phase, if Python finds directories matching the package name but no __init__.py, it creates a namespace package object, dynamically merging the contents of all matching directories found in sys.path.

Master Python with Deep Grasping Methodology!

Learn More