Модули, пакеты, __name__ == '__main__'

Module = .py файл. Package = directory с __init__.py (или namespace package PEP 420). Import — это не copy-paste содержимого; это:

1. Lookup в кэше sys.modules,
2. Поиск файла по sys.path,
3. Execute top-level кода,
4. Cache результат в sys.modules,
5. Bind имя в текущий namespace.

Этот урок раскрывает import machinery и связанные patterns: sys.path lookup order, if __name__ == '__main__': idiom, циклические импорты.

Что такое модуль

Каждый .py файл — module. При первом import f Python выполняет:

1. Проверяет sys.modules — если ключ 'f' уже там, возвращает existing module object (caching). Это значит: повторные import бесплатны.
2. Иначе ищет файл по sys.path — list директорий в порядке поиска.
3. Загружает файл и executes top-level код. При этом создаётся module object — special wrapper над глобальным namespace файла.
4. Записывает в sys.modules — чтобы повторные import’ы попали в cache.
5. Bind name f в текущий namespace вызывающего.

import sys
print(sys.path)             # list of directories search order
print(list(sys.modules.keys())[:10])  # already-loaded modules

Cite: Lib/importlib/_bootstrap.py — Python implementation import machinery; Python/import.c — C portion.

sys.path lookup order

Типичный порядок директорий для поиска:

1. Directory скрипта (script_dir, или '' для interactive shell — текущая директория).
2. PYTHONPATH (env variable, разделена : на Linux/macOS, ; на Windows).
3. Standard library (stdlib Lib/).
4. site-packages (installed via pip / uv / poetry).

import sys
for p in sys.path:
    print(p)

Решение если случилось: python -c "import random; print(random.__file__)" покажет, какой файл загружается. Если ваш — переименовать.

import variants — таблица

Packages — directories с __init__.py

Package — это directory, содержащий __init__.py. Этот файл — точка входа в package; executes при первом import package.

mypackage/
    __init__.py     # executed on `import mypackage`
    core.py
    utils/
        __init__.py
        helpers.py

import mypackage.utils.helpers запускает (по порядку):

1. mypackage/__init__.py
2. mypackage/utils/__init__.py
3. mypackage/utils/helpers.py

Все три module-objects записываются в sys.modules.

__init__.py часто пустой (просто marker, что directory — package). Иногда определяет package-level API:

# mypackage/__init__.py
from .core import main_function, MainClass
from .utils.helpers import helper_function

__all__ = ['main_function', 'MainClass', 'helper_function']
__version__ = '1.0.0'

После этого from mypackage import main_function работает напрямую — клиент не должен знать о внутренней структуре core / utils.

Namespace packages — PEP 420

Python 3.3+: directory без __init__.py тоже может быть package — namespace package. Несколько директорий с одним именем (например в разных PYTHONPATH-entries) merge’ятся в один логический package.

Use case — plugin systems: каждый плагин — отдельная installed package, добавляющая subpackage к общему namespace без conflict’ов.

Differences от regular package:

• Нет __init__.py — нет точки инициализации.
• Может быть «split» across multiple parent directories.
• Implementation detail: regular package содержит __path__ фиксированный; namespace package — _NamespacePath с lazy lookup.

См. PEP 420 — Implicit Namespace Packages.

__name__ == '__main__' idiom

Каждый module имеет специальный атрибут __name__. Значение зависит от того, как module загружается:

• При normal import (import mymodule) — __name__ == 'mymodule'.
• При запуске как script (python myfile.py) — __name__ == '__main__'.

Это позволяет файлу служить и как library, и как script:

# myutil.py
def helper():
    return 42

def main():
    print('Running myutil.py as script')
    print('helper() returned:', helper())

if __name__ == '__main__':
    main()

При import myutil блок if __name__ == '__main__': не исполняется — только определения. При python myutil.py — исполняется main().

Циклические импорты — проблема и обход

A.py импортирует B, B.py импортирует A — circular import. Симптом: ImportError или AttributeError про partially-initialized module.

Корень: при import A Python создаёт пустой module object для A в sys.modules, начинает executing A.py. Если в начале A.py встречает import B, и B.py делает from A import some_function — на этот момент some_function ещё не определена в A (top-level код A не закончил выполнение). Получаем AttributeError.

Решения:

1. Late import — переместить import внутрь функции, где он нужен. Тогда execute его произойдёт позже, когда оба модуля уже initialized.

# В функции вместо top-level:
def my_func():
    from B import b_func   # late import
    return b_func()

2. Restructure — выделить общие части в C, и A, B импортируют из C (no cycle).

3. Type-only imports — для type hints используйте if TYPE_CHECKING: block (PEP 484), который не runtime’ится:

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from B import BClass

def f(b: 'BClass') -> None:   # forward reference как string
    ...

Cross-course context

Cross-course → Spark: 03/07 udfs-introduction — import Python ↔ spark.udf.register("name", func) в PySpark: оба паттерна добавляют именованную функцию в namespace (sys.modules для Python, SparkSession.catalog для Spark). Различие: Python import работает в одном процессе (cache sys.modules локальный); Spark UDF registration сериализует функцию через cloudpickle и пересылает на каждый executor — namespace распределённый.

Ключевые выводы

1. Module = .py; Package = directory с __init__.py (или namespace package PEP 420).
2. import = execute top-level + cache в sys.modules + bind name в caller scope. Повторные imports бесплатны (cache hit).
3. sys.path lookup order: script_dir → PYTHONPATH → stdlib → site-packages. Никогда не shadow’те stdlib именами файлов.
4. if __name__ == '__main__': — каноничный pattern для dual-purpose script/library.
5. Circular imports — решаются late imports, restructuring, или TYPE_CHECKING-block для type hints.