Надёжные CLI-скрипты: коды выхода, логирование, ретраи, сигналы

Коды выхода: контракт с ОС

Каждая система автоматизации — cron, CI, Kubernetes, Makefile — делает одно допущение о твоём скрипте: код 0 значит «сработало», ненулевой — «нет». Когда ты нарушаешь этот контракт, вся цепочка алертов ломается вместе с ним. Процесс сообщает об успехе или сбое ровно одним числом — своим кодом выхода. 0 значит успех; что угодно ненулевое значит сбой. Это число не украшение — это единственное, на что смотрят cron, CI-раннеры, &&-цепочки, systemd и любой оркестратор, чтобы решить, запускать ли следующий шаг или поднимать алерт. backup.sh && upload.sh запустит upload, только если backup вышел с 0. CI помечает шаг красным только при ненуле. Так что код выхода и есть сигнал успеха, и ошибиться в нём — это и есть способ, которым упавшая задача рапортует зелёным.

import sys, logging

log = logging.getLogger("export")

def main() -> int:
    try:
        data = fetch_export()      # may raise on a 500
        write_atomic("/data/export.json", data)
        return 0                   # success — and only here
    except Exception:
        log.exception("export failed")  # ERROR + traceback to stderr
        return 1                   # FAILURE is now visible to cron/CI

if __name__ == "__main__":
    sys.exit(main())              # the return value becomes the exit code

Смертельный паттерн — обратный: поймать исключение, print сообщение и дать main свалиться с конца. Функция, свалившаяся с конца, возвращает None; sys.exit(None) завершается нулём. Ты только что сказал ОС, что задача удалась, тогда как она на самом деле упала. Либо дай исключению пробросить (Python завершится ненулём с трейсбэком), либо явно вызови sys.exit(1). Резервируй отдельные коды (2, 3, …) только если вызывающий реально ветвится на том, какой именно сбой — иначе 1 достаточно.

Логирование, а не print: правило скрипта без присмотра

print пишет в stdout без уровня, без таймстампа и без контроля маршрутизации. В интерактивной сессии это нормально; в cron-задаче это невидимо — терминала нет, а stdout часто перехватывается как данные задачи или отбрасывается. Модуль logging даёт то, что нужно скрипту без присмотра: уровни (DEBUG/INFO/WARNING/ERROR), таймстампы и адресат, настроенный один раз. Два важных правила: диагностика идёт в stderr, реальный вывод — в stdout (чтобы нижестоящий | jq видел чистые данные, а не строки лога), а уровень задаётся флагом или переменной окружения, чтобы можно было поднять DEBUG, не правя код.

import logging, os, sys

logging.basicConfig(
    level=os.environ.get("LOG_LEVEL", "INFO"),
    format="%(asctime)s %(levelname)s %(name)s %(message)s",
    stream=sys.stderr,            # diagnostics to stderr; stdout stays clean for data
)
log = logging.getLogger("export")

log.info("starting export run")          # routine progress
log.error("upstream returned 503")       # a problem worth alerting on
log.exception("unexpected failure")      # ERROR + full traceback, inside an except block

log.exception — то, за чем тянешься внутри блока except: он логирует на ERROR и прикрепляет трейсбэк, что ровно и нужно отправить в агрегатор логов. Когда видишь cron-задачу с print-ами для диагностики, спроси себя: куда реально уходит этот вывод и кто читает его в 3 часа ночи при сбое? print-отладка cron-задачи не даёт ничего grep-абельного; структурированные логи ищутся, отправляются и стыкуются прямо с observability.

Ретраи с backoff: переживаем временный I/O

Сетевые и API-вызовы падают временно: таймаут, 503, rate-limit. Надёжная реакция — не «сдаться» и не «ретраить вечно», а ограниченный ретрай с экспоненциальным backoff и джиттером. Жди ~1с, потом ~2с, потом ~4с, каждое со случайной добавкой, чтобы флот скриптов не ретраил в унисон и не затоптал восстанавливающийся сервис, вплоть до лимита попыток. Два жёстких ограничения: ретраить только идемпотентные или временные операции и уважать Retry-After, когда сервер его шлёт.

import time, random, logging

log = logging.getLogger("export")

def with_backoff(op, *, attempts=5, base=1.0, cap=30.0):
    for i in range(attempts):
        try:
            return op()
        except TransientError as e:           # ONLY transient/retryable errors
            if i == attempts - 1:
                raise                          # budget exhausted -> let it fail
            delay = min(cap, base * 2 ** i) + random.uniform(0, 1)  # backoff + jitter
            log.warning("attempt %d failed (%s), retrying in %.1fs", i + 1, e, delay)
            time.sleep(delay)

Асимметрия — в этом весь смысл. Ограниченный backoff превращает временный 503 в не-событие — третья попытка проходит, и никто не замечает. Неограниченный или мгновенный ретрай делает обратное: он молотит уже задыхающийся сервис, превращая мигание в аварию. А ретрай неидемпотентного POST (списать карту, послать письмо) может применить побочный эффект дважды — так что ретрай чтения и идемпотентные записи, а неидемпотентные операции сделай идемпотентными через ключ, прежде чем их ретраить.

Сигналы и атомарная запись: умираем чисто

Процесс без присмотра убивают. Оркестратор шлёт SIGTERM (сигнал ОС с просьбой завершиться корректно), чтобы его остановить; человек шлёт SIGINT (сигнал прерывания, он же Ctrl-C) через терминал. По умолчанию оба разматывают стек — но если ты на середине записи файла, дефолт оставляет обрезанный файл, удержанный лок или temp-каталог, забитый мусором. Две дополняющие защиты: обработать сигнал (или опереться на try/finally + контекстные менеджеры), чтобы сбросить буферы и прибраться, и никогда не писать настоящий файл на месте — пиши temp-файл, затем os.replace, который атомарен на POSIX-файловой системе. Kill в любой момент оставит либо старый целый файл, либо новый целый файл, но никогда полузаписанный.

import os, signal, tempfile, json

def write_atomic(path: str, obj) -> None:
    d = os.path.dirname(path) or "."
    fd, tmp = tempfile.mkstemp(dir=d)          # same filesystem -> rename is atomic
    try:
        with os.fdopen(fd, "w") as f:
            json.dump(obj, f)
            f.flush()
            os.fsync(f.fileno())               # durable before the swap
        os.replace(tmp, path)                  # atomic: readers see old OR new, never partial
    except BaseException:
        os.unlink(tmp)                         # killed mid-write -> no orphan temp
        raise

def handle_term(signum, frame):
    raise SystemExit(143)                      # turn SIGTERM into a clean unwind (128+15)

signal.signal(signal.SIGTERM, handle_term)     # finally/with blocks now run on stop

Поскольку os.replace атомарен, окна для kill, в котором можно было бы увидеть частичный файл, просто не существует. Соедини это с идемпотентностью — скрипт будет перезапущен (ретрай, ручной перезапуск, наложившийся тик cron), так что check-before-act, пиши атомарно и бери lockfile, чтобы отказать второму одновременному запуску. Идемпотентный скрипт можно безопасно запустить дважды; неидемпотентный портит состояние на втором.