Краткий ответ

Для этого модуль может определить специальную функцию __getattr__ на уровне модуля. Python вызывает её только после обычного поиска, если запрошенное имя не найдено среди атрибутов модуля. Функция получает имя атрибута строкой и должна вернуть значение либо выбросить AttributeError.

Исторический контекст

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

В Python 3.7 появился протокол модульного уровня __getattr__ вместе с возможностью настраивать dir() через __dir__. Он решает задачу динамического доступа, сохраняя обычное поведение для уже существующих атрибутов.

Постановка проблемы

Предположим, пакет содержит тяжёлую зависимость или редко используемый объект. Если импортировать всё при загрузке пакета, увеличиваются время старта, расход памяти и вероятность циклических зависимостей.

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

Подробное решение

При обращении к module.name Python сначала проверяет обычные атрибуты модуля. Если имя не найдено, он ищет модульную функцию __getattr__ и вызывает её с аргументом 'name'.

# package/__init__.py

def __getattr__(name):
    if name == 'Client':
        from .client import Client
        return Client
    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')

В этом примере Client импортируется только при первом обращении. Однако результат не кэшируется автоматически: при каждом последующем обращении функция может вызываться снова. Если ленивый импорт дорог или должен возвращать один и тот же объект, функция может записать полученное значение в глобальное пространство имён модуля.

__getattr__ не перехватывает обращения к уже существующим атрибутам. Поэтому он не заменяет обычную проверку и не должен использоваться как универсальный перехватчик каждого доступа.

Для неизвестного имени следует выбрасывать именно AttributeError. Это позволяет корректно работать встроенным операциям проверки атрибутов, hasattr() и инструментам, которые ожидают стандартную семантику отсутствующего атрибута.

Механизм действует для доступа к атрибуту модуля и может участвовать в разрешении имён при импорте из модуля. При этом он не превращает динамически возвращаемое значение в заранее объявленное имя: анализаторы, автодополнение и документация могут не узнать о нём без дополнительных деклараций.

Ситуация из практики

Публичный пакет экспортирует несколько тяжёлых клиентов для разных внешних систем, но большинство пользователей применяет только один из них. Вариант с импортом всех клиентов в __init__.py прост и хорошо виден инструментам, но замедляет каждый импорт пакета и может загружать ненужные зависимости.

Вариант с функцией-фабрикой экономит ресурсы, однако меняет публичный интерфейс: вместо ожидаемого package.Client появляется вызов фабрики, а совместимость с прежним API усложняется.

Выбран ленивый экспорт через модульный __getattr__, дополненный явными аннотациями или документацией публичных имён. Это сохраняет привычный интерфейс и откладывает дорогой импорт. Для часто используемых объектов результат дополнительно кэшируют в пространстве имён модуля, чтобы избежать повторной работы; при этом циклические импорты и потоковую конкуренцию при первом доступе нужно проверять отдельно.

Что кандидаты часто упускают

1. Будет ли __getattr__ вызван для уже существующего атрибута модуля?

Нет. Сначала выполняется обычный поиск атрибута. __getattr__ используется только как запасной механизм после неудачного поиска, поэтому объявленный атрибут имеет приоритет над вычисляемым.

2. Кэшируется ли автоматически результат, возвращённый модульным __getattr__?

Нет. Функция возвращает значение для конкретного обращения, но Python сам не записывает его в модуль. Если значение нужно вычислить один раз, функция должна явно сохранить его, например присвоить импортированный объект глобальному имени модуля. Такое кэширование уменьшает накладные расходы, но требует учитывать частично инициализированное состояние при ошибках или циклических импортах.

3. Почему вместо произвольной ошибки нужно выбрасывать AttributeError для неизвестного имени?

AttributeError является стандартным сигналом отсутствующего атрибута. На нём основаны hasattr() и другие операции, которые отличают отсутствие имени от ошибки внутри вычисления значения. Если __getattr__ выбрасывает, например, KeyError, вызывающий код может неверно интерпретировать ситуацию, а стандартные средства доступа к атрибутам перестанут вести себя ожидаемо.