Первый Python-скрипт для коллеги: от sys.argv до пакета

Скрипт, который работает только на вашем ноутбуке, — это ещё не инструмент. У коллеги другая версия Python, нет установленных библиотек, файлы лежат в других папках, а пути к данным вы зашили прямо в код. В итоге простая просьба «прогони мой скрипт» превращается в получасовую переписку. Ниже — что сделать с обычным .py-файлом, чтобы его можно было отдать другому человеку и он запустился с первой попытки. Займёт это 30–60 минут, всё показано для Python 3.11+.

Что должно быть до начала

Прежде чем оформлять скрипт, проверьте, что у вас есть:

• Python 3.10 или новее (проверьте командой python --version; если у вас и python, и python3 — уточните, какой отвечает за нужную версию).
• Сам рабочий скрипт — пусть даже в одном файле.
• Понимание, какие сторонние библиотеки он использует (например, requests, pandas). Стандартная библиотека — os, json, argparse — устанавливать не нужно.
• Git-репозиторий или хотя бы папку, которую вы целиком передадите коллеге.

Идея простая: коллеге нельзя рассчитывать на то, что «и так понятно». Всё, что вы держите в голове, надо вынести в текст — в README, в аргументы командной строки и в файл зависимостей.

Шаг 1. Убрать жёстко зашитые пути и параметры

Самая частая причина, по которой чужой скрипт падает, — строки вроде path = "/Users/ivan/data/report.csv". У коллеги такого пути нет. Вынесите значения в аргументы командной строки через модуль argparse из стандартной библиотеки.

import argparse


def parse_args():
    parser = argparse.ArgumentParser(
        description="Считает статистику по CSV-файлу продаж."
    )
    parser.add_argument(
        "input_file",
        help="путь к входному CSV-файлу",
    )
    parser.add_argument(
        "--output",
        default="result.json",
        help="куда сохранить результат (по умолчанию result.json)",
    )
    parser.add_argument(
        "--limit",
        type=int,
        default=100,
        help="сколько строк обработать",
    )
    return parser.parse_args()


if __name__ == "__main__":
    args = parse_args()
    print(f"Читаю {args.input_file}, лимит {args.limit}")

Проверка: запустите python script.py --help. Должно появиться описание и список аргументов. Теперь коллега увидит, что от него хотят, даже не читая код.

Строка if __name__ == "__main__": нужна, чтобы код запуска не срабатывал при импорте файла как модуля — это спасёт, когда скрипт вырастет и его функции захотят переиспользовать.

Шаг 2. Зафиксировать зависимости

Если скрипт использует сторонние библиотеки, у коллеги их не окажется. Соберите их в файл requirements.txt в корне проекта:

requests==2.31.0
pandas==2.2.0

Точные версии (==) лучше, чем «любая свежая»: через полгода новая мажорная версия pandas может сломать ваш код, и коллега получит ошибку, которой у вас не было. Узнать установленные версии можно командой pip freeze, но она вываливает все пакеты окружения — из них выберите только те, что реально нужны скрипту, а не копируйте весь список.

Правило, экономящее часы чужого времени: если запуск требует чего-то, кроме python script.py, это «что-то» должно быть написано в README, а не жить у вас в голове.

Проверка: создайте чистое виртуальное окружение и установите зависимости с нуля.

python -m venv .venv
source .venv/bin/activate    # в Windows: .venv\Scripts\activate
pip install -r requirements.txt

Если после этого скрипт запускается — значит, вы ничего не забыли. Если падает с ModuleNotFoundError, недостающий пакет надо дописать в requirements.txt.

Шаг 3. Написать README

README — первое, что откроет коллега. Он отвечает на четыре вопроса: что это, что нужно установить, как запустить, что получится на выходе. Достаточно простого текста:

# Статистика продаж

Считает агрегаты по CSV-файлу с продажами.

## Установка

    python -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt

## Запуск

    python script.py данные.csv --output итог.json --limit 500

На выходе — JSON-файл с суммами по каждому менеджеру.

Проверка: дайте README прочитать человеку, который не видел скрипт. Если он может запустить, не задав вам ни одного вопроса, — README готов.

Шаг 4. Сообщать об ошибках понятно

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

import sys
from pathlib import Path


def main():
    args = parse_args()
    input_path = Path(args.input_file)

    if not input_path.exists():
        print(f"Файл не найден: {input_path}", file=sys.stderr)
        sys.exit(1)

    # дальше основная логика


if __name__ == "__main__":
    main()

Код выхода sys.exit(1) — не косметика: если скрипт кто-то запустит из другого процесса или CI, ненулевой код скажет, что запуск провалился. При успехе процесс сам вернёт 0.

Если не получилось

Типичные ошибки, которые увидит коллега, и что с ними делать:

• ModuleNotFoundError: No module named 'pandas' — зависимость не установлена или её нет в requirements.txt. Дополните файл и попросите переустановить.
• python: command not found — на машине команда называется python3. Укажите это в README или используйте python3 в примерах.
• SyntaxError при запуске рабочего кода — почти всегда старая версия Python. Синтаксис вроде match или | в аннотациях типов требует 3.10+. Проверьте python --version у коллеги.
• Permissiondenied при записи результата — путь --output ведёт в папку, куда нет прав на запись. Пусть укажет каталог, где может создавать файлы.
• Кракозябры в консоли на Windows — проблема кодировки при чтении файла. Открывайте файлы явно: open(path, encoding="utf-8"), не полагаясь на кодировку по умолчанию.

Когда одного файла мало

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

Упаковка в устанавливаемый пакет через pyproject.toml и точки входа — отдельная тема, здесь мы её не разворачиваем. Для первого скрипта достаточно трёх файлов: сам код, README и requirements.txt.

Что сделать дальше

Когда базовая передача работает, следующие шаги повышают надёжность:

• Добавьте один-два примера входных данных в папку examples/ — коллега проверит запуск, не подставляя свои файлы.
• Закрепите версию Python в README (например, «протестировано на 3.11»).
• Замените print на модуль logging, когда скрипт начнут запускать по расписанию, — так проще разбирать, что произошло ночью.
• Если код перерастёт один файл — посмотрите официальный гайд по упаковке на packaging.python.org и переезжайте на pyproject.toml.