24강. 최종 프로젝트: 게임 전투 로그 분석 및 밸런스 리포트 도구

?1. 이번 강의에서 해결할 문제

앞에서 만든 데이터 모델, reader, 통계, 테스트와 CLI를 하나의 실행 흐름으로 연결합니다. 입력 형식과 출력 형식이 달라도 같은 지표를 안정적으로 계산해야 합니다.

✓2. 학습 목표

✓이 강의를 마치면

• JSON·CSV 전투 로그를 공통 모델로 읽습니다.
• 전체·플레이어·몬스터·스킬별 지표를 계산합니다.
• JSON·CSV 리포트를 저장하고 pytest 테스트 3개 이상으로 검증합니다.

◇3. 핵심 개념

최종 구조는 입력 → 검증 모델 → 분석 → 리포트 직렬화 → CLI로 의존 방향을 한쪽으로 유지합니다. 각 계층은 Python 객체를 주고받고 파일 형식과 argparse는 경계에만 둡니다.

최종 폴더 구조

game-log-analyzer/
├─ battle_analyzer/
│  ├─ __init__.py
│  ├─ models.py
│  ├─ readers.py
│  ├─ analysis.py
│  ├─ writers.py
│  └─ cli.py
├─ data/battles.json
├─ tests/test_analyzer.py
├─ main.py
└─ requirements.txt

</>4. 단계별 코드 예시

파일 경로: battle_analyzer/analysis.py

battle_analyzer/analysis.py

from collections import defaultdict

from .models import BattleRecord


def metrics(records: list[BattleRecord]) -> dict[str, float | int]:
    count = len(records)
    wins = sum(record.result == "win" for record in records)
    return {
        "battle_count": count,
        "average_damage": round(
            sum(record.damage for record in records) / count, 2
        ) if count else 0.0,
        "win_rate": round(wins / count, 4) if count else 0.0,
    }


def group_metrics(records: list[BattleRecord], field: str) -> dict[str, dict]:
    groups = defaultdict(list)
    for record in records:
        groups[getattr(record, field)].append(record)
    return {name: metrics(group) for name, group in sorted(groups.items())}


def build_report(records: list[BattleRecord]) -> dict:
    return {
        "overall": metrics(records),
        "players": group_metrics(records, "player"),
        "monsters": group_metrics(records, "monster"),
        "skills": group_metrics(records, "skill"),
    }

파일 경로: battle_analyzer/writers.py

battle_analyzer/writers.py

import csv
import json
from pathlib import Path


def write_report(report: dict, path: Path, output_format: str) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    if output_format == "json":
        with path.open("w", encoding="utf-8") as file:
            json.dump(report, file, ensure_ascii=False, indent=2)
        return

    rows = []
    for category, groups in report.items():
        if category == "overall":
            groups = {"all": groups}
        for name, values in groups.items():
            rows.append({"category": category, "name": name, **values})

    with path.open("w", encoding="utf-8", newline="") as file:
        writer = csv.DictWriter(
            file,
            fieldnames=["category", "name", "battle_count", "average_damage", "win_rate"],
        )
        writer.writeheader()
        writer.writerows(rows)

파일 경로: battle_analyzer/cli.py

battle_analyzer/cli.py

import argparse
import logging
from pathlib import Path

from .analysis import build_report
from .readers import read_csv, read_json
from .writers import write_report


def build_parser():
    parser = argparse.ArgumentParser(description="게임 전투 로그 분석기")
    parser.add_argument("--input", required=True, type=Path)
    parser.add_argument("--output", required=True, type=Path)
    parser.add_argument("--format", choices=("json", "csv"), default="json")
    parser.add_argument("--verbose", action="store_true")
    return parser


def main(argv=None):
    args = build_parser().parse_args(argv)
    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.INFO)
    try:
        reader = {".json": read_json, ".csv": read_csv}[args.input.suffix.lower()]
        records = reader(args.input)
        report = build_report(records)
        write_report(report, args.output, args.format)
    except (FileNotFoundError, KeyError, TypeError, ValueError) as error:
        logging.error("분석 실패: %s", error)
        return 1
    logging.info("%d건 분석 완료: %s", len(records), args.output)
    return 0

파일 경로: tests/test_analyzer.py

tests/test_analyzer.py

import json

import pytest

from battle_analyzer.analysis import build_report, metrics
from battle_analyzer.models import BattleRecord
from battle_analyzer.readers import read_json
from battle_analyzer.writers import write_report


def record(player="Knight", monster="Slime", skill="Slash", damage=100, result="win"):
    return BattleRecord(player, monster, skill, damage, result)


def test_metrics_calculates_average_and_win_rate():
    result = metrics([record(damage=80), record(damage=120, result="loss")])
    assert result["battle_count"] == 2
    assert result["average_damage"] == pytest.approx(100.0)
    assert result["win_rate"] == pytest.approx(0.5)


def test_report_groups_player_monster_and_skill():
    report = build_report([record(), record(player="Mage", skill="Fireball")])
    assert set(report["players"]) == {"Knight", "Mage"}
    assert report["monsters"]["Slime"]["battle_count"] == 2
    assert report["skills"]["Fireball"]["average_damage"] == 100


def test_json_input_and_output(tmp_path):
    source = tmp_path / "battles.json"
    output = tmp_path / "report.json"
    source.write_text(json.dumps([{
        "player": "Knight", "monster": "Slime", "skill": "Slash",
        "damage": 80, "result": "win"
    }]), encoding="utf-8")
    report = build_report(read_json(source))
    write_report(report, output, "json")
    assert json.loads(output.read_text(encoding="utf-8"))["overall"]["battle_count"] == 1

파일 경로: main.py

main.py

from battle_analyzer.cli import main

if __name__ == "__main__":
    raise SystemExit(main())

PowerShell · 최종 실행

Set-Location C:\dev\game-log-analyzer
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe .\main.py --input .\data\battles.json --output .\reports\balance.json --format json
.\.venv\Scripts\python.exe .\main.py --input .\data\battles.csv --output .\reports\balance.csv --format csv --verbose
Get-Content .\reports\balance.json

→5. 코드가 동작하는 이유

reader는 두 입력 형식을 BattleRecord로 통일하고 analysis는 파일을 모른 채 통계를 계산합니다. getattr은 지정 필드별 그룹화를 공통화합니다. writer는 동일 리포트를 중첩 JSON 또는 평면 CSV 행으로 직렬화하며 CLI가 전체 흐름과 종료 코드를 조정합니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 입력 확장자와 실제 내용 불일치: reader 선택 전 suffix를 확인하고 오류 메시지에 경로를 포함합니다.
• 몬스터 승률 의미가 모호함: 이 리포트에서는 “해당 몬스터를 상대한 플레이어의 승률”이라고 README에 정의합니다.
• 테스트가 실제 reports를 덮어씀: tmp_path만 사용합니다.
• 오류를 잡고 성공 코드 반환: 실패 시 1을 반환해 자동화가 감지하게 합니다.

✎7. 직접 실습

✎최종 완료 조건

1. JSON과 CSV에 동일한 전투 5건 이상을 준비합니다.
2. 플레이어 2명, 몬스터 2종, 스킬 3종 이상의 그룹 통계를 확인합니다.
3. 평균 피해, 승률, 전투 횟수가 손계산과 일치하는지 비교합니다.
4. JSON·CSV 리포트를 각각 저장합니다.
5. 최소 3개 pytest 테스트를 통과시킵니다.
6. 누락 파일과 지원하지 않는 확장자에서 종료 코드 1을 확인합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. 파일 reader와 통계 함수를 분리하면 어떤 테스트가 쉬워지나요?
2. 중첩 리포트를 CSV로 저장할 때 왜 평면 행으로 바꾸나요?
3. CLI가 실패 시 0이 아닌 종료 코드를 반환해야 하는 이유는 무엇인가요?

■9. 핵심 요약

■핵심 요약

Python 기초 문법을 입력, 모델, 분석, 출력, CLI와 테스트라는 실제 구조로 연결했습니다. 완성 도구는 JSON·CSV 전투 로그를 읽고 전체·플레이어·몬스터·스킬별 지표를 계산해 두 형식의 리포트로 저장합니다.