Проект, который запустится у другого

Передаём рецепт окружения

Ваша .venv зависит от компьютера и содержит локальные пути. Её не отправляют в Git или архив проекта. Другому разработчику нужны исходники, установленный Python и список зависимостей, по которому он создаст собственное окружение.

python -m pip freeze > requirements.txt

Выполняйте команду в активном окружении этого проекта. freeze записывает установленные пакеты с версиями, в том числе транзитивные зависимости Rich. Символ > сохраняет вывод в файл и перезаписывает прежнее содержимое.

rich==13.9.4
markdown-it-py==3.0.0
mdurl==0.1.2
Pygments==2.18.0

Это зафиксированный набор для скачиваемого примера, а не обещание самых новых версий. Ваш freeze после pip install rich может дать другие версии. В своей работе проверяйте именно свой файл зависимостей.

Что попадёт в Git

.venv/
__pycache__/
*.pyc
.env

__pycache__ и *.pyc — автоматически создаваемый кэш Python. .env может содержать локальные настройки и секреты. Исходники, тесты, README, requirements и сам .gitignore должны оставаться в репозитории.

Проверить правила можно командой git status: она перечисляет файлы, которые Git сейчас видит. Папки в коротком выводе показаны целиком, поэтому кеш внутри app удобно посмотреть отдельной командой с ключом --untracked-files=all.

git status --short
git status --short --untracked-files=all -- app

README — инструкция следующему человеку

Читатель не присутствовал на занятии. Напишите, что делает программа, какая версия Python нужна, откуда выполнять команды, как создать окружение, установить зависимости, запустить приложение и что должно появиться. Названия папок объясните через обязанности.

Что такое тест и зачем он в этой теме

Тест — это обычный код, который вызывает вашу функцию с известными данными и проверяет, что она вернула ожидаемое. Проверяет не человек глазами, а сама программа: вы один раз описываете «на списке [5, 4, 5, 3, 5] среднее равно 4.4» — и дальше эта проверка повторяется по команде за доли секунды.

В этой теме тесты выполняют ещё одну работу: они проверяют структуру проекта. Тестовый файл лежит в отдельной папке tests и добирается до функций теми же импортами, что и main.py. Если структура собрана правильно, тесты запускаются сразу. Если раскладка файлов не совпадает с импортами, появятся те же ошибки, которые разобраны в главах 2.4 и 2.5.

Тесты ваши модули импортируют, а не запускают. Поэтому main() и должен вызываться только под условием __name__ == "__main__" — иначе при каждом прогоне тестов программа будет печатать свой отчёт.

Ставим pytest

Тесты запускает отдельная программа — pytest. Она устанавливается в окружение проекта так же, как Rich в главе 2.3.

python -m pip install pytest
python -m pip freeze > requirements.txt

Вторая команда обновляет список зависимостей: pytest тоже нужен тому, кто будет проверять вашу работу.

Файл с тестами

Каждый тест — обычная функция. Ни классов, ни наследования здесь не требуется: pytest сам находит функции, имя которых начинается с test_, и вызывает их по очереди.

import pytest

from app.services.calculator import calculate_average
from app.utils.formatter import format_average


def test_average():
    assert calculate_average([5, 4, 5, 3, 5]) == pytest.approx(4.4)


def test_format():
    assert format_average(4.4) == "Средний результат: 4.40"


def test_empty_list():
    with pytest.raises(ValueError):
        calculate_average([])

Как работает assert

assert — это встроенная в Python проверка условия. Читается она так: «дальше идём, только если условие истинно».

• Условие истинно — assert ничего не делает, функция доходит до конца, тест считается пройденным.
• Условие ложно — Python останавливает функцию и сообщает об ошибке AssertionError. pytest перехватывает её и печатает, какие значения сравнивались.

Поэтому строка assert format_average(4.4) == "Средний результат: 4.40" означает: вызови функцию и сравни результат со строкой справа. Никаких специальных слов для сравнения не нужно — работают обычные операторы ==, !=, >, in.

Две конструкции в файле пришли из pytest:

• pytest.approx(4.4) — «примерно 4.4». Нужно для дробных чисел: они хранятся приближённо, и точное равенство иногда не выполняется.
• with pytest.raises(ValueError): — «внутри этого блока обязана возникнуть такая ошибка». Здесь проверяется не результат, а поведение при неверных данных: на пустом списке calculate_average должна вызывать ValueError. Если функция промолчит, тест не пройдёт.

Команда запуска по частям

python -m pytest -v

-m pytest — запускаем pytest тем же Python, что и программу. -v — печатать каждый тест отдельной строкой. Команда выполняется из корня проекта: оттуда виден пакет app, который тесты импортируют. Папку с тестами указывать не нужно — pytest сам обходит проект и берёт файлы test_*.py.

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

Как выглядит непройденный тест

Пройденные тесты показывают только, что всё в порядке. Разберите три других вывода — они встретятся в практике 2.7 и в домашней работе.

Тест не прошёл: расчёт вернул не то

Ошибка до проверки

Ноль тестов: проверок не было

Проверка с чистого листа

Скопируйте только передаваемые файлы в отдельную папку или скачайте свой репозиторий заново. Откройте папку, содержащую app и requirements.txt. Создайте там новое окружение и активируйте его командами главы 2.1.

python -m pip install -r requirements.txt
python -m app.main
python -m pytest -v

Если видны Средний результат: 4.40 и 3 passed, вы проверили, что проект не зависит от старой локальной .venv. В README укажите также вывод python --version.

Рецепт уже лежит в проекте

В Python список зависимостей создавала отдельная команда pip freeze. В Go отдельного шага нет: go.mod и go.sum заполнялись сами, пока вы работали. Передать проект другому человеку — значит передать исходники вместе с этими двумя файлами.

go mod tidy
go mod verify
go list -m all

go mod tidy приводит файлы в соответствие с импортами в коде. go mod verify пересчитывает контрольные суммы всех скачанных зависимостей и сравнивает их с go.sum: ответ all modules verified означает, что содержимое версий не менялось с момента загрузки. Обе команды выполняют перед отправкой работы.

module example.com/student-tools

go 1.21

require github.com/fatih/color v1.17.0

require (
	github.com/mattn/go-colorable v0.1.13 // indirect
	github.com/mattn/go-isatty v0.0.20 // indirect
	golang.org/x/sys v0.18.0 // indirect
)

Это зафиксированный набор для скачиваемого примера, а не обещание самых новых версий. У вас версии будут другими — так и должно быть. В своей работе проверяйте именно свой go.mod.

Что попадёт в Git

# Результат сборки
student-tools
student-tools.exe

# Локальные настройки и покрытие
.env
coverage.out

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

go.mod и go.sum в репозиторий попадают обязательно. Без них другой человек не сможет получить те же версии, и go build у него соберёт неизвестно что — или не соберёт вовсе.

README и тесты рядом с кодом

Читатель не присутствовал на занятии. Напишите, что делает программа, какая версия Go нужна, откуда выполнять команды, как получить зависимости, как собрать и запустить проект и что должно появиться. Названия папок объясните через обязанности.

Что такое тест и зачем он в этой теме

Тест — это обычный код, который вызывает вашу функцию с известными данными и проверяет, что она вернула ожидаемое. Проверяет не человек глазами, а сама программа: вы один раз описываете «на срезе [5, 4, 5, 3, 5] среднее равно 4.4» — и дальше эта проверка повторяется по команде за доли секунды.

В Go тестирование встроено в язык и в команду go: ставить ничего не нужно, сторонние библиотеки для трёх проверок не требуются. Правила всего три, и все они про имена. Файл обязан заканчиваться на _test.go. Функция обязана начинаться с Test и принимать один аргумент *testing.T. И такой файл не попадает в обычную сборку: go build его игнорирует, поэтому тесты не увеличивают программу.

Ещё одно отличие от Python: тест лежит в той же папке, что и проверяемый код, и объявляет тот же пакет. Отдельной папки tests в Go не делают. Зато тесту становятся доступны и неэкспортированные имена пакета — то, до чего внешний код не добрался бы.

package services

import (
	"math"
	"testing"
)

func TestCalculateAverage(t *testing.T) {
	got, err := CalculateAverage([]int{5, 4, 5, 3, 5})
	if err != nil {
		t.Fatalf("неожиданная ошибка: %v", err)
	}
	if math.Abs(got-4.4) > 1e-9 {
		t.Errorf("среднее = %v, ожидалось 4.4", got)
	}
}

func TestCalculateAverageEmpty(t *testing.T) {
	_, err := CalculateAverage([]int{})
	if err == nil {
		t.Error("для пустого среза ожидалась ошибка, её нет")
	}
}

Как читается файл теста

• package services — тот же пакет, что и у проверяемого файла. Поэтому CalculateAverage вызывается напрямую, без импорта: имена внутри пакета видны без квалификации.
• func TestCalculateAverage(t *testing.T) — один тест. Имя обязано начинаться с Test: по этому признаку Go и находит, что запускать. Функция без такого имени просто не выполнится.
• t.Errorf(...) — «запиши расхождение и продолжай»; t.Fatalf(...) — «запиши и прекрати этот тест немедленно». Второе нужно там, где дальше проверять нечего: если функция вернула ошибку, сравнивать её результат бессмысленно.
• Готовых assertEqual в Go нет: сравнение пишется обычным if, и тест остаётся обычным кодом.

Почему сравнение через math.Abs

Компьютер хранит дробные числа приближённо, и привычные равенства иногда не выполняются: 0.1 + 0.2 даёт 0.30000000000000004. Так устроено двоичное представление дробных чисел, и это одинаково работает во всех языках. Поэтому дробные результаты сравнивают с допуском: math.Abs(got-4.4) > 1e-9 читается как «отличается больше, чем на миллиардную». Точное сравнение == оставляют строкам и целым числам.

Команда запуска по частям

go test ./...
go test ./... -v
go test ./internal/services -run TestCalculateAverageEmpty -v

go test собирает и запускает тесты; ./... — «все пакеты модуля»; -v печатает каждый тест отдельной строкой, а не сводку. Третья команда показывает, как запустить один тест: -run принимает шаблон имени. Команды работают из любой папки внутри модуля.

Ожидается две строки --- PASS и итог ok example.com/student-tools/internal/services. Пакеты без тестов Go отметит как no test files: так он сообщает, что проверять там нечего.

Как выглядит непройденный тест

Зелёный прогон полезен, но учит мало. Разберите три вида вывода — с ними вы столкнётесь в практике 2.7 и в домашней работе.

FAIL — код отработал, но посчитал не то

--- FAIL: TestCalculateAverage (0.00s)
    calculator_test.go:15: среднее = 5.5, ожидалось 4.4
FAIL
FAIL    example.com/student-tools/internal/services    0.002s
FAIL

Здесь в формулу внесена ошибка — деление на len(values) - 1. Go называет тест, файл и строку, где сработала проверка, а текст расхождения вы написали сами в t.Errorf. Отсюда практический вывод: пишите в сообщении и полученное, и ожидаемое значение — иначе через месяц вывод FAIL вам ничего не скажет.

Ошибка сборки — до тестов дело не дошло

# example.com/student-tools/internal/services [build failed]
./calculator_test.go:10:17: not enough arguments in call to CalculateAverage
FAIL    example.com/student-tools/internal/services [build failed]

Аналог питоновского ERROR, только раньше: в Go такие ошибки находит компилятор, а не выполнение теста. Пометка [build failed] означает, что ни один тест пакета не запускался. Разница важна: FAIL — «проверка не сошлась», build failed — «код не собрался», и чинить нужно разные места.

Строки no test files: проверок не было

?       example.com/student-tools               [no test files]
?       example.com/student-tools/internal/services      [no test files]
?       example.com/student-tools/internal/utils         [no test files]

Так выглядит прогон, в котором проверять оказалось нечего: файл назван calculatortest.go вместо calculator_test.go, или функция — CheckAverage вместо TestAverage. Ошибки нет, красного цвета нет, но и проверок не было. Смотрите не на отсутствие слова FAIL, а на наличие строк ok и PASS.

Проверка с чистого листа

Скопируйте только передаваемые файлы в отдельную папку или скачайте свой репозиторий заново. Откройте папку, содержащую main.go и go.mod. Кэш модулей можно даже очистить командой go clean -modcache, чтобы зависимости скачались заново.

go mod download
go build ./...
go run .
go test ./... -v

Если видны Средний результат: 4.40 и строки PASS, вы проверили, что проект собирается не только у вас. В README укажите также вывод go version: он показывает, на какой версии работа проверялась.