Файл __init__.py: ключ к правильной организации пакетов Python

Расширенные примеры работы с __init__.py

Ниже приведены нестандартные сценарии использования файла инициализации пакета.

Автоматический импорт всех модулей из пакета

# utils/__init__.py
import os
import importlib

modules = {}
for entry in os.listdir(os.path.dirname(__file__)):
    if entry.endswith('.py') and not entry.startswith('_'):
        mod_name = entry[:-3]
        mod = importlib.import_module(f'.{mod_name}', package=__name__)
        modules[mod_name] = mod

# теперь все функции из модулей доступны через utils.modules['math_ops']
print(modules.keys())

dict_keys(['math_ops', 'string_ops', 'date_ops'])

Этот подход позволяет не обновлять __init__.py при добавлении новых модулей. Однако он загружает все модули даже если они не нужны - возможны проблемы с производительностью.

Динамическое определение __all__ по содержимому пакета

# my_package/__init__.py
import pkgutil
import importlib

__all__ = []
for importer, modname, ispkg in pkgutil.iter_modules(__path__):
    if not ispkg and not modname.startswith('_'):
        __all__.append(modname)
        # опционально импортируем модуль на верхний уровень
        globals()[modname] = importlib.import_module(f'.{modname}', package=__name__)

print('Автоматически экспортируемые модули:', __all__)

Автоматически экспортируемые модули: ['core', 'helpers', 'validators']

Плюс: не нужно вручную перечислять модули. Минус: замедление импорта из-за обхода всех модулей.

Инициализация конфигурации с версионированием

# package/__init__.py
__version__ = '2.1.0'
__author__ = 'Python Developer'

import os
_config = {}

def load_config(config_path=None):
    import json
    if config_path is None:
        config_path = os.path.join(os.path.dirname(__file__), 'config.json')
    with open(config_path) as f:
        _config.update(json.load(f))

load_config()  # выполняется при первом импорте

def get_config(key, default=None):
    return _config.get(key, default)

# Использование
import package
print(package.__version__)  # '2.1.0'
print(package.get_config('database_url'))  # значение из config.json

Проблема: если config.json отсутствует, импорт пакета упадёт с ошибкой. Решение - обрабатывать исключения внутри load_config().

Ленивая инициализация тяжёлых ресурсов

# package/__init__.py
_heavy_resource = None

def get_heavy_resource():
    global _heavy_resource
    if _heavy_resource is None:
        # эмуляция долгой загрузки
        import time; time.sleep(5)
        _heavy_resource = {'big_data': list(range(10**6))}
    return _heavy_resource

import package
print('Пакет импортирован быстро')
data = package.get_heavy_resource()  # здесь происходит реальная загрузка

Теперь импорт пакета не блокирует программу, ресурсы загружаются только по необходимости.

Проверка зависимостей при импорте

# package/__init__.py
_required = ['numpy', 'pandas', 'requests']
_missing = []
for lib in _required:
    try:
        __import__(lib)
    except ImportError:
        _missing.append(lib)

if _missing:
    raise ImportError(f'Отсутствуют необходимые библиотеки: {", ".join(_missing)}')

ImportError: Отсутствуют необходимые библиотеки: pandas

Такой подход гарантирует, что пользователь сразу узнает о недостающих зависимостях, но делает пакет «хрупким» - импорт может прерваться. Альтернатива - выдавать предупреждение, а не ошибку.

Использование __init__.py для настройки логирования на уровне пакета

# logging_package/__init__.py
import logging

# Создаём логгер для пакета
logger = logging.getLogger(__name__)
handler = logging.StreamHandler()
formatter = logging.Formatter('%(name)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)

# Отключаем вспомогательное логирование из библиотек
logging.getLogger('requests').setLevel(logging.WARNING)

from logging_package import logger
logger.info('Пакет настроен')

logging_package - INFO - Пакет настроен

Это удобно для больших проектов, где каждый пакет имеет свой логгер с отдельными настройками.

Переопределение импортированных имён для обратной совместимости

# old_package/__init__.py
from . import new_module as core  # для совместимости со старым кодом, который использовал old_package.core
# или
import old_package.new_module as core

# Старый код
import old_package
old_package.core.some_func()  # работает, хотя модуль переименован

Проблема: усложняет понимание, какой именно модуль используется. Решение - задокументировать алиасы и планировать их удаление.

Создание фасада для сложной иерархии подпакетов

# facade_package/__init__.py
from .sub_package_a import class_a
from .sub_package_b import class_b
from .sub_package_c.helpers import utility

# Также можно добавить собственные функции
class Facade:
    def __init__(self):
        self.a = class_a()
        self.b = class_b()

    def compute(self):
        return utility() + self.a.value + self.b.value

from facade_package import Facade
f = Facade()
print(f.compute())

Это скрывает внутреннюю структуру пакета и предоставляет простой интерфейс.