시험 복습 시간표 플래너

--- name: exam-revision-timetable-planner description: 시험 날짜, 과목 가중치, 자신감을 바탕으로 시험 전까지의 일일 복습 시간표를 만듭니다. 학습 시간을 집중 세션으로 나누고, 약한 과목과 비중이 큰 과목에 더 많은 시간을 할애하며, 과목을 교차 배치하고, 각 시험 전 마지막 주에는 문제 풀이로 전환하며, 시험 전날에는 시간을 재서 모의고사를 봅니다. 또한 휴식일과 쉬는 날을 존중합니다. 주제별 세션 수가 너무 적거나 시험이 연속으로 있는 경우를 알려줍니다. --self-test 옵션이 있는 표준 라이브러리 Python 플래너를 포함합니다. --- # 시험 복습 시간표 플래너 여러분이 스트레스가 많은 시험 기간을 현실적인 계획으로 바꿔줍니다: 마지막 시험까지 매일 각 세션에서 어떤 과목을 공부할지. 증거 기반 기법(분산 학습, 인출 연습, 교차 학습, 모의고사)을 사용하고, 휴식과 수면을 포함한 인간적인 계획을 유지하며, 모든 것을 할 시간이 충분하지 않을 때의 절충안을 명확히 보여줍니다. ## 이 스킬의 파일들 - `scripts/revision_plan.py` - 과목 CSV를 읽고 과목 표, 일일 시간표, 분석 결과를 출력합니다 (Python 3 표준 라이브러리만 사용) - `references/study-techniques.md` - 세션 내에서 무엇을 할지: 인출 연습, 분산 학습, 교차 학습, 모의고사, 그리고 피해야 할 것들 - `references/scheduling-rules.md` - 스크립트가 우선순위, 목표, 세션 유형, 분석 결과를 할당하는 방법과 조정 방법 - `templates/revision-plan.md` - 제공할 계획: 개요, 주간 시간표, 세션 루틴, 체크인 시점 - `examples/winter-exams.csv` - 12월 2일부터 11일 사이의 대학 시험 5개와 주제 수 ## 작업 흐름 ### 1. 사실 수집 각 시험에 대해 물어보세요: 과목, 날짜, 비중(학점, 최종 성적 비율, 또는 중요도 1-5), 자신감(1(부족)부터 5(탄탄)까지), 그리고 주제 또는 챕터 수. 그런 다음 첫 복습일, 주중과 주말의 현실적인 시간(수업, 일, 통근 후), 선호하는 세션 길이(기본 50/10, 집중력이 낮으면 25/5 포모도로), 주간 휴식일, 그리고 이미 정해진 날짜들을 물어보세요. ### 2. 플래너 실행 ``` python3 scripts/revision_plan.py examples/winter-exams.csv --start 2026-11-16 --weekday-hours 3 --weekend-hours 5 --rest-day Sun --off 2026-11-21 --day-start 16:00 python3 scripts/revision_plan.py my-exams.csv --start 2026-05-04 --session-min 25 --break-min 5 --json python3 scripts/revision_plan.py --self-test ``` 종료 코드 1은 HIGH 분석 결과(주제 수보다 적은 세션), 2는 잘못된 입력을 의미합니다. ### 3. 절충안 수정 UNDER_COVERED 또는 TIGHT의 경우: 시간을 추가하거나, 더 일찍 시작하거나, 강한 과목의 목표를 낮추거나, 수익이 낮은 주제를 훑어보기로 합의하세요(교과 과정 가중치 또는 모의고사 빈도 사용). BACK_TO_BACK의 경우: 두 번째 과목의 문제 풀이를 첫 번째 시험 전으로 옮기세요. 학생과 계획을 확인하세요: 안 좋은 날에도 실행 가능한가요? 매일 밤 벼락치기보다는 여유를 두세요. ### 4. 전달 `templates/revision-plan.md`를 채우세요: 개요 표, 주간 시간표, `references/study-techniques.md`의 세션 루틴, 그리고 자신감을 다시 평가하고 스크립트를 다시 실행할 두 개의 체크인 날짜. ## 예시 결과 `examples/winter-exams.csv`에 대해 11월 16일부터 주중 3시간, 토요일 5시간, 일요일과 11월 21일 휴무: 25일, 50분 세션 57개(47.5시간). 유기화학(가중치 5, 자신감 2)과 미시경제학(4, 2)은 각각 15개와 16개 세션, 유럽사(3, 4)는 6개 세션. 각 과목은 문제 풀이로 끝나고 시험 전날 시간을 재는 모의고사를 봅니다. 분석 결과: 통계학(8개 주제에 10개 세션)과 유럽사(6개 주제에 6개 세션)는 TIGHT, 유럽사와 미시경제학은 12월 7일과 8일에 연속으로 있어 BACK_TO_BACK입니다. ## 규칙 - 학생이 실제로 가진 시간으로 계획하세요. 원하는 시간이 아니라요; 수면을 보호하세요(시험 전 밤늦은 세션 금지). - 모든 세션은 인출 연습(질문, 빈 페이지 회상, 플래시카드)으로 끝나야 하며, 단순히 다시 읽거나 형광펜으로 표시하는 것만으로는 안 됩니다. - 주당 최소 하루 휴식일 또는 이틀 반나절을 유지하세요; 번아웃은 하루를 잃는 것보다 더 큰 비용이 듭니다. - 깨진 계획을 따르지 말고 각 체크인 또는 시험 후에 다시 계획하세요. - 학생의 채점 과제를 대신 해주지 마세요; 계획과 학습 방법에 도움을 주세요. 학생이 심각한 스트레스나 공황의 조짐을 보이면 학생 지원 센터나 의사와 상담하도록 권장하세요. FILE:references/study-techniques.md # 학습 기법 각 세션에서 무엇을 할지. 증거 강도 순서(Dunlosky et al. 2013, "Improving Students' Learning With Effective Learning Techniques"는 연습 시험과 분산 연습을 높은 효용으로 평가). ## 인출 연습 (높음) 다시 읽는 대신 기억에서 정보를 꺼내세요: 질문에 답하고, 빈 페이지에 기억나는 모든 것을 쓰고, 노트와 대조하여 다른 색으로 빈칸을 채우세요. 플래시카드는 뒤집기 전에 답하면 효과적입니다. 처음에 틀리고 나서 고치는 것도 학습에 도움이 됩니다. ## 분산 학습 (높음) 한 과목의 세션을 긴 블록 하나 대신 여러 날에 걸쳐 분산하세요. 각 주제에 대한 간단한 복습 리듬: 다음 날, 3일 후, 일주일 후, 시험 전. 시간표는 과목을 여러 날에 걸쳐 교차 배치합니다; 각 세션을 그 과목의 이전 세션에 대한 5분 회상으로 시작하여 분산 학습을 구축하세요. ## 교차 학습 (중간) 과목 내에서 문제 유형을 섞으세요(수학과 과학의 경우: 같은 유형 20개가 아니라 한 세트에 다양한 유형의 문제) 시험이 요구하는 방법 선택을 연습하기 위해서입니다. ## 모의고사 (시험에 높음) 각 시험 전에 시간 제한 조건에서 최소 한 개의 전체 시험지를 풀고, 공식 채점 기준으로 채점하고 주제별로 잃은 점수를 목록화하세요. 스크립트는 각 시험 전날 하나를 배치합니다; 시험지가 있으면 더 일찍 추가하세요. ## 정교화 및 자기 설명 (중간) "왜 이게 작동하지?" "이게 X와 어떻게 연결되지?"라고 묻고, 가르치듯이 개념을 소리 내어 설명하고, 기억에서 개념 지도를 그리세요. ## 단독으로는 가치가 낮음 다시 읽기, 형광펜 표시, 노트 복사는 생산적으로 느껴지지만 장기적 이득은 거의 없습니다. 인출 전 첫 번째 통과로만 사용하세요. ## 세션 루틴 (50/10 기본) 1. 5분: 이 과목의 지난 세션에서 무엇을 했는지 기억에서 회상. 2. 30분: 한 주제 학습 또는 연습(학습 + 회상) 또는 문제 풀기(연습 문제). 3. 10분: 책을 덮고 자신을 시험하고, 놓친 것을 표시. 4. 5분: 다음에 할 수 없었던 질문 세 개를 적기. 5. 10분 화면에서 떨어져 휴식: 움직이고, 물 마시기. 집중력이 짧으면 25/5 세션(`--session-min 25 --break-min 5`)과 네 번마다 더 긴 휴식을 사용하세요. ## 수면, 음식, 시험 전날 수면은 기억을 강화합니다; 밤샘은 시험 성적을 떨어뜨립니다. 시험 전날 밤은 가벼운 복습과 수면을 위해 남겨두세요. 규칙적으로 식사하고, 매일 움직이고, 세션 중에는 휴대폰을 다른 방에 두세요. FILE:references/scheduling-rules.md # 일정 규칙 `scripts/revision_plan.py`가 시간표를 만드는 방법. ## 하루 세션 수 일일 시간에 맞는 세션 수: `floor((hours * 60 + break) / (session + break))`. 50/10 세션: 3시간 -> 3세션, 5시간 -> 5세션. 휴식일(`--rest-day`)과 `--off` 날짜는 없음. 시험 당일에는 세션의 절반만 계획됩니다(시험이 나머지를 차지), 이후 시험만. ## 우선순위 및 목표 - 우선순위 = 가중치 x (6 - 자신감). 가중치 5, 자신감 2 -> 20; 가중치 3, 자신감 4 -> 6. - 목표 세션 = 해당 시험 전에 가능한 모든 세션 x 우선순위 / 모든 우선순위의 합 (최소 1). 가중치는 학점 또는 1-5 중요도 점수일 수 있습니다; 비율만 중요하므로 모든 과목에 동일한 척도를 사용하세요. ## 각 세션 선택 모든 세션에 대해 스크립트는 시험이 아직 남아 있고 그날 `--max-same`(기본 2)보다 적은 세션을 가진 과목 중에서 선택합니다: 1. 아직 목표에 미달한 과목 먼저; 2. 그런 다음 이전 세션과 다른 과목(교차 학습); 3. 그런 다음 시험까지 남은 일수당 가장 높은 남은 필요량; 4. 동률이면 더 높은 우선순위, 그 다음 더 이른 시험. 시험 전날은 그 과목의 시간 제한 모의고사로 시작합니다. ## 세션 유형 - 학습 + 회상: 과목 목표의 60%가 완료되고 시험까지 7일 이상 남을 때까지. - 혼합 복습: 목표의 60% 이후, 시험까지 7일 이상 남음. - 연습 문제: 시험 전 마지막 7일. - 모의고사(시간 제한): 시험 전날. ## 분석 결과 | 코드 | 심각도 | 규칙 | 일반적인 해결책 | |---|---|---|---| | UNDER_COVERED | HIGH | 세션 < 주제 | 시간 추가, 더 일찍 시작, 수익 낮은 주제 훑어보기 | | TIGHT | MEDIUM | 세션 < 1.5 x 주제 | 단일 통과 수용, 또는 강한 과목에서 시간 확보 | | BELOW_TARGET | MEDIUM | 계획 < 목표의 60% | 시험이 빠름; 그 과목을 먼저 시작 | | BACK_TO_BACK | MEDIUM | 연속된 날짜의 시험 | 두 번째 시험의 연습을 앞당김 | | SAME_DAY | MEDIUM | 하루에 두 시험 | 마지막 주에 둘을 하나의 블록으로 취급 | | NO_REST_DAY | LOW | 휴식일이나 쉬는 날 없이 10일 초과 계획 | `--rest-day` 추가 | | LONG_DAYS | LOW | 하루 8시간 초과 | 5-6시간 집중으로 제한 | ## 조정 - 한 과목에 더 많은 시간: 가중치를 높이거나 자신감을 낮추고 다시 실행. - 과목 전환 줄이기: `--max-same 3`. - 시각 표시: `--day-start 09:00`은 세션 사이 휴식과 함께 시작 및 종료 시간을 추가. - 재계획: 각 체크인 후 자신감과 `--start`를 업데이트하고 다시 실행; 완료된 시험은 CSV에서 제외. FILE:templates/revision-plan.md # 복습 계획: <이름>, <시험 기간> **기간:** <2026년 11월 16일 ~ 12월 11일> **시간:** <주중 3시간, 토요일 5시간> **휴식:** <일요일 + 11월 21일> **세션:** <50분 x 57개 (47.5시간)> **세션 리듬:** <50분 학습 / 10분 휴식> ## 시험 및 우선순위 | 과목 | 시험 | 가중치 | 자신감 | 주제 | 계획된 세션 | 비고 | |---|---|---|---|---|---|---| | <유기화학> | <12월 2일 수> | <5> | <2> | <9> | <15> | <12월 1일 모의고사> | ## 1주차: <11월 16-22일> | 요일 | 세션 1 | 세션 2 | 세션 3 | 세션 4 | 세션 5 | |---|---|---|---|---|---| | <11월 16일 월> | <16:00 유기화학: 학습> | <17:00 미시경제학: 학습> | <...> | | | ## 2주차: <...> <...> ## 세션 루틴 1. 지난 세션 5분 회상(빈 페이지) 2. 한 주제 30분 학습 또는 연습 3. 10분 자가 테스트, 놓친 것 표시 4. 5분: 다음에 할 질문 세 개 5. 화면에서 떨어져 10분 휴식 ## 합의된 절충안 - <통계학 TIGHT: 전체 한 번 통과, 두 번째 통과는 주제 5-8만(모의고사에서 가장 많은 점수)> - <유럽사 / 미시경제학 연속: 미시경제학 연습은 12월 5일까지 완료> ## 체크인 - <11월 22일 일>: 과목별 자신감 1-5 재평가, 플래너 재실행 - <11월 29일 일>: 동일, 마지막 10일 조정 ## 웰빙 - 수면: <23:30 취침, 시험 전날 밤 22:00 이후 공부 금지> - 일일 운동: <30분 산책> - 너무 힘들면: <...와 상담 / 학생 지원 연락처> FILE:examples/winter-exams.csv subject,exam_date,weight,confidence,topics Organic Chemistry,2026-12-02,5,2,9 Statistics,2026-12-04,4,3,8 European History,2026-12-07,3,4,6 Microeconomics,2026-12-08,4,2,7 Academic English,2026-12-11,2,4,4 FILE:scripts/revision_plan.py #!/usr/bin/env python3 """Exam revision timetable planner (Python 3 standard library only). Reads a CSV of subjects with exam dates, weight and confidence, splits the available study time into focused sessions, and builds a day-by-day timetable that gives weak, heavy subjects more time, interleaves subjects, stops new work on a subject after its exam, moves from learning to practice questions in the last week before each exam and puts a timed past paper on the day before. CSV columns (header required; ; or , separated): subject, exam_date (YYYY-MM-DD), weight (1-5 or credits), confidence (1-5), topics (optional) Usage: python3 revision_plan.py exams.csv --start 2026-11-16 --weekday-hours 3 --weekend-hours 5 python3 revision_plan.py exams.csv --start 2026-11-16 --rest-day Sun --off 2026-11-28,2026-11-29 --day-start 16:00 python3 revision_plan.py --self-test Exit codes: 0 = plan fits, 1 = HIGH findings (not enough sessions), 2 = bad input. """ import argparse, csv, datetime as dt, io, json, sys DAYS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] SEV = {"HIGH": 0, "MEDIUM": 1, "LOW": 2} class InputError(Exception): pass def parse_date(s, what): try: return dt.date.fromisoformat(s.strip()) except ValueError: raise InputError(f"{what} '{s}' must be YYYY-MM-DD") def read_subjects(text): sample = text[:2000] delim = ";" if sample.count(";") > sample.count(",") else "," rd = csv.DictReader(io.StringIO(text), delimiter=delim) if not rd.fieldnames: raise InputError("empty CSV") fields = [f.strip().lower() for f in rd.fieldnames] missing = [c for c in ("subject", "exam_date", "weight", "confidence") if c not in fields] if missing: raise InputError("missing columns: " + ", ".join(missing)) subs = [] for i, raw in enumerate(rd, start=2): r = {k.strip().lower(): (v or "").strip() for k, v in raw.items() if k} if not any(r.values()): continue try: w = float(r["weight"].replace(",", ".")) c = int(r["confidence"]) t = int(r["topics"]) if r.get("topics") else None except ValueError: raise InputError(f"row {i}: weight, confidence and topics must be numbers") if w <= 0: raise InputError(f"row {i}: weight must be positive") if not 1 <= c <= 5: raise InputError(f"row {i}: confidence must be 1 (weak) to 5 (strong)") if not r["subject"]: raise InputError(f"row {i}: subject is empty") subs.append({"subject": r["subject"], "exam": parse_date(r["exam_date"], f"row {i}: exam_date"), "weight": w, "confidence": c, "topics": t}) if not subs: raise InputError("no subjects in CSV") return subs def slots_for(hours, session, brk): """Number of sessions that fit in `hours` with a break between sessions.""" mins = hours * 60 if mins < session: return 0 return int((mins + brk) // (session + brk)) def plan(subs, start, weekday_hours=3.0, weekend_hours=5.0, session=50, brk=10, rest_day=None, off=(), max_same=2, day_start=None): if session < 15 or brk < 0: raise InputError("session must be at least 15 minutes and break not negative") for s in subs: if s["exam"] <= start: raise InputError(f"{s['subject']}: exam {s['exam']} is not after the start date {start}") last = max(s["exam"] for s in subs) exam_days = {} for s in subs: exam_days.setdefault(s["exam"], []).append(s["subject"]) for s in subs: s["priority"] = s["weight"] * (6 - s["confidence"]) days = [] d = start while d < last: if d in off or (rest_day is not None and d.weekday() == rest_day): n = 0 else: n = slots_for(weekend_hours if d.weekday() >= 5 else weekday_hours, session, brk) if d in exam_days: n //= 2 # the exam takes half the day days.append((d, n)) d += dt.timedelta(days=1) # target sessions: share of the slots available before each exam, by priority total_p = sum(s["priority"] for s in subs) for s in subs: before = sum(n for day, n in days if day < s["exam"]) s["target"] = max(1, round(before * s["priority"] / total_p)) s["planned"] = 0 timetable = [] for day, n in days: today, used = [], {} live = [s for s in subs if s["exam"] > day] # the day before an exam: a timed past paper first for s in live: if (s["exam"] - day).days == 1 and len(today) < n: today.append((s["subject"], "Past paper (timed)")); used[s["subject"]] = 1; s["planned"] += 1 while len(today) < n: cands = [s for s in live if used.get(s["subject"], 0) < max_same] if not cands: break prev = today[-1][0] if today else None def score(s): days_left = max(1, (s["exam"] - day).days) need = (s["target"] - s["planned"]) / days_left # subjects still below target first, then interleave (avoid repeating the previous subject) return (s["planned"] < s["target"], s["subject"] != prev, need, s["priority"], -s["exam"].toordinal()) s = max(cands, key=score) left = (s["exam"] - day).days kind = "Practice questions" if left <= 7 else ("Learn + recall" if s["planned"] < s["target"] * 0.6 else "Mixed review") today.append((s["subject"], kind)); used[s["subject"]] = used.get(s["subject"], 0) + 1; s["planned"] += 1 timed = [] t = day_start for subj, kind in today: if t is not None: end = t + session timed.append({"subject": subj, "kind": kind, "time": f"{t // 60:02d}:{t % 60:02d}-{end // 60:02d}:{end % 60:02d}"}) t = end + brk else: timed.append({"subject": subj, "kind": kind}) timetable.append({"date": day.isoformat(), "dow": DAYS[day.weekday()], "exams": exam_days.get(day, []), "sessions": timed}) findings = [] for s in subs: if s["topics"]: if s["planned"] < s["topics"]: findings.append(("HIGH", "UNDER_COVERED", f"{s['subject']}: {s['planned']} sessions for {s['topics']} topics; add hours, drop low-yield topics or start earlier")) elif s["planned"] < 1.5 * s["topics"]: findings.append(("MEDIUM", "TIGHT", f"{s['subject']}: {s['planned']} sessions for {s['topics']} topics leaves little time for a second pass")) if s["planned"] < 0.6 * s["target"]: findings.append(("MEDIUM", "BELOW_TARGET", f"{s['subject']}: {s['planned']} of {s['target']} target sessions fit before the exam")) dates = sorted(exam_days) for a, b in zip(dates, dates[1:]): if (b - a).days <= 1: findings.append(("MEDIUM", "BACK_TO_BACK", f"exams on {a} ({', '.join(exam_days[a])}) and {b} ({', '.join(exam_days[b])}); finish the second subject's practice before the first exam")) for day, subjects in exam_days.items(): if len(subjects) > 1: findings.append(("MEDIUM", "SAME_DAY", f"{len(subjects)} exams on {day}: {', '.join(subjects)}")) if rest_day is None and len(days) > 10 and not off: findings.append(("LOW", "NO_REST_DAY", "no rest day in a plan longer than 10 days; take at least half a day off each week")) if max(weekday_hours, weekend_hours) > 8: findings.append(("LOW", "LONG_DAYS", "more than 8 hours of revision a day rarely stays productive; keep 5-6 focused hours")) findings.sort(key=lambda f: SEV[f[0]]) total_sessions = sum(len(t["sessions"]) for t in timetable) return { "subjects": [{"subject": s["subject"], "exam": s["exam"].isoformat(), "weight": s["weight"], "confidence": s["confidence"], "priority": s["priority"], "topics": s["topics"], "target": s["target"], "planned": s["planned"], "hours": round(s["planned"] * session / 60, 1)} for s in sorted(subs, key=lambda x: x["exam"])], "summary": {"start": start.isoformat(), "last_exam": last.isoformat(), "days": len(days), "sessions": total_sessions, "study_hours": round(total_sessions * session / 60, 1), "session_min": session, "break_min": brk}, "timetable": timetable, "findings": [{"severity": a, "code": b, "message": c} for a, b, c in findings], } def to_markdown(p): s = p["summary"] out = ["# Revision timetable", "", f"{s['start']} to {s['last_exam']}: {s['days']} days, {s['sessions']} sessions of {s['session_min']} min ({s['study_hours']} h of focused study), {s['break_min']} min breaks", "", "| Subject | Exam | Weight | Confidence | Priority | Topics | Target | Planned | Hours |", "|---|---|---|---|---|---|---|---|---|"] for x in p["subjects"]: out.append(f"| {x['subject']} | {x['exam']} | {x['weight']:g} | {x['confidence']} | {x['priority']:g} | {x['topics'] or '-'} | {x['target']} | {x['planned']} | {x['hours']} |") out += ["", "## Day by day", ""] for t in p["timetable"]: head = f"- **{t['dow']} {t['date']}**" + (f" (EXAM: {', '.join(t['exams'])})" if t["exams"] else "") if not t["sessions"]: out.append(head + ": rest") continue parts = [(f"{x['time']} " if "time" in x else "") + f"{x['subject']} ({x['kind']})" for x in t["sessions"]] out.append(head + ": " + "; ".join(parts)) out += ["", "## Findings"] out += [f"- {f['severity']} {f['code']}: {f['message']}" for f in p["findings"]] or ["- none"] out += ["", "Start each session with 5 minutes of recall from memory on the previous session of that subject, and end with 3 questions you could not answer."] return "\n".join(out) def self_test(): res = [] def check(name, cond): res.append(cond) print(("PASS " if cond else "FAIL ") + name) D = dt.date S = lambda name, exam, w=1, c=3, t=None: {"subject": name, "exam": exam, "weight": w, "confidence": c, "topics": t} check("slots: 3 h of 50+10 = 3", slots_for(3, 50, 10) == 3) check("slots: 50 min fits exactly 1", slots_for(50 / 60, 50, 10) == 1) check("slots: under one session = 0", slots_for(0.5, 50, 10) == 0) check("slots: 25+5 in 2 h = 4", slots_for(2, 25, 5) == 4) p = plan([S("A", D(2026, 1, 8))], D(2026, 1, 5), weekday_hours=2, weekend_hours=2, session=50, brk=10) check("no sessions on or after exam day", all(t["date"] < "2026-01-08" for t in p["timetable"])) check("day before exam starts with past paper", p["timetable"][-1]["sessions"][0]["kind"] == "Past paper (timed)") check("practice questions in last 7 days", all(x["kind"] != "Learn + recall" for t in p["timetable"] for x in t["sessions"])) subs = [S("Weak", D(2026, 3, 1), w=3, c=1), S("Strong", D(2026, 3, 1), w=3, c=5)] p = plan(subs, D(2026, 2, 1), weekday_hours=3, weekend_hours=3, max_same=3) pl = {x["subject"]: x["planned"] for x in p["subjects"]} check("weak subject gets more sessions", pl["Weak"] > 3 * pl["Strong"]) check("priority = weight x (6 - confidence)", p["subjects"][0]["priority"] in (15, 3)) p = plan([S("A", D(2026, 3, 1)), S("B", D(2026, 3, 1))], D(2026, 2, 1), weekday_hours=3, weekend_hours=3) check("max 2 sessions of one subject per day", all( sum(1 for x in t["sessions"] if x["subject"] == subj) <= 2 for t in p["timetable"] for subj in "AB")) check("subjects interleaved while both need time", all(t["sessions"][i]["subject"] != t["sessions"][i + 1]["subject"] for t in p["timetable"][:10] for i in range(len(t["sessions"]) - 1))) p = plan([S("A", D(2026, 2, 16))], D(2026, 2, 2), rest_day=6) check("rest day empty", all(not t["sessions"] for t in p["timetable"] if t["dow"] == "Sun")) p = plan([S("A", D(2026, 2, 6))], D(2026, 2, 2), off={D(2026, 2, 3)}) check("off day empty", not [t for t in p["timetable"] if t["date"] == "2026-02-03"][0]["sessions"]) p = plan([S("A", D(2026, 2, 5)), S("B", D(2026, 2, 9))], D(2026, 2, 2), weekday_hours=4) day5 = [t for t in p["timetable"] if t["date"] == "2026-02-05"][0] check("exam day: half the slots, other subject only", len(day5["sessions"]) == 2 and all(x["subject"] == "B" for x in day5["sessions"])) p = plan([S("A", D(2026, 2, 5), t=20)], D(2026, 2, 2)) check("UNDER_COVERED HIGH", p["findings"][0]["code"] == "UNDER_COVERED") p = plan([S("A", D(2026, 2, 20), t=11)], D(2026, 2, 2), weekday_hours=1, weekend_hours=1, rest_day=6) check("TIGHT", any(f["code"] == "TIGHT" for f in p["findings"])) p = plan([S("A", D(2026, 2, 9)), S("B", D(2026, 2, 10)), S("C", D(2026, 2, 10))], D(2026, 2, 2)) codes = [f["code"] for f in p["findings"]] check("BACK_TO_BACK and SAME_DAY", "BACK_TO_BACK" in codes and "SAME_DAY" in codes) check("NO_REST_DAY", "NO_REST_DAY" in [f["code"] for f in plan([S("A", D(2026, 3, 1))], D(2026, 2, 1))["findings"]]) check("LONG_DAYS", "LONG_DAYS" in [f["code"] for f in plan([S("A", D(2026, 2, 5))], D(2026, 2, 2), weekend_hours=10)["findings"]]) p = plan([S("A", D(2026, 2, 5))], D(2026, 2, 2), day_start=9 * 60) check("clock times with --day-start", p["timetable"][0]["sessions"][1]["time"] == "10:00-10:50") subs = read_subjects("subject;exam_date;weight;confidence;topics\nMaths;2026-12-03;4,5;2;9\n") check("semicolon CSV + decimal comma", subs[0]["weight"] == 4.5 and subs[0]["topics"] == 9) for bad, why in [("subject,exam_date\nA,2026-01-01\n", "missing columns"), ("subject,exam_date,weight,confidence\nA,2026-13-01,1,3\n", "bad date"), ("subject,exam_date,weight,confidence\nA,2026-01-01,1,9\n", "confidence out of range"), ("subject,exam_date,weight,confidence\nA,2026-01-01,x,3\n", "non-number")]: try: read_subjects(bad); check("rejects " + why, False) except InputError: check("rejects " + why, True) try: plan([S("A", D(2026, 1, 1))], D(2026, 1, 1)); check("rejects exam not after start", False) except InputError: check("rejects exam not after start", True) passed = sum(res) print(f"{passed}/{len(res)} passed") return 0 if passed == len(res) else 1 def main(): ap = argparse.ArgumentParser(description="Exam revision timetable planner") ap.add_argument("csv", nargs="?", help="subjects CSV") ap.add_argument("--start", help="first revision day YYYY-MM-DD (default today)") ap.add_argument("--weekday-hours", type=float, default=3.0) ap.add_argument("--weekend-hours", type=float, default=5.0) ap.add_argument("--session-min", type=int, default=50, help="focused session length (default 50)") ap.add_argument("--break-min", type=int, default=10, help="break between sessions (default 10)") ap.add_argument("--rest-day", choices=DAYS, help="weekly day off") ap.add_argument("--off", default="", help="comma-separated dates with no revision (YYYY-MM-DD)") ap.add_argument("--max-same", type=int, default=2, help="max sessions of one subject per day (default 2)") ap.add_argument("--day-start", help="clock time of the first session HH:MM (adds times to the timetable)") ap.add_argument("--json", action="store_true") ap.add_argument("--self-test", action="store_true") a = ap.parse_args() if a.self_test: return self_test() if not a.csv: ap.error("give a CSV, or --self-test") try: with open(a.csv, encoding="utf-8-sig") as fh: subs = read_subjects(fh.read()) start = parse_date(a.start, "--start") if a.start else dt.date.today() off = {parse_date(x, "--off") for x in a.off.split(",") if x.strip()} ds = None if a.day_start: try: h, m = map(int, a.day_start.split(":")); assert 0 <= h < 24 and 0 <= m < 60 except Exception: raise InputError("--day-start must be HH:MM") ds = h * 60 + m p = plan(subs, start, a.weekday_hours, a.weekend_hours, a.session_min, a.break_min, DAYS.index(a.rest_day) if a.rest_day else None, off, a.max_same, ds) except (OSError, InputError) as e: print(f"error: {e}", file=sys.stderr) return 2 print(json.dumps(p, indent=2) if a.json else to_markdown(p)) return 1 if any(f["severity"] == "HIGH" for f in p["findings"]) else 0 if __name__ == "__main__": sys.exit(main())