Как зафиксировать окружение расчёта Python и проверить контрольный запуск

Вы несколько раз запускали скрипт, получили числа, сохранили результат. Через месяц коллега или научный руководитель просит повторить расчёт. Вы запускаете файл, а он выдаёт ошибку импорта или другое среднее. Знакомая ситуация: на чужом компьютере нет библиотеки, которую вы ставили когда-то, или Python оказался другой версии.

Причина может быть в коде, входных данных или окружении. Чтобы разбираться предметно, передайте вместе со скриптом описание условий запуска и ожидаемый результат. Затем проверьте выбранный пример в отдельном окружении, сохраняя исходные файлы.

Расскажу на конкретном учебном примере, из каких файлов состоит такой пакет, как провести контрольный запуск и почему requirements.txt — это ещё не всё.

Из чего состоит зафиксированное окружение

В нашем авторском учебном расчёте скрипт читает числа из CSV и выводит количество записей и среднее. Числа 1, 2 и 3 вымышленные: они показывают механику, а не результаты наблюдения студентов. Скрипт использует csv и statistics из стандартной библиотеки Python; в отдельном контрольном окружении внешние пакеты для него не понадобились. Зафиксируем интерпретатор, файлы и команду, чтобы другой читатель мог проверить именно этот расчёт.

Для этого небольшого учебного примера соберём пять файлов. Это выбранный состав нашего пакета, а не универсальное требование к любому исследованию:

Разберём каждый файл по порядку.

Входные данные: hours.csv

Входной CSV здесь содержит один столбец: заголовок hours и три числовые строки 1, 2, 3. Поскольку поле в каждой строке только одно, запятые в показанном файле не требуются. Сохраните этот учебный текст в UTF-8:

hours
1
2
3

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

Скрипт расчёта: analysis.py

Полный код, который сохраняет переносы строк и отступы:

import csv
from statistics import mean
with open("hours.csv", encoding="utf-8", newline="") as f:
    values = [float(row["hours"]) for row in csv.DictReader(f)]
print(f"n={len(values)}")
print(f"mean={mean(values):.1f}")

Скрипт делает три вещи: открывает файл, собирает числа из столбца hours, выводит количество записей и среднее с одним знаком после запятой.

В показанном коде чтение явно задаёт encoding="utf-8" и newline="". Наш файл подготовлен для этого условия. Не меняйте кодировку и структуру чужого набора наугад: сверяйте их с его описанием и параметрами чтения.

Зависимости: requirements.txt

В нашем проверенном примере requirements.txt пустой: в отдельном окружении вывод python -m pip freeze был пустым, а показанный скрипт выполнился без внешних пакетов. Само по себе наличие пустого файла в неизвестном проекте не доказывает, что его зависимости описаны полностью.

requirements.txt можно создать, перенаправив вывод команды pip freeze в файл: python -m pip freeze > requirements.txt. Команда pip freeze выводит установленные пакеты в формате requirements, а перенаправление (>) записывает этот вывод в файл. Важный момент: pip freeze описывает то, что уже установлено, а не вычисляет lockfile или результат работы решателя зависимостей. Также по умолчанию из вывода исключаются некоторые инструменты начальной установки — например, в Python 3.12 исключается только pip. Это нормально для фиксации зависимостей проекта, но нужно помнить об ограничениях.

Сведения об окружении: run-info.txt

В run-info.txt запишем фактические условия контрольного запуска: CPython 3.12.14, Linux, без внешних пакетов. Это сведения о нашем запуске 26 октября 2026 года, а не требование установить именно эту версию или утверждение о новейшей версии Python. Вот полный текст файла:

Python: 3.12.14
OS: Linux
Implementation: CPython
External packages: none
Command: python analysis.py
Expected: n=3; mean=2.0

Команда python analysis.py в этом примере выполняется из папки с analysis.py и hours.csv. Относительное имя hours.csv в коде относится к текущей рабочей папке. Если файл не найден, проверьте её и путь, прежде чем менять зависимости.

Проверяйте выбранный интерпретатор командой python --version, его пакеты — python -m pip freeze, а затем запускайте им же python analysis.py. Все три вызова должны относиться к одному окружению. На Windows команда выбора установленного интерпретатора может называться py; используйте её только если она выбирает нужный вам Python, либо укажите путь явно.

Контрольный вывод: result.txt

Файл содержит результат, который должен получиться при запуске с правильными входными данными и в зафиксированном окружении.

n=3
mean=2.0

Проверить легко: 1 + 2 + 3 = 6, среднее 6 / 3 = 2.0.

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

Последовательность шагов для проверки:

1. Выберите установленный базовый Python и отдельную учебную папку. Сохраните туда исходный CSV и код. Создайте новое окружение командой python -m venv .venv, если python вызывает выбранный интерпретатор; иначе укажите его путь. Не используйте имя уже существующего рабочего окружения.
2. В следующих шагах обращаемся прямо к интерпретатору окружения, поэтому активация не нужна. Для Linux/macOS в Bash используем .venv/bin/python, для Windows в PowerShell — .\.venv\Scripts\python.exe. Выполняйте команды из учебной папки. Наш контрольный запуск был на Linux; здесь приведены также соответствующие пути для Windows по документации venv.
3. Проверьте версию. Linux/macOS: .venv/bin/python --version. Windows PowerShell: .\.venv\Scripts\python.exe --version. Запишите свою фактическую версию и ОС в run-info.txt, не копируйте чужой номер версии как свой.
4. Сохраните список пакетов. Linux/macOS: .venv/bin/python -m pip freeze > requirements.txt. Windows PowerShell: .\.venv\Scripts\python.exe -m pip freeze > requirements.txt. Перенаправление заменяет одноимённый файл: здесь мы создаём его для своего нового примера.
5. Запустите расчёт. Linux/macOS: .venv/bin/python analysis.py. Windows PowerShell: .\.venv\Scripts\python.exe analysis.py. Во всех трёх проверках используется Python именно созданного окружения. Для нашего примера внешние пакеты не устанавливаются.
6. Сравните две строки вывода с result.txt. Сохраните команду и результат проверки рядом с файлами. Совпадение означает, что этот контрольный пример выполнен с ожидаемым выходом.

Документация venv описывает изоляцию от пакетов базового Python по умолчанию. Если при создании включить --system-site-packages, доступ к системным пакетам будет разрешён. Поэтому не обещаем безусловной изоляции при любых настройках. Каталог окружения также не рассматривают как переносимый готовый архив: создайте окружение заново в целевом месте, как рекомендует документация.

Чего не гарантирует этот набор

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

Также стоит помнить: pip freeze не фиксирует версию самого Python — её нужно записывать отдельно. А виртуальное окружение не является переносимым как готовый каталог; его нужно пересоздавать в целевом месте.

Если результат не совпал, возможные причины: другая папка, другое имя файла, другой заголовок в CSV, другая кодировка или случайно изменённый скрипт. Проверять нужно по порядку, начиная с самых очевидных вещей.

Практический итог

Для показанного расчёта мы собрали входные данные, полный скрипт, пустой список внешних зависимостей, описание окружения и ожидаемый вывод. Контрольный запуск в отдельном окружении дал n=3 и mean=2.0. Это проверка конкретного учебного комплекта; она не заменяет обоснование метода исследования.

Для другого проекта состав описания выбирают по фактическим условиям: могут понадобиться версии системных библиотек, параметры программы, версии данных и сведения о случайности расчёта. Не считайте один requirements.txt гарантией переноса любого анализа. Если вывод отличается, сохраните исходники, команду и сообщение об ошибке, а затем выясните конкретное расхождение.

Если хотите подробнее разобраться, как передавать набор файлов и описывать их в сопроводительном документе, посмотрите материал о том, как составить README для исследовательских данных. Он как раз про то, что писать в пояснении к такому набору.

Если нужна помощь с исследовательскими расчётами и описанием анализа, можно обсудить статистический анализ данных. Заранее согласуйте задачу, состав исходных материалов и объём консультации.

Источники

• pip: документация pip freeze
• Python: документация venv

Фото: Christina Morillo / Pexels