종료 코드가 진실을 말하게 한다

목표

셸 한 줄짜리 검사를 "운영 도구" 로 만든다 — 종료 코드 0·1·2 약속, 표준 출력과 표준 오류의 분리, 로그 수준, JSON 출력, 임포트 가능한 main().

왜 중요한가

cron 과 CI 는 화면을 읽지 않고 종료 코드만 본다. 진단 메시지가 표준 출력에 섞이면 파이프라인의 다음 단계가 깨진다. 트레이스백은 만든 사람에게는 정보지만 새벽에 알림을 받은 사람에게는 소음이다. 이 실습의 도구는 작지만, 여기서 익힌 모양이 그대로 수백 줄짜리 운영 도구의 뼈대가 된다. 표준 라이브러리(argparse·logging·json·pathlib)만 쓴다.

단계

1. /root/pyops/cli/dircheck.py 를 만든다. 위치 인자 path, 옵션 --min-files(int, 기본 1)·--max-age-hours(float, 기본 24)·--json·-v/--verbose 를 argparse 로 정의한다. python3 dircheck.py --help 가 종료 코드 0 으로 끝나야 한다.
2. 디렉터리 안의 파일 수와 가장 오래된 파일의 나이(시간)를 재서 files=<n> oldest_age_hours=<x> ok=<true|false> 한 줄을 표준 출력에 낸다. 조건은 파일 수 ≥ --min-files 이고 가장 오래된 파일의 나이 ≤ --max-age-hours 다.
3. 조건을 만족하면 종료 코드 0, 위반이면 1 로 끝낸다. 빈 디렉터리는 files=0 이고 --min-files 1 이면 위반이다.
4. 경로가 없거나 디렉터리가 아니면 트레이스백 없이 표준 오류에 한 줄을 적고 종료 코드 2 로 끝낸다. 이때 표준 출력에는 아무것도 쓰지 않는다.
5. logging 을 붙인다. 기본은 INFO, -v 면 DEBUG. -v 로 돌리면 DEBUG 가 포함된 줄이 표준 오류에만 나오고 표준 출력에는 결과 한 줄만 남아야 한다.
6. --json 이면 표준 출력에 JSON 객체 한 개만 낸다. 키는 path·files·oldest_age_hours·ok 이고 ok 는 불리언, files 는 정수다. 종료 코드 약속은 그대로다.
7. 경로를 여러 개 받는다(nargs="+"). 디렉터리마다 결과 한 줄(또는 JSON 이면 배열 하나)을 내고, 종료 코드는 가장 나쁜 것(2 > 1 > 0)으로 끝낸다.
8. main(argv=None) -> int 함수로 정리하고 파일 맨 아래에서만 sys.exit(main()) 을 부른다. import dircheck 만으로는 아무것도 실행되지 않아야 하고, dircheck.main(["<디렉터리>"]) 가 정수를 돌려줘야 한다.

참고

• 나이는 time.time() - path.stat().st_mtime 을 3600 으로 나눈 값이다. 소수 셋째 자리까지면 충분하다.
• 시험용 디렉터리는 직접 만든다: mkdir -p /root/pyops/cli/samples/ok /root/pyops/cli/samples/empty && touch /root/pyops/cli/samples/ok/a.txt
• 흔한 실수: 진단을 print() 로 찍어 표준 출력을 더럽히는 것, 예외를 잡아 놓고 0 으로 끝내는 것, parse_args() 를 main() 밖(모듈 최상단)에서 부르는 것.

단계 8개

1. 인자 정의와 --help
2. 파일 수와 가장 오래된 나이를 잰다
3. 0 과 1 의 약속
4. 도구 오류는 2, 트레이스백은 없이
5. 진단은 표준 오류로, -v 로 수준 조절
6. 기계가 읽을 결과는 JSON 으로
7. 여러 디렉터리, 가장 나쁜 코드
8. 임포트해도 실행되지 않는 도구