Модули и импорты в Python: import, from-import, pip и пакеты

Один файл — один модуль

Когда код вырастает за рамки одного скрипта, хочется разложить его по файлам. Модульная система Python проста: любой .py-файл автоматически модуль, импортируемый по имени.

Допустим, есть файл util.py:

# util.py
def greet(name):
    return f"Hello, {name}"

PI = 3.14159

В другом файле той же папки — main.py — ты им пользуешься:

# main.py
import util

print(util.greet("Ada"))
print(util.PI)

Запусти python3 main.py, и Python найдёт util.py, выполнит его один раз и сделает всё, что определено на верхнем уровне (функции, переменные, классы), атрибутами модуля util.

Три формы импорта

Импорт целиком. К содержимому обращаешься через имя модуля:

Импорт конкретных имён. Они становятся доступны напрямую:

Импорт с алиасом. Полезно, когда имя модуля длинное или когда два модуля имеют одинаковое имя:

import numpy as np
import pandas as pd

# Now use np.array(...), pd.DataFrame(...), etc.

Есть и четвёртая форма — from math import *, — которая тянет всё в твоё пространство имён. Избегай её вне REPL: в коде становится невозможно понять, откуда взялось имя, и создаются тихие коллизии.

Когда выполняются импорты

Python выполняет код верхнего уровня импортируемого модуля один раз — при первом импорте в данной программе. Последующие импорты того же модуля возвращают уже загруженную версию. Так что:

# setup.py
print("setup module loading...")
VALUE = 42

# main.py
import setup
import setup  # imported twice — but "loading" only prints once
print(setup.VALUE)

Напечатает "setup module loading..." только один раз. Это важно: если ты положил побочные эффекты (открытие файла или печать) на верхний уровень модуля, они случатся при импорте, и это обычно не то, чего ты хотел. Убирай такие вещи в функции.

Стандартная библиотека

Python поставляется с большой стандартной библиотекой модулей. Несколько ты уже видел. Часть будет под рукой постоянно:

• math — sqrt, sin, log, константы вроде pi и e.
• random — случайные числа, выбор, перемешивание.
• datetime — даты и время.
• json — чтение/запись JSON.
• os, os.path — пути и операции файловой системы.
• pathlib — современная работа с путями, часто приятнее, чем os.path.
• re — регулярные выражения.
• collections — специализированные коллекционные типы (Counter, defaultdict, deque и так далее).
• itertools, functools — помощники для итераторов и функций.
• csv — чтение и запись CSV.

Стандартная библиотека уже установлена — ничего ставить через pip не нужно.

Сторонние пакеты и pip

Для всего, что не покрыто стандартной библиотекой, есть Python Package Index (PyPI), где лежат сотни тысяч пакетов. Устанавливаются они через pip:

pip install requests
pip install pandas
pip install --upgrade requests
pip uninstall requests

После установки они импортируются как обычно:

import requests

response = requests.get("https://api.example.com/data")
print(response.status_code)

Пара советов, как не сойти с ума:

Используй виртуальные окружения

Ставить всё глобально — путь к боли. Разным проектам нужны разные версии, какие-то пакеты зависят от конкретной версии Python, глобальные установки на некоторых системах требуют админских прав. Виртуальное окружение — изолированная установка Python под один проект:

python3 -m venv .venv
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

pip install requests

Пока venv активно, pip ставит в папку проекта, а не в систему. Закончил — deactivate.

Фиксируй зависимости

Сохрани список установленных пакетов, чтобы другие (включая тебя будущего) могли воспроизвести то же окружение:

pip freeze > requirements.txt

А потом:

pip install -r requirements.txt

Инструменты вроде Poetry, pipenv и uv делают это эргономичнее, но связка pip + requirements.txt прекрасно подходит для обучения.

Пишем свои модули

Когда появляются функции, которые хочется переиспользовать в разных файлах, выноси их в отдельный модуль. Соглашения об именах:

• Имена файлов — lower_snake_case.py.
• Функции и переменные на уровне модуля — тоже lower_snake_case.
• Классы — PascalCase.

# shopping.py
PRICES = {"apple": 0.50, "bread": 2.00}

def total(items):
    return sum(PRICES[item] for item in items)

# main.py
from shopping import total, PRICES

print(total(["apple", "bread"]))
print(PRICES)

Если два файла в одной папке импортируют друг друга, ты можешь случайно создать циклический импорт. Типичный ремонт — вынести общий код в третий файл, который импортируют оба.

Пакеты: папки с модулями

Когда модулей становится больше горстки, сгруппируй их в пакет — папку с файлом __init__.py внутри:

myproject/
├── main.py
└── utils/
    ├── __init__.py
    ├── text.py
    └── numbers.py

А потом:

from utils.text import slugify
from utils import numbers

print(slugify("Hello, World"))
print(numbers.mean([1, 2, 3]))

__init__.py может быть пустым; важно само его присутствие — оно делает utils пакетом. В современном Python есть и «namespace packages» без __init__.py, но для старта явная версия понятнее.

Мини-чеклист, когда импорты ломаются

• «ModuleNotFoundError: No module named X». Либо пакет не установлен, либо ты запускаешь Python от другого интерпретатора, а не от того, куда ставил pip install. В venv убедись, что окружение активировано.
• «ImportError: cannot import name Y from X». Модуль есть, но нужного имени в нём нет. Ищи опечатки и смотри реальное содержимое модуля.
• «Circular import». Два модуля импортируют друг друга. Вытащи общий код в третий модуль.

Дальше: установка сторонних пакетов

Собственные модули заводят далеко, но большинство реальных проектов подтягивает библиотеки из PyPI — requests, pandas, тест-фреймворк. Следующая страница — про pip, как чисто ставить пакеты и фиксировать зависимости проекта.