> ## 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 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`.
```python theme={"dark"}
# 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.
```python theme={"dark"}
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.
```python theme={"dark"}
# 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.
```python theme={"dark"}
# 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.
```python theme={"dark"}
# 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`.
Tired of Poor Python Skills? Fix That With Deep Grasping!
Learn More
