Какова цель файла `__init__.py` в Python и как он определяет структуру пакета?

Назначение __init__.py

Файл __init__.py отмечает директорию как пакет Python, делая её импортируемой как модуль. Без него (в старых версиях Python) директория рассматривается как обычная папка и не может быть импортирована.

Что он может содержать

Файл может быть:

• Пустым — просто сигнализирует, что директория является пакетом
• Заполненным инициализационным кодом — выполняется автоматически при импорте пакета
• Использован для экспорта публичного API путём явного импорта подмодулей или объектов

Например, вместо того чтобы писать:

Ты можешь упростить импорты, добавив в __init__.py:

Это позволяет пользователям писать:

Пример структуры пакета

Namespace-пакеты в Python 3.3+

В Python 3.3 и позже __init__.py больше не является строго обязательным. Директории без него рассматриваются как namespace-пакеты, которые позволяют одному пакету охватывать несколько директорий или установок.

Ключевые отличия:

• Обычные пакеты — требуют __init__.py, поддерживают инициализационный код
• Namespace-пакеты — __init__.py не нужен, используются для распределённых или разделённых пакетов

Главный вывод

Используй __init__.py, когда тебе нужна явная инициализация пакета или ты хочешь контролировать публичный API. Опускай его только если ты намеренно создаёшь namespace-пакет.