Python: полный мануал с примерами и справочником функций

Глава 13 · средний

Модули, пакеты и зависимости

Разделите расчёт и запуск, соберите пакет и поймите, откуда берутся импортированные имена.

Расчёт отдельно, запуск отдельно

Когда одна программа используется и в терминале, и в другом скрипте, полезно отделить расчёт от ввода и вывода. В примере учебный файл manual_prices.py содержит только функцию. Запускаемый скрипт импортирует её и печатает результат. Оба файла сохраняются в одной папке. Функция не спрашивает данные через input и не записывает отчёт: поэтому её можно независимо проверить, вызвать из интерфейса и повторно использовать для другой формы представления.

Файл модуля manual_prices.py:

def total(prices):
    return sum(prices)

from manual_prices import total

print("Итого:", total([120, 80, 50]))
print("Пустой заказ:", total([]))

Итого: 250
Пустой заказ: 0

import manual_prices связывает имя модуля, и вызов выглядит как manual_prices.total(...). Вариант from manual_prices import total связывает выбранное имя непосредственно. Псевдоним через as помогает избежать конфликта, но не создаёт другую копию модуля. Избегайте from module import *: читателю сложнее понять происхождение имён, а обновление библиотеки может неожиданно изменить пространство имён. Начинайте с явных импортов стандартной библиотеки и своего проекта.

Почему импорт не должен запускать весь сценарий

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

У запускаемого файла имя __name__ равно "__main__". У импортированного модуля это его импортное имя. Условие if __name__ == "__main__": отделяет запуск сценария от доступных определений. Оно не отменяет остальной верхнеуровневый код, поэтому побочные действия всё равно стоит собрать в main(). Проверка особенно важна для процессов, которые заново импортируют главный модуль: иначе дочерний процесс может начать создавать новых детей ещё при загрузке.

import manual_app
import runpy

print("Импорт завершён")
print("Расчёт:", manual_app.calculate(4))
runpy.run_module("manual_app", run_name="__main__")

Импорт завершён
Расчёт: 8
Запуск приложения: 6

Как Python находит ваш файл

Поиск модулей учитывает sys.path, установленное окружение и механизмы импорта. Поэтому файл json.py рядом с программой способен заслонить одноимённый стандартный модуль. Симптомом бывает неожиданное отсутствие метода или сообщение о частично инициализированном модуле. Проверьте имя своего файла, путь интерпретатора и module.__file__, если этот атрибут есть. Некоторые встроенные или особым образом загруженные модули не обязаны иметь обычный путь на диске; это не признак неисправности.

Не исправляйте ошибку установки пакета бесконечным добавлением случайных каталогов в sys.path. Сначала убедитесь, что зависимость поставлена именно для запускаемого интерпретатора, используя python -m pip. Различайте импортное имя и имя дистрибутива: они могут не совпадать. Версию установленного дистрибутива можно узнать через importlib.metadata.version; наличие его метаданных и наличие конкретного импортируемого модуля связаны, но отвечают на разные вопросы. При отсутствии дистрибутива возникает PackageNotFoundError.

Соберите связанные модули в пакет

Для первого обычного пакета создайте каталог с __init__.py, файлом расчёта и __main__.py для запуска. Пустой __init__.py подходит; не нужно импортировать в нём всё содержимое проекта. Относительный импорт from .core import total обращается к соседнему модулю внутри пакета. Прямой запуск такого файла по пути теряет контекст пакета и может вызвать ошибку относительного импорта. Запускайте пакет через python -m manual_report из правильного окружения.

import runpy

runpy.run_module("manual_report", run_name="__main__")

Отчёт: 42

Команда для обычного терминала; этот блок показывает способ запуска, а не отдельный проверенный скрипт:

python -m manual_report

Циклический импорт возникает, когда модули требуют имена друг друга до завершения инициализации. Часто помогает выделить общие типы и функции в третий модуль с минимальными зависимостями. Перенос импорта внутрь функции иногда устраняет конкретный порядок загрузки, но может скрыть неудачное устройство проекта. Старайтесь строить зависимости направленно: ввод вызывает расчёт, расчёт не импортирует интерфейс; слой хранения получает данные, а не управляет всем приложением. Такое разделение также делает тесты проще.

Ресурсы и окружение — разные части проекта

Для шаблона, встроенного в пакет, используйте importlib.resources.files и чтение через полученный объект ресурса. Не рассчитывайте, что пакет всегда лежит распакованной папкой рядом с текущей директорией. Если стороннему API действительно нужен физический путь, контекстный менеджер as_file предоставляет его на ограниченное время. Пользовательские отчёты, базы и настройки лучше хранить вне установленного пакета, в выбранной рабочей папке; после обновления программы они должны оставаться доступны.

pyproject.toml описывает сборку, метаданные и зависимости проекта. Сам файл не устанавливает пакеты и не создаёт окружение. Ограничение версии зависимости задаёт разрешённый диапазон; файл фиксации или иной воспроизводимый список закрепляет выбранные версии для конкретного запуска. Формат фиксации зависит от инструмента. Для передачи проекта также запишите требуемую версию Python и команды проверки. Не копируйте чужую виртуальную среду как универсальный переносимый пакет: воспроизводите её из описания зависимостей.

Отложенный импорт появился в Python 3.15

lazy import переносит загрузку модуля к первому использованию имени. Это бывает полезно для большого CLI с редко используемыми командами, но меняет момент возможной ошибки и выполнения побочных действий. Синтаксис разрешён на уровне модуля, а не внутри функции, класса или try/except/finally; звёздочный и future-импорт тоже не могут быть lazy. Для начала изучите обычный импорт. Совместимый путь __lazy_modules__ описан в документации, однако конкретный новый синтаксис потребует Python 3.15.

lazy import manual_missing_dependency_315

print("Объявление прошло")
try:
    print(manual_missing_dependency_315.__name__)
except ModuleNotFoundError as error:
    print("Первое использование:", type(error).__name__)

Объявление прошло
Первое использование: ModuleNotFoundError

Практика: импорт без лишнего вывода

Положите функцию нормализации названия в модуль, импортируйте её и убедитесь, что при импорте ничего не печатается. Обработайте строку из пробелов как отсутствующее название. Затем добавьте в модуль main() и защиту запуска. Отдельно выполните модуль как программу: в этом случае демонстрация должна появиться. Так вы проверите два разных пользовательских сценария — повторное использование функции и самостоятельный запуск.

from manual_names import normalize

print(normalize("  Новый отчёт  "))
print(normalize("   "))

Новый отчёт
Без названия