Проектирование консольной утилиты на Python: argparse, main() и коды возврата

Цель

Собрать консольную утилиту, которой могут управлять shell-скрипты, задачи CI и агенты: предсказуемые аргументы, текст справки, который и есть документация, структурированные коды возврата и чистые потоки вывода.

Предварительные условия

Пакет с pyproject.toml (см. статью об упаковке), чья логика живёт в импортируемых функциях, отдельно от обработки аргументов.

Шаги

1. Напишите def main(argv: list[str] | None = None) -> int, которая строит парсер, разбирает argv (по умолчанию беря sys.argv[1:]) и возвращает код возврата. Зарегистрируйте её как [project.scripts] tool = "pkg.cli:main" и добавьте if __name__ == "__main__": sys.exit(main()). Тесты тогда вызывают main(["--flag", "x"]) и проверяют возвращаемое значение и перехваченный вывод.
2. Стройте парсер с указанием prog, description и epilog с примерами. Используйте конвертеры type= (int, pathlib.Path либо функцию, вызывающую ArgumentTypeError), чтобы некорректные значения сообщались как ошибки использования, choices= для замкнутых множеств значений и add_subparsers(dest="command", required=True) для утилит с несколькими командами.
3. Следуйте соглашению, описанному в документации sys.exit: Unix-программы обычно используют код 2 для синтаксических ошибок командной строки и 1 для всех остальных ошибок, а 0 означает успех. argparse уже завершается с кодом 2 при некорректных аргументах. Дополнительные коды из sysexits.h (EX_USAGE 64, EX_NOINPUT 66, EX_UNAVAILABLE 69, EX_TEMPFAIL 75) используйте, только если они задокументированы в --help.
4. Пишите результаты в stdout, а диагностику — в stderr. Предлагайте --json, если вывод потребляют другие программы, и --verbose/--quiet, которые задают уровень логирования, вместо того чтобы разбрасывать по коду вызовы print.
5. Перехватывайте ожидаемые сбои (FileNotFoundError, ошибки соединения, исключения предметной области) в main, выводите одну строку в stderr и возвращайте задокументированный код; неожиданным исключениям давайте всплыть дальше, чтобы сохранились трассировка и код возврата 1.
6. Обрабатывайте KeyboardInterrupt, выполняя очистку и возвращая 130 — в соответствии с принятым в shell соглашением «128 плюс номер сигнала», — и подавляйте BrokenPipeError на stdout, чтобы tool | head завершался тихо.
7. Держите справку честной: metavar для читаемых плейсхолдеров, ArgumentDefaultsHelpFormatter, чтобы в справке были видны значения по умолчанию, и тест на то, что --help завершается с кодом 0.

Ожидаемый результат

tool --help документирует весь интерфейс; tool --bad; echo $? выводит 2; проблема со входными данными выводит одну строку в stderr и задокументированный код; вызывающая сторона может ветвиться по коду возврата, не разбирая текст.

Ограничения и основание проверки

Документация sys.exit отмечает, что на большинстве систем коды возврата должны лежать в диапазоне от 0 до 127; значения выше конфликтуют с кодированием сигналов в shell. exit_on_error=False заставляет парсер выбрасывать ArgumentError вместо завершения работы, что подходит для встраивания, но требует собственной обработки ошибок. Соглашения приведены по указанной документации; никаких измерений удобства использования не утверждается.

Завершение работы после Ctrl-C

Shell решает, должно ли прерывание остановить ещё и охватывающий скрипт, проверяя, умер ли дочерний процесс именно от SIGINT, а не читая код возврата. Поэтому утилита, которая перехватывает KeyboardInterrupt и возвращает 130, выглядит как обычное штатное завершение, и for f in *; do tool "$f"; done после каждого Ctrl-C будет продолжать со следующим файлом. Выполните очистку, а затем завершите процесс так, как это сделало бы необработанное прерывание (начиная с версии 3.8 сам Python делает именно так):

except KeyboardInterrupt:
    cleanup()
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    os.kill(os.getpid(), signal.SIGINT)

$? при этом по-прежнему читается как 130, а родительский процесс, ожидающий завершения, видит именно гибель от сигнала. return 130 оставляйте только для случаев, когда точно известно, что вызывающая сторона читает исключительно коды возврата.