Протоколы и контракты в Python (Лабораторная работа №1)

Цель: Реализовать, протестировать и продемонстрировать подсистему приёма задач с использованием typing.Protocol, runtime-проверки через @runtime_checkable и нескольких источников данных

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

Реализованные бонусы: Dockerfile для быстрого запуска проекта

1) Установка проекта локально

git clone https://github.com/TheVailen/python_lab1.git
cd python_lab1
python3 -m venv .venv
source .venv/bin/activate
pip install pytest pytest-cov

2) Реализованный функционал

Категория	Функции/Классы/Аргументы
Контракты	Task
	TaskSource
Источники задач	JsonlFileSource
	GeneratorSource
	ApiStubSource
Подсистема приёма	TaskIntake
Демонстрация	main()
Тестирование	pytest
Бонусы	Dockerfile

3) Запуск программы и режим работы

Демонстрационный запуск

Программа демонстрирует работу подсистемы приёма задач с тремя типами источников: файл, генератор и API-заглушка

python -m src.main

Вывод

file-1: {"action": "process_order", "order_id": 101}
file-2: {"action": "send_notification", "user_id": 7}
gen-1: {"action": "recalculate_stats"}
gen-2: {"action": "check_resource"}
api-1: {"action": "sync_external_data"}
api-2: {"action": "rebuild_cache"}

4) Тесты

python -m pytest -v

Тесты с процентом покрытия (реализовано 97% покрытия)

python -m pytest --cov=src

5) Запуск в Docker

Сборка Docker-образа

docker build -t python-lab1 .

Запуск в контейнере

docker run --rm python-lab1

Запуск тестов в контейнере

docker run --rm python-lab1 python -m pytest tests -v

6) Допущения

• В качестве файлового источника используется формат JSONL, где каждая строка должна содержать JSON-объект с полями id и payload.

• API-источник в данной лабораторной реализован как заглушка, то есть данные передаются заранее подготовленным списком словарей.

• Если в ответе API отсутствует поле id, оно автоматически формируется в виде api-<номер>.

• Подсистема TaskIntake принимает только объекты, удовлетворяющие протоколу TaskSource, что проверяется через isinstance(..., TaskSource) благодаря @runtime_checkable.

• main.py используется как демонстрационный сценарий, поэтому при каждом запуске вывод программы одинаковый.

7) Используемые библиотеки и модули

Категория	Модуль	Назначение
Контракты и типизация	typing	Использование Protocol, runtime_checkable, Any и аннотаций типов
Модели данных	dataclasses	Описание структуры задачи через @dataclass
Коллекции	collections.abc	Типизация итерируемых объектов (Iterable, Sequence, Callable)
Файлы и пути	pathlib	Работа с путями к JSONL-файлам
JSON	json	Чтение и разбор задач из JSONL-файла
Тестирование	pytest	Проверка корректности работы модулей и runtime-проверок
Покрытие	pytest-cov	Подсчёт процента покрытия кода тестами
Контейнеризация	Docker	Быстрый переносимый запуск проекта в одинаковом окружении

8) Чему я научился

• Освоил использование typing.Protocol для задания поведенческого контракта без общего базового класса.

• Научился использовать @runtime_checkable для runtime-проверки соответствия протоколу через isinstance.

• Реализовал несколько источников данных, работающих по одному контракту.

• Научился разделять проект на модули: контракт, источники, подсистема агрегации, демонстрационный запуск.