설치·실행·검증 문서 쓰기

README를 동료의 첫 실행 절차로 씁니다

작성자의 컴퓨터에서 프로그램이 한 번 실행된 사실과 처음 받은 동료가 실행할 수 있는 상태는 다릅니다. 작성자는 이미 올바른 폴더에 있고 생성 JSON도 남아 있을 수 있습니다. README는 그런 기억을 대신하는 문서입니다. 이 레슨의 제출물은 실제 파일 이름과 명령을 바탕으로 환경, 실행, 입력, 검증, 오류, 제한을 설명하는 첫 실행 안내입니다.

독자는 앞 레슨의 코드를 읽지 않았다고 가정합니다. 시작 위치를 file_cli.py가 있는 압축 해제 폴더로 지정합니다. 저장소 안의 개인 절대 경로를 쓰면 동료의 환경에서 성립하지 않습니다. 이동할 경로를 예시로 제시할 때는 경로가 다를 수 있음을 설명하고 해당 파일이 보이는지 확인하게 합니다. 폴더 위치를 이미 알고 있다는 전제부터 제거합니다.

설치 조건과 확인한 환경을 구분합니다

프로젝트는 Python 3.9 이상과 표준 라이브러리를 사용하며 macOS 또는 Linux의 Bash·Git을 전제로 합니다. Python이 설치되어 있으면 별도 pip 설치는 없습니다. sqlite3 모듈은 Python 코드에서 사용하고 이 CLI 실행에는 sqlite3 명령행 도구가 필요하지 않습니다. 실제 코드에 없는 Flask나 requests를 설치하라고 적지 않습니다. 외부 의존성이 없는 것도 재현 조건의 한 부분입니다.

지원 조건과 검증한 버전은 다른 문장으로 남깁니다. 환경 절에는 필요한 최소 조건을 쓰고 실행 기록에는 python3 --version으로 확인한 버전을 적습니다. 최소 버전 이상 모두를 실행 검증했다는 표현은 피합니다. 이번 작성 환경의 버전 확인은 따라하기 출력에 남깁니다. 동료는 자신의 출력도 기록하여 버전 차이가 문제의 단서인지 판단할 수 있게 합니다.

가상 환경을 만들지 않았으면 만들었다고 쓰지 않습니다. 이번 실습은 표준 라이브러리만 쓰므로 별도 패키지 설치 없이 검증합니다. 추후 외부 의존성을 추가하면 설치 방법·버전 파일·재검증 절차도 함께 바뀌어야 합니다. 지금 문서에 미래 계획을 실행 단계처럼 섞지 않습니다. 개발자의 선택 이유는 제한이나 개선 항목에서 설명합니다.

명령의 순서와 상태 변화를 씁니다

먼저 python3 file_cli.py import data/import.csv records.json으로 가상 CSV를 가져옵니다. 다음 lookup records.json b01으로 저장 기록을 확인하고 report records.json으로 공개 보고서를 생성합니다. import 전에는 records.json이 없어도 됩니다. 가져오기 뒤 생성되는 파일인지 제공 파일인지 명시하면 독자가 빈 JSON을 임의로 만들 필요가 없습니다. 테스트도 처음 상태를 기준으로 실행합니다.

성공 기준은 첫 명령의 IMPORTED|2, 조회의 제목 책, 산책과 pages 0, 공개 보고서의 rows 두 건·completed 한 건·total_pages 0입니다. 제목에는 쉼표가 있으므로 CSV의 인용 필드가 보존되는지도 보여 줍니다. 완료 기록의 쪽수가 0이라는 경계를 문서와 검사에서 함께 확인합니다. 실행할 때 변하는 절대 경로나 시간은 고정 기대값으로 제시하지 않습니다.

입력 계약에는 헤더 id,title,pages,cost,completed와 순서를 적습니다. 쪽수·금액은 0 이상 정수이고 완료 표시는 0 또는 1입니다. CSV가 기존 JSON에 합쳐지는지 전체 교체되는지 알려야 사용자가 자료 손실을 예상할 수 있습니다. 헤더만 있는 CSV는 정상 빈 목록으로 교체한다는 경계도 적습니다. 실제 개인 자료 대신 제공된 가상 파일로 먼저 확인하게 합니다.

검증 명령은 검증 범위를 설명합니다

python3 -m unittest discover -s tests -p 'test_cli.py'는 새 파일 명령의 일곱 사례를 확인합니다. python3 clean_run.py는 필요한 파일만 새 폴더에 복사해 가져오기·조회·보고서를 실행합니다. bash check.sh는 오래된 작업 공간 검사를 실행합니다. 이 세 명령이 HTTP 요청이나 학습자의 실제 Git 기록까지 모두 검증하는 것은 아닙니다. 범위가 다른 명령을 모두 전체 테스트라고 부르지 않습니다.

미션의 bash check-reproduction.sh는 기존 검사, 전체 unittest, 새 폴더 검사, 독립 Git 예시 기록 검사를 순서대로 실행합니다. HTTP 소켓과 커밋 실행이 필요하므로 현재 작성 환경에서 전체 성공을 주장하지 않습니다. 외부 검증 대기와 로컬에서 이미 확인한 항목을 나누어 적습니다. 문서에 통과 개수를 쓰려면 실제로 실행한 테스트의 마지막 개수와 결과를 근거로 삼습니다.

자동 검사는 문서가 있다는 사실이나 특정 항목을 적었는지만 확인할 수 있습니다. 동료가 README만 보고 실행하는 과정은 별도로 관찰합니다. 어느 명령에서 막혔는지, 어떤 입력을 사용했는지, 해소에 필요했던 설명이 무엇인지 기록합니다. 아직 동료 검증을 하지 않았다면 미실시라고 적습니다. 시도하지 않은 결과를 통과라고 꾸미지 않습니다.

오류 안내는 다음 확인 행동을 줍니다

NOT_FOUND는 지정 ID가 없다는 업무 결과이며 종료 코드 1입니다. ERR_FILE|FileNotFoundError는 원본 CSV 경로나 필요한 SQL 파일을 찾지 못한 경우 등 파일 처리 실패를 뜻합니다. 현재 위치와 실제 파일을 확인하도록 안내합니다. argparse의 required 오류는 필요한 인자를 빠뜨렸다는 신호입니다. 입력 경로를 바꾸기 전에 명령 구조가 맞는지 확인하게 합니다.

ERR_FILE|ValueError는 CSV·JSON 내용의 계약을 살핍니다. 헤더 순서, 음수 쪽수, 중복 ID 같은 검증 대상을 안내하되 실제 개인 자료를 문서에 붙이지 않습니다. 손상 파일을 단순 삭제하고 재실행하라는 안내는 기존 상태를 잃을 수 있습니다. 가상 자료로 원인을 재현하고 원본 보존 여부를 확인한 뒤 수정합니다. 종료 코드와 출력 채널도 기록하면 오류 유형을 구별하기 쉽습니다.

프로그램의 한계를 구체적으로 남깁니다

이 프로젝트는 단일 사용자의 로컬 파일 도구입니다. 동시 쓰기 충돌 해결, 로그인, 운영 배포, 정전 내구성을 제공하지 않습니다. HTTP 관찰은 서버 시작 시 만든 읽기 전용 보고서 스냅샷입니다. 실행 중 파일을 바꿔도 기존 스냅샷이 자동 갱신되지는 않습니다. 기능을 사용자가 잘못 기대하지 않도록 실제 구현의 경계를 적습니다.

lab.kind가 none인 이번 레슨은 코드 채점 대신 README 초안을 제출합니다. 환경·설치·처음 위치·세 실행 명령·입력 계약·검증 범위·오류·제한 항목을 포함합니다. 미션 starter의 빈 README를 채우고 동료에게 설명 없이 전달할 수 있는지 검토합니다. 문장 길이보다 실행 가능한 명령과 서로 맞는 결과가 기준입니다. 관련 협업 원고는 리뷰 질문을 보충하는 더 읽기로 연결합니다.

README를 변경할 때는 실행 명령을 다시 확인합니다. 새 CLI가 생겼는데 예전 app.py 한 건 설명만 남아 있으면 문서의 제목과 실제 쓰임이 어긋납니다. 반대로 기존 계약을 삭제한 것처럼 쓰면 이전 기능을 계속 쓰는 사람을 혼란스럽게 합니다. 새 명령의 책임과 기존 진입점 보존을 함께 알리고 Git 변경 묶음에도 해당 문서 수정을 포함합니다.

import platform
print("Python", platform.python_version())

Python 3.13.0

import csv, io
text = 'id,title,pages,cost,completed\nb01,"책, 산책",0,1200,1\nb02,한글 제목,8,0,0\n'
rows = list(csv.DictReader(io.StringIO(text)))
print(len(rows), rows[0]["title"])
print(sum(int(r["pages"]) for r in rows if r["completed"] == "1"))

2 책, 산책
0

checks = {"파일 CLI": "7개 통과", "HTTP 전체": "외부 검증 대기", "동료 재현": "미실시"}
for name, status in checks.items():
    print(name + ": " + status)

파일 CLI: 7개 통과
HTTP 전체: 외부 검증 대기
동료 재현: 미실시

python3 file_cli.py import data/import.csv records.json
python3 file_cli.py lookup records.json b01
python3 file_cli.py report records.json