.PY File Format – Modules and packages

The import statement

import_stmt:
    ["lazy"] "import" module ["as" identifier] ("," module ["as" identifier])*
  | ["lazy"] "from" relative_module "import" identifier ["as" identifier]
        ("," identifier ["as" identifier])*
  | ["lazy"] "from" relative_module "import" "(" identifier ["as" identifier]
        ("," identifier ["as" identifier])* [","] ")"
  | "from" relative_module "import" "*"
module:          (identifier ".")* identifier
relative_module: "."* module | "."+

Importing a submodule imports each parent first, so import a.b.c runs a, then a.b, then a.b.c. The submodule is then set as an attribute of its parent.

A name imported with from a import x is a new binding to the object, so later rebinding of a.x is not seen.

How modules are found

The import system works in two steps: it finds the module and loads it (5.3, 5.4).

1. sys.modules, the cache of everything imported, is checked first. A module there is used at once. A value of None raises ModuleNotFoundError.
2. Each finder on sys.meta_path is asked for a module spec. By default the finders handle built-in modules, frozen modules, and the path-based finder, in that order. If none finds it, ModuleNotFoundError is raised.
3. The spec's loader creates the module, adds it to sys.modules, and executes it. Adding it first means a circular import receives the partly initialised module instead of recursing. If execution fails, the module is removed again.

The path-based finder searches the entries of sys.path, or a package's __path__. Within each directory, extension modules are tried first, then source, then bytecode, and a package directory comes before any of them.

sys.path is built from the program's directory (see Running a file), the PYTHONPATH variable, the standard library, and site-packages, which holds installed packages. sys.path is an ordinary list and can be changed at run time.

Compiled bytecode is cached as described under How a file becomes a .pyc. Custom finders can be added through sys.meta_path and sys.path_hooks (5.3.3). importlib.reload(m) runs a module again in its existing module object.

Packages

A package is any module with a __path__ attribute (5.2).

parent/
    __init__.py
    one/
        __init__.py
        spam.py
    two/
        __init__.py
    three.py

# in package/subpackage1/moduleX.py

from .moduleY import spam            # package.subpackage1.moduleY
from . import moduleY
from ..subpackage1 import moduleY    # package.subpackage1, reached from its parent
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo

__all__ and public names

from module import * imports the names listed in the module's __all__, a sequence of strings. Every name listed must exist. Without __all__, it imports every name that does not start with an underscore (7.11).

__all__ = ["read", "write"]

def read(): ...
def write(): ...
def helper(): ...       # not imported by *

A package's __all__ decides which submodules from package import * imports, since Python does not scan the directory. A leading underscore is a convention only: from m import _name still works. A module can also define __getattr__ to compute attributes on demand.

Lazy imports

Since Python 3.15, an import can be lazy (7.11.1, PEP 810). The name is bound to a proxy, and the module is loaded on the first use of the name.

lazy import json
lazy from pathlib import Path

import sys
print("json" in sys.modules)     # False
json.dumps({})                   # loads json now
print("json" in sys.modules)     # True

• Lazy imports are allowed only at module scope. Inside a function, class body or try statement, lazy is a SyntaxError.
• lazy from module import * and future statements cannot be lazy.
• Import errors appear at the first use, not at the statement.
• __lazy_modules__, a module-level container of full module names, makes ordinary module-scope imports of those modules lazy (7.11.1.1).

Future statements

from __future__ import feature enables a feature in the module before it becomes the default (7.11.2, PEP 236). It is a directive to the compiler. It must come before all other code, apart from the docstring, comments, blank lines and other future statements.

Only annotations still has an effect, which is described on Type hints. The others are accepted and do nothing.