Модули и импорт

Модуль — это файл и объект

Любой файл something.py — модуль. При импорте Python выполняет его код и создаёт объект-модуль, атрибуты которого — все глобальные имена файла:

import math

print(type(math), math.__name__)
print(math.sqrt(16), math.pi)
print([name for name in dir(math) if not name.startswith("_")][:8], "...")
print(math.__file__ if hasattr(math, "__file__") else "встроен в интерпретатор")

Формы импорта

import json                               # имя json → объект-модуль
import collections.abc                    # загружает пакет и подмодуль, имя — collections
import datetime as dt                     # псевдоним
from pathlib import Path                  # имя Path → объект из модуля
from os.path import join as path_join     # конкретное имя с псевдонимом

print(json.dumps([1]), collections.abc.Iterable, dt.date(2026, 1, 1))
print(Path("a") / "b", path_join("a", "b"))

from-импорт копирует ссылку

import types, sys

settings = types.ModuleType("settings")       # создаём модуль на лету для примера
settings.DEBUG = False
sys.modules["settings"] = settings

from settings import DEBUG                    # ссылка на объект False
import settings as s

s.DEBUG = True                                # меняем атрибут модуля
print(DEBUG, s.DEBUG)                         # наша копия ссылки не изменилась

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

Модуль выполняется один раз

При первом import x Python выполняет файл и кладёт модуль в словарь sys.modules. Все последующие импорты берут готовый объект из кеша:

import sys, tempfile, pathlib

folder = pathlib.Path(tempfile.mkdtemp())
(folder / "greeter.py").write_text(
    'print("  выполняется код модуля greeter")\n'
    'counter = 0\n'
    'def hello(name):\n'
    '    global counter\n'
    '    counter += 1\n'
    '    return f"Привет, {name}!"\n',
    encoding="utf-8",
)
sys.path.insert(0, str(folder))             # добавляем папку в путь поиска модулей

import greeter
import greeter                              # второй раз код модуля не выполняется
from greeter import hello

print(hello("Анна"), greeter.counter)
print("greeter" in sys.modules, sys.modules["greeter"] is greeter)

import importlib
greeter = importlib.reload(greeter)         # принудительно выполнить заново
print("после reload counter =", greeter.counter)

Поэтому модуль — естественный синглтон: объект config, созданный в модуле, один на всё приложение.

Как Python ищет модуль

1. sys.modules — уже загружен? Вернуть.
2. Встроенные модули (sys, builtins).
3. sys.path — список папок, по порядку: - папка запускаемого скрипта (или текущая при python -m); - PYTHONPATH; - стандартная библиотека; - site-packages текущего окружения (то, что поставил pip).

import sys
for p in sys.path[:6]:
    print(repr(p))

name и main

У каждого модуля есть __name__. При импорте это имя модуля ("greeter"), а у файла, запущенного как программа, — "__main__":

# tools.py
def slugify(text):
    return text.lower().replace(" ", "-")

def main():
    print(slugify("Hello World"))

if __name__ == "__main__":     # True только при `python tools.py`
    main()                     # при `import tools` не выполнится

python -m package.module запускает модуль как программу, правильно настраивая sys.path и относительные импорты — предпочтительный способ запуска модулей внутри пакетов.

all

Список __all__ определяет, что экспортирует from module import *, и документирует публичный API:

# geometry.py
__all__ = ["area", "Circle"]

def area(r): ...
class Circle: ...
def _helper(): ...          # с подчёркиванием — внутреннее

Циклические импорты

# a.py                          # b.py
from b import func_b            from a import func_a     # ← a ещё не выполнен до конца!
def func_a(): ...               def func_b(): ...

Когда a импортирует b, а b — a, второй получает недоделанный модуль a (из sys.modules), в котором ещё нет func_a → ImportError: cannot import name ... (most likely due to a circular import).

Решения:

1. Вынести общее в третий модуль — лучший вариант, обычно цикл указывает на плохое разделение ответственности.
2. Импортировать внутри функции — импорт выполнится при вызове, когда оба модуля уже загружены.
3. import b вместо from b import func_b и обращение b.func_b() во время вызова.
4. Для подсказок типов — from __future__ import annotations и if TYPE_CHECKING:.

Динамический и ленивый импорт

import importlib

for name in ["json", "csv", "nonexistent_lib"]:
    try:
        module = importlib.import_module(name)
        print(name, "→", module)
    except ModuleNotFoundError as e:
        print(name, "→", e)

def export_excel(rows):
    import decimal                  # тяжёлую зависимость импортируем только при вызове
    return decimal.Decimal(len(rows))

print(export_excel([1, 2, 3]))

Импорт внутри функции ускоряет запуск CLI-утилит и разрывает циклы, но прячет зависимости — используйте осознанно.

Итог

• Модуль — файл .py и объект, его атрибуты — глобальные имена файла.
• Код модуля выполняется один раз, затем модуль берётся из sys.modules.
• Поиск: sys.modules → встроенные → sys.path; не называйте файлы как стандартные модули.
• if __name__ == "__main__": — код только для запуска как программы.
• Избегайте import *; циклы разрывайте выносом общего кода или импортом внутри функции.