> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Python Module Import
A Python module import is the mechanism that locates, initializes, and binds external Python code (modules or packages) into the current namespace. When an import statement is executed, Python resolves the target module, executes its top-level code to populate its namespace, and creates a reference to that module or its specific attributes in the importing scope.
## The Import Resolution Process
When an `import` statement is invoked, the Python interpreter executes a strict sequence of operations governed by the import system's finder and loader protocol:
1. **Cache Lookup (`sys.modules`):** Python first inspects `sys.modules`, a dictionary caching all previously imported modules. If the module exists here, Python immediately binds the cached module object to the local namespace, bypassing the rest of the process. A critical detail regarding circular imports is that a module is added to `sys.modules` *before* its top-level code finishes executing. Consequently, the cached module object returned during a circular import may be partially initialized.
2. **Meta Path Finders (`sys.meta_path`):** If the module is not cached, Python delegates the search to a list of finder objects defined in `sys.meta_path`. Python iterates through these finders until one successfully locates the module. The standard finders include:
* `BuiltinImporter`: Checks if the requested name corresponds to a built-in module compiled directly into the Python interpreter (e.g., `sys`, `time`).
* `FrozenImporter`: Checks for frozen modules.
* `PathFinder`: Searches for the module's file (e.g., `.py`, `.pyc`, or compiled C extensions) across the directory locations listed in `sys.path`.
3. **Loading and Execution:** Once a finder locates the module, it returns a `ModuleSpec` object containing a loader. Under the modern import system (PEP 451, introduced in Python 3.4), the import machinery itself creates the empty module object and registers it in `sys.modules`. Only after registration does the import machinery call the loader's `exec_module()` method to compile (if necessary) and execute the module's top-level code in an isolated namespace, initializing its attributes, functions, and classes.
4. **Namespace Binding:** Finally, Python binds the resulting module object, or specific requested attributes, to variables in the local scope where the `import` statement was called.
## Import Syntax and Namespace Binding
The syntax used dictates exactly what is bound to the local namespace.
**Standard Import**
Binds the entire module object to the local namespace under its original name. Accessing its contents requires fully qualified dot notation.
```python theme={"dark"}
import module_name
```
**Aliased Import**
Binds the module object to the local namespace under a specified alternate identifier.
```python theme={"dark"}
import module_name as alias
```
**Specific Attribute Import**
Extracts specific attributes (functions, classes, or variables) from the module and binds them directly to the local namespace. The module object itself is not bound to the local scope, though it is still loaded into `sys.modules`.
```python theme={"dark"}
from module_name import attribute_name, other_attribute
```
**Aliased Attribute Import**
Binds a specific imported attribute to an alternate identifier in the local namespace.
```python theme={"dark"}
from module_name import attribute_name as alias
```
**Wildcard Import**
Binds all public names defined in the target module to the local namespace. Public names are determined by the module's `__all__` list; if `__all__` is undefined, it binds all names that do not begin with an underscore (`_`).
In Python 3, wildcard imports are strictly restricted to the module level. Attempting to execute a wildcard import inside a function or class definition will raise a `SyntaxError`.
```python theme={"dark"}
from module_name import *
```
## Absolute vs. Relative Imports
Imports can be categorized by how they resolve the module location relative to the current package structure.
**Absolute Imports**
Specify the fully qualified module name or absolute package hierarchy. Absolute imports are resolved using the finders in `sys.meta_path`. This means they are first checked against `BuiltinImporter` and `FrozenImporter`—resolving built-in and frozen modules entirely independently of `sys.path`—before falling back to `PathFinder`, which searches the directory locations listed in `sys.path`.
```python theme={"dark"}
from package.subpackage import module
```
**Relative Imports**
Use dot notation to specify the module's location relative to the current module's position in the package hierarchy. These can only be used within packages (using `from . import ...` syntax). Since Python 3.4 (PEP 451), the import system relies primarily on the `__spec__.parent` attribute to resolve relative imports. The older `__package__` attribute is deprecated for this purpose and raises an `ImportWarning` in Python 3.10+ if it differs from the spec.
```python theme={"dark"}
# Import from the current directory
from . import module
# Import from the parent directory
from .. import module
# Import from a sibling package
from ..sibling_package import module
```
## Programmatic Importing
Under the hood, the `import` keyword invokes the built-in `__import__()` function. For dynamic imports where the module name is evaluated at runtime as a string, Python provides the `importlib` standard library, which exposes the internal import mechanics.
```python theme={"dark"}
import importlib
# Dynamically load a module by its string name
dynamic_module = importlib.import_module("module_name")
```
Tired of Poor Python Skills? Fix That With Deep Grasping!
Learn More
