Зависимости Python — requirements.txt, pyproject.toml и pip

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Разработчику Инженеру

---

Почему import requests может не сработать

Стандартная библиотека Python (os, json, urllib) ставится вместе с интерпретатором. Пакет requests в неё не входит — его нужно скачать с PyPI через pip и записать в манифест проекта, чтобы коллеги и CI поставили то же самое.

Без установки:

ModuleNotFoundError: No module named 'requests'

Обзор манифестов для всех языков и Docker — Манифесты зависимостей. Теория PyPI и место pip в дистрибутиве — Архитектура CPython.

---

Пример — проверка URL через requests

Файл check_url.py:

import requests

def check_url(url: str) -> bool:
    try:
        response = requests.get(url, timeout=5)
        return response.status_code == 200
    except requests.RequestException:
        return False

if __name__ == "__main__":
    print(check_url("https://example.com"))

Блок if __name__ == "__main__": запускает проверку только при python check_url.py, а не при import check_url — см. точку входа и импорт.

Пока requests не установлен, скрипт не дойдёт до сети — упадёт на import.

---

requirements.txt — список для pip

Создайте в корне проекта файл requirements.txt:

requests>=2.31.0

Установка (лучше внутри виртуального окружения):

python -m venv .venv

Активация:

• Windows (PowerShell): .venv\Scripts\Activate.ps1
• Linux / macOS: source .venv/bin/activate

pip install -r requirements.txt
python check_url.py

Ожидаемый вывод: True для https://example.com (если сайт отвечает 200).

Что сказать тому, кто разворачивает проект

«Все Python-зависимости в requirements.txt в корне репозитория. После клона — python -m venv .venv, активация venv, затем pip install -r requirements.txt».

---

pyproject.toml — современный манифест проекта

Один файл описывает проект и зависимости (стандарт PEP 621):

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "url-checker"
version = "0.1.0"
description = "Проверка доступности URL"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.31.0",
]

[tool.setuptools.py-modules]
check_url = {}

Секция [tool.setuptools.py-modules] нужна, чтобы однофайловый check_url.py считался модулем при pip install ..

Установка проекта в venv (зависимости подтянутся из секции dependencies):

pip install .
# режим разработки — правки check_url.py без переустановки после каждого save:
pip install -e .

Запуск скрипта после установки:

python check_url.py

Для библиотек в репозитории обычно добавляют пакет в подпапке (src/url_checker/…); для учебного одного файла достаточно requirements.txt или минимального pyproject.toml выше.

---

Виртуальное окружение (venv)

venv изолирует пакеты проекта от системного Python и от других проектов на той же машине.

Действие	Команда
Создать venv	python -m venv .venv
Активировать (Windows)	.venv\Scripts\activate
Активировать (Unix)	source .venv/bin/activate
Установить из списка	pip install -r requirements.txt
Установить один пакет	pip install requests
Сохранить текущий набор в файл	pip freeze > requirements.txt

pip freeze фиксирует все установленные пакеты с точными версиями — удобно для снимка, но файл получается длинным. Для новых проектов часто вручную пишут только прямые зависимости (requests, fastapi) или используют Poetry / uv.

---

Полезные команды pip

Команда	Назначение
pip install имя	Установить последнюю совместимую версию с PyPI
pip install имя==2.31.0	Точная версия
pip install -r requirements.txt	Установить всё из файла
pip install -e .	Проект из текущей папки (editable)
pip uninstall имя	Удалить пакет
pip list	Список установленного в venv
pip show requests	Метаданные пакета, путь установки
pip install --upgrade pip	Обновить сам pip
python -m pip install …	То же, явно через модуль (рекомендуется в документации)

Проверка, что requests виден интерпретатору:

python -c "import requests; print(requests.__version__)"

---

Сравнение requirements.txt и pyproject.toml

	requirements.txt	pyproject.toml
Формат	строка на пакет	TOML, секция [project]
Типичное использование	скрипты, учебные проекты, Docker, CI	библиотеки, приложения, Poetry/PDM
Установка	pip install -r requirements.txt	pip install . или менеджер Poetry
Метаданные проекта	нет	имя, версия, автор, entry points

Оба варианта читают pip; в одном репозитории иногда держат pyproject.toml как источник правды, а requirements.txt генерируют для Docker — главное, чтобы команда и CI использовали один согласованный способ.

---

Docker и CI — тот же requirements.txt

В Dockerfile зависимости ставят при сборке образа:

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY check_url.py .

В GitHub Actions / GitLab CI шаг тот же, что локально:

- run: pip install -r requirements.txt

Полный workflow для Python CI (checkout, кэш pip, pytest) — GitHub Actions — CI/CD рецепты.

Подробнее про слои кэша и compose — Манифесты зависимостей, DevOps CI. Готовый Dockerfile для Flask/FastAPI — галерея Lab.

---

Частые ошибки

Симптом	Причина	Что сделать
ModuleNotFoundError	Пакет не установлен или другой Python	Активировать venv, pip install -r requirements.txt
Пакет есть, но import падает	Запуск python не из того venv	where python (Windows) / which python, проверить путь
На CI работает, локально нет	Нет файла зависимостей в ветке	Закоммитить requirements.txt или pyproject.toml
Разные версии у коллег	Нет фиксации версий	requests==2.32.3 или lock (Poetry, pip-tools)

---

Дальше по разделу Python

Тема	Статья
Первая программа, установка Python	16 — Первая программа
if __name__ == "__main__"	40 — точка входа
Веб, FastAPI, Django	34 — Веб и REST
Тесты (pytest ставится отдельно)	37 — pytest