완성 모습과 준비물
이번 실습의 결과물은 report.md 보고서와 sample.csv를 변환한 JSON입니다. 이어지는 API·배포·자동화 수업도 같은 도서관 자료를 씁니다. 가상 지역 3곳, 도서관 6곳, 좌석 합계 400석이 출발점입니다.
전체 실습 키트 ZIP을 내려받아 압축을 완전히 푸세요. 파일 미리보기 화면에서 실행하지 않습니다. README.md가 있는 tech-practice 폴더를 편집기로 엽니다. 편집기는 메모장도 가능하지만 코드 편집기를 쓰면 구조를 보기 쉽습니다. 변환 실습에는 Python 3.10 이상이 필요합니다.
휴대전화에서는 교재와 완성 대시보드를 볼 수 있습니다. 파일 편집과 터미널 실행은 PC를 기준으로 설명합니다. 먼저 원본 폴더를 복제해 tech-practice-backup으로 보관하세요.
1단계 · 문서·표·프로그램의 언어 구별하기
| 형식 | 이 실습의 파일 | 잘하는 일 | 주의할 점 |
|---|---|---|---|
| Markdown | report.md | 제목·목록·링크로 보고서 구조 표현 | 편집기마다 표·체크박스 지원이 다를 수 있음 |
| CSV | sample.csv | 열과 행으로 같은 종류의 기록 저장 | 쉼표가 포함된 값은 따옴표로 감싸기 |
| JSON | libraries.json | 프로그램 사이에서 구조화한 데이터 교환 | 큰따옴표, 숫자, null의 차이 지키기 |
한 자료를 세 번 작성하는 것이 아닙니다. CSV를 원본 표로 보존하고, JSON으로 화면을 만들고, Markdown으로 결과를 설명합니다. AI에게도 “보고서용 문장”인지 “컴퓨터가 읽을 JSON”인지 출력 형식을 지정해야 합니다.
2단계 · Markdown으로 검토 메모 쓰기
report.md를 열어 내용을 읽습니다. #는 큰 제목, ##는 절 제목, -는 목록입니다. 아래 예시를 문서 끝에 붙이고 저장하세요. 편집기의 Markdown 미리보기가 있으면 원문과 나란히 비교합니다.
## 추가 검토
- 집계 대상: 해솔시 도서관 3곳
- 좌석 합계: 200석
- [ ] 원본과 합계를 비교했다
- [ ] 출처와 기준일을 적었다
> 좌석 합계만으로 지역의 독서 수요를 판단하지 않는다.
[원본 데이터](./sample.csv)
성공 확인: 제목의 단계가 보이고, 두 개의 할 일과 원본 링크가 구별됩니다. 체크박스가 단순 문자로 보이더라도 원문은 유지됩니다. 실제 공개 URL이 아닌 상대 경로 링크는 파일 위치에 따라 달라집니다.
AI에게 요청하기: “위 Markdown의 숫자와 출처는 바꾸지 말고, 사실·해석·추가 확인을 구분해 문장을 다듬어줘. 근거 없는 원인 설명은 추가하지 마.” 결과를 붙이기 전에 3곳·200석이 유지되는지 확인하세요.
3단계 · CSV의 한 행을 이해하기
sample.csv를 텍스트 편집기로 열어 첫 두 줄을 봅니다. 엑셀에서는 데이터 가져오기를 사용해 UTF-8을 선택하면 한글을 확인하기 쉽습니다.
도서관명,시군구명,열람좌석수,데이터기준일자
해솔중앙도서관,해솔시,120,2026-09-01
첫 줄은 열 이름이고, 다음 줄부터 한 도서관입니다. 열 이름을 바꾸면 뒤의 변환 프로그램이 해당 열을 찾지 못합니다. 이름에 쉼표가 있는 경우 "해솔, 중앙도서관"처럼 값 전체를 감쌉니다. 숫자 120에는 단위 “석”을 붙이지 않습니다.
빈 좌석 값은 모름, 0은 좌석 없음입니다. 이 차이를 지켜야 모르는 값을 합계 0으로 잘못 해석하지 않습니다. 원본을 고칠 때는 사본에서 작업하고, 수정한 행과 이유를 메모하세요.
4단계 · CSV를 JSON으로 변환하기
터미널의 현재 폴더가 tech-practice인지 확인합니다. Windows는 해당 폴더에서 터미널을 열고 아래 첫 명령을 실행합니다. macOS·Linux는 두 번째 명령을 씁니다. 두 명령을 모두 실행할 필요는 없습니다.
py convert_csv.py sample.csv --sample --source "교육용 가상 데이터"
python3 convert_csv.py sample.csv --sample --source "교육용 가상 데이터"
완료: 6행 → dashboard/data/libraries.json이 나오면 성공입니다. JSON 파일의 items 안에는 6개 객체가 있습니다. 프로그램은 수집일을 실행 날짜로 기록하고, CSV의 기준일은 각 행에 보존합니다.
{"name":"해솔중앙도서관","city":"해솔시","seats":120,"date":"2026-09-01"}
JSON에서 "120"은 문자열, 120은 숫자, null은 값 없음입니다. 마지막 항목 뒤에 쉼표를 넣거나 작은따옴표를 쓰면 JSON 문법 오류가 납니다. 이 실습에서는 손으로 대량 수정하지 않고 CSV를 고친 뒤 다시 변환하세요.
5단계 · 숫자를 화면에서 확인하기
Windows는 py server.py, macOS·Linux는 python3 server.py를 실행합니다. 터미널을 켜둔 채 브라우저에서 http://127.0.0.1:8765를 엽니다. 전체 6곳·400석, 지역을 해솔시로 바꾸면 3곳·200석이어야 합니다. 서버 종료는 터미널에서 Ctrl+C입니다.
작은 실험: 사본 CSV에서 첫 행 좌석을 빈 칸으로 바꾸고 다시 변환합니다. 화면을 새로 고치면 전체 6곳·280석·좌석 미상 1곳이 됩니다. 도서관 수는 유지되고, 알려진 좌석만 더해지는 것을 확인하세요.
막혔을 때와 원상 복구
| 증상 | 확인 순서 |
|---|---|
| py 또는 python3를 찾지 못함 | Python 설치 여부 확인 → 터미널 다시 열기 → 버전 확인 |
| 파일을 찾지 못함 | 압축 해제 여부 → 현재 폴더에 convert_csv.py가 있는지 확인 |
| 필수 열 누락 | CSV 첫 줄을 sample.csv의 열 이름과 비교 |
| 숫자 변환 중단 | “120석”, 음수, 임의 문자열 제거 → 원본을 보고 수정 |
| 화면 데이터가 바뀌지 않음 | 변환 성공 메시지 → 브라우저 새로고침 → JSON 파일 확인 |
실험 전 백업한 sample.csv로 교체한 뒤 같은 변환 명령을 다시 실행하면 기본값으로 돌아갑니다. 변환 도중 오류가 나면 기존 JSON은 유지되도록 만들었습니다. 오류를 무시하고 “성공했다”고 보고서에 적지 마세요.
완료 기준과 다음 실습
- Markdown에서 사실·해석·확인할 일을 구분했다.
- CSV 6행과 JSON 6개 항목을 비교했다.
- 전체 400석과 해솔시 200석을 직접 확인했다.
- 빈 값과 0의 차이를 설명할 수 있다.
다음 교재에서는 이 자료를 주소로 요청하고 JSON으로 응답받는 API로 읽습니다. 제출물은 report.md와 결과 화면 한 장이면 됩니다. 공개 게시판에 올릴 때 실제 업무자료는 제외하고 가상 데이터만 사용하세요.
참고 문서
- CommonMark 문법: Markdown의 기본 문법. 표·체크박스는 확장 문법입니다.
- Python csv: 따옴표와 열 구분을 직접 구현하지 않고 CSV 라이브러리를 쓰는 이유.
- Python json: JSON과 Python 자료형의 대응.