Planificador de Horario de Repaso para Exámenes

--- name: planificador-horario-revision-examenes description: Construye un horario de revisión de exámenes día a día a partir de tus fechas de examen, pesos de asignaturas y confianza. Divide las horas de estudio en sesiones enfocadas, da más tiempo a las asignaturas débiles y pesadas, intercala asignaturas, cambia a preguntas de práctica en la última semana antes de cada examen, pone un examen de años anteriores cronometrado el día anterior, y respeta los días de descanso y libres. Señala muy pocas sesiones por tema y exámenes consecutivos. Incluye un planificador Python de stdlib con --self-test. --- # Planificador de Horario de Revisión de Exámenes Ayudas a los estudiantes a convertir una temporada de exámenes estresante en un plan realista: qué asignatura estudiar en cada sesión, cada día, hasta el último examen. Usas técnicas basadas en evidencia (espaciado, práctica de recuperación, intercalado, exámenes de años anteriores), mantienes el plan humano con descanso y sueño, y haces visibles las compensaciones cuando no hay tiempo suficiente para todo. ## Archivos en esta habilidad - `scripts/revision_plan.py` - lee un CSV de asignaturas e imprime la tabla de asignaturas, un horario día a día y hallazgos (solo biblioteca estándar de Python 3) - `references/study-techniques.md` - qué hacer dentro de una sesión: práctica de recuperación, espaciado, intercalado, exámenes de años anteriores, y qué evitar - `references/scheduling-rules.md` - cómo el script asigna prioridades, objetivos, tipos de sesión y hallazgos, y cómo ajustarlo - `templates/revision-plan.md` - el plan a entregar: resumen, horario semanal, rutina de sesión, puntos de control - `examples/winter-exams.csv` - cinco exámenes universitarios entre el 2 y el 11 de diciembre con recuentos de temas ## Flujo de trabajo ### 1. Recopila los hechos Pregunta por cada examen: asignatura, fecha, cuánto cuenta (créditos, porcentaje de la nota final, o importancia 1-5), confianza de 1 (perdido) a 5 (sólido), y el número de temas o capítulos. Luego pregunta por el primer día de revisión, horas realistas entre semana y fines de semana (después de clases, trabajo, desplazamiento), duración preferida de sesión (50/10 por defecto, Pomodoro 25/5 para poca concentración), un día de descanso semanal y cualquier día que ya esté ocupado. ### 2. Ejecuta el planificador ``` 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 ``` El código de salida 1 significa un hallazgo ALTO (menos sesiones que temas), 2 significa entrada incorrecta. ### 3. Arregla las compensaciones Para UNDER_COVERED o TIGHT: añade horas, empieza antes, baja el objetivo para asignaturas fuertes, o acuerda qué temas de bajo rendimiento hojear (usa la ponderación del plan de estudios o la frecuencia en exámenes de años anteriores). Para BACK_TO_BACK: mueve la práctica de la segunda asignatura antes del primer examen. Revisa el plan con el estudiante: ¿es factible en un mal día? Deja margen en lugar de abarrotar cada tarde. ### 4. Entrega Completa `templates/revision-plan.md`: la tabla de resumen, el horario por semana, la rutina de sesión de `references/study-techniques.md`, y dos fechas de control para volver a calificar la confianza y volver a ejecutar el script. ## Resultado de ejemplo Para `examples/winter-exams.csv` desde el 16 de noviembre con 3 h entre semana, 5 h los sábados, domingos y 21 de noviembre libres: 25 días, 57 sesiones de 50 minutos (47.5 h). Química Orgánica (peso 5, confianza 2) y Microeconomía (4, 2) reciben 15 y 16 sesiones, Historia Europea (3, 4) recibe 6. Cada asignatura termina con preguntas de práctica y un examen de años anteriores cronometrado el día anterior a su examen. Hallazgos: Estadística (10 sesiones para 8 temas) e Historia Europea (6 para 6) son TIGHT, e Historia Europea y Microeconomía son BACK_TO_BACK el 7 y 8 de diciembre. ## Reglas - Planifica con las horas que el estudiante realmente tiene, no las que desearía tener; protege el sueño (sin sesiones tarde en la noche antes de exámenes). - Cada sesión termina con recuperación (preguntas, recuerdo en página en blanco, tarjetas), no solo relectura o subrayado. - Mantén al menos un día de descanso o dos medios días a la semana; el agotamiento cuesta más que un día perdido. - Replanifica después de cada control o examen en lugar de seguir un plan roto. - No hagas trabajo calificado por el estudiante; ayuda con la planificación y métodos de estudio. Si un estudiante muestra signos de estrés grave o pánico, anímale a hablar con el apoyo estudiantil o un médico. FILE:references/study-techniques.md # Técnicas de Estudio Qué hacer dentro de cada sesión. Ordenadas por fuerza de evidencia (Dunlosky et al. 2013, "Improving Students' Learning With Effective Learning Techniques", calificó la práctica de pruebas y la práctica distribuida como de alta utilidad). ## Práctica de recuperación (alta) Trae información de vuelta de la memoria en lugar de leerla de nuevo: responde preguntas, escribe todo lo que recuerdes en una página en blanco, luego verifica contra tus notas y llena los vacíos en otro color. Las tarjetas funcionan si respondes antes de voltear. Equivocarse primero y luego corregir también ayuda al aprendizaje. ## Espaciado (alto) Distribuye sesiones sobre una asignatura en muchos días en lugar de un bloque largo. Un ritmo de repaso simple para cada tema: al día siguiente, después de 3 días, después de una semana, luego antes del examen. El horario intercala asignaturas a través de los días; comienza cada sesión con 5 minutos de recuerdo sobre la sesión anterior de esa asignatura para construir el espaciado. ## Intercalado (moderado) Mezcla tipos de problemas dentro de una asignatura (para matemáticas y ciencias: diferentes tipos de problemas en un conjunto, no 20 del mismo) para practicar elegir el método, que es lo que el examen requiere. ## Exámenes de años anteriores (alto para exámenes) Haz al menos un examen completo bajo condiciones cronometradas antes de cada examen, luego califícalo con el esquema de calificación oficial y lista los puntos perdidos por tema. El script pone uno el día antes de cada examen; añade más tempranos si hay exámenes disponibles. ## Elaboración y autoexplicación (moderado) Pregunta "¿por qué funciona esto?" y "¿cómo se conecta con X?", explica un concepto en voz alta como si lo enseñaras, dibuja un mapa conceptual de memoria. ## Bajo valor por sí solos Releer, subrayar y copiar notas se sienten productivos pero dan poco beneficio a largo plazo. Úsalos solo como un primer pase antes de la recuperación. ## Rutina de sesión (50/10 por defecto) 1. 5 min: recuerda de memoria lo que hiciste la última vez para esta asignatura. 2. 30 min: aprende o practica un tema (Aprender + recuerdo) o haz preguntas (Preguntas de práctica). 3. 10 min: cierra el libro y pruébate; marca lo que fallaste. 4. 5 min: escribe tres preguntas que no pudiste responder para la próxima vez. 5. 10 min de descanso lejos de la pantalla: muévete, bebe agua. Para períodos de atención cortos usa sesiones de 25/5 (`--session-min 25 --break-min 5`) y un descanso más largo cada cuatro. ## Sueño, comida y el día anterior El sueño consolida la memoria; las trasnochadas reducen el rendimiento en el examen. Mantén la noche antes del examen para repaso ligero y dormir. Come comidas regulares, muévete cada día, y mantén el teléfono en otra habitación durante las sesiones. FILE:references/scheduling-rules.md # Reglas de Programación Cómo `scripts/revision_plan.py` construye el horario. ## Sesiones por día Sesiones que caben en las horas diarias: `floor((hours * 60 + break) / (session + break))`. Con sesiones de 50/10: 3 h -> 3 sesiones, 5 h -> 5 sesiones. Los días de descanso (`--rest-day`) y las fechas `--off` no tienen ninguna. En un día de examen solo se planifican la mitad de las sesiones (el examen toma el resto), y solo para exámenes posteriores. ## Prioridad y objetivo - prioridad = peso x (6 - confianza). Peso 5, confianza 2 -> 20; peso 3, confianza 4 -> 6. - sesiones objetivo = todas las sesiones disponibles antes de ese examen x prioridad / suma de todas las prioridades (al menos 1). El peso puede ser créditos o una puntuación de importancia 1-5; solo importan las proporciones, así que usa la misma escala para cada asignatura. ## Elegir cada sesión Para cada sesión el script elige entre asignaturas cuyo examen aún está por delante y que tienen menos de `--max-same` (por defecto 2) sesiones ese día: 1. asignaturas aún por debajo de su objetivo primero; 2. luego una asignatura diferente de la sesión anterior (intercalado); 3. luego la mayor necesidad restante por día que queda hasta el examen; 4. los empates van a la mayor prioridad, luego al examen más temprano. El día antes de un examen comienza con un examen de años anteriores cronometrado para esa asignatura. ## Tipos de sesión - Aprender + recuerdo: hasta que el 60 % del objetivo de la asignatura esté hecho y más de 7 días antes de su examen. - Repaso mixto: después del 60 % del objetivo, más de 7 días antes. - Preguntas de práctica: en los últimos 7 días antes del examen. - Examen de años anteriores (cronometrado): el día antes del examen. ## Hallazgos | Código | Severidad | Regla | Arreglo típico | |---|---|---|---| | UNDER_COVERED | ALTO | sesiones < temas | más horas, empezar antes, hojear temas de bajo rendimiento | | TIGHT | MEDIO | sesiones < 1.5 x temas | aceptar un solo pase, o tomar tiempo de asignaturas fuertes | | BELOW_TARGET | MEDIO | planificado < 60 % del objetivo | el examen es temprano; empieza esa asignatura primero | | BACK_TO_BACK | MEDIO | exámenes en días consecutivos | adelantar la práctica para el segundo examen | | SAME_DAY | MEDIO | dos exámenes en un día | tratar ambos como un bloque en la última semana | | NO_REST_DAY | BAJO | plan > 10 días sin día de descanso o días libres | añadir `--rest-day` | | LONG_DAYS | BAJO | más de 8 h al día | limitar a 5-6 horas enfocadas | ## Ajuste - Más tiempo para una asignatura: sube su peso o baja su confianza y vuelve a ejecutar. - Menos cambios de asignatura: `--max-same 3`. - Horas de reloj: `--day-start 09:00` añade horas de inicio y fin, con descansos entre sesiones. - Replanifica: después de cada control, actualiza la confianza y `--start`, y vuelve a ejecutar; los exámenes terminados salen del CSV. FILE:templates/revision-plan.md # Plan de revisión: <nombre>, <temporada de exámenes> **Período:** <16 Nov a 11 Dic 2026> **Horas:** <3 h entre semana, 5 h sábados> **Descanso:** <domingos + 21 Nov> **Sesiones:** <57 x 50 min (47.5 h)> **Ritmo de sesión:** <50 min estudio / 10 min descanso> ## Exámenes y prioridades | Asignatura | Examen | Peso | Confianza | Temas | Sesiones planificadas | Notas | |---|---|---|---|---|---|---| | <Química Orgánica> | <Mié 2 Dic> | <5> | <2> | <9> | <15> | <examen de años anteriores 1 Dic> | ## Semana 1: <16-22 Nov> | Día | Sesión 1 | Sesión 2 | Sesión 3 | Sesión 4 | Sesión 5 | |---|---|---|---|---|---| | <Lun 16 Nov> | <16:00 Química Orgánica: Aprender> | <17:00 Microeconomía: Aprender> | <...> | | | ## Semana 2: <...> <...> ## Rutina de sesión 1. 5 min de recuerdo de la última sesión (página en blanco) 2. 30 min aprender o practicar un tema 3. 10 min autoevaluación, marca los fallos 4. 5 min: tres preguntas abiertas para la próxima vez 5. 10 min de descanso lejos de la pantalla ## Compensaciones acordadas - <Estadística es TIGHT: un pase completo, segundo pase solo en temas 5-8 (más puntos en exámenes de años anteriores)> - <Historia Europea / Microeconomía consecutivos: práctica de Microeconomía hecha para el 5 Dic> ## Controles - <Dom 22 Nov>: vuelve a calificar la confianza 1-5 por asignatura, vuelve a ejecutar el planificador - <Dom 29 Nov>: lo mismo, ajusta los últimos 10 días ## Bienestar - Sueño: <en cama para las 23:30, sin estudio después de las 22:00 la noche antes de exámenes> - Movimiento diario: <caminata de 30 min> - Si es demasiado: <habla con ... / contacto de apoyo estudiantil> 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 """Planificador de horario de revisión de exámenes (solo biblioteca estándar de Python 3). Lee un CSV de asignaturas con fechas de examen, peso y confianza, divide el tiempo de estudio disponible en sesiones enfocadas, y construye un horario día a día que da más tiempo a asignaturas débiles y pesadas, intercala asignaturas, detiene el trabajo nuevo en una asignatura después de su examen, pasa de aprender a preguntas de práctica en la última semana antes de cada examen y pone un examen de años anteriores cronometrado el día anterior. Columnas CSV (encabezado requerido; separado por ; o ,): subject, exam_date (YYYY-MM-DD), weight (1-5 o créditos), confidence (1-5), topics (opcional) Uso: 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 Códigos de salida: 0 = el plan cabe, 1 = hallazgos ALTOS (sesiones insuficientes), 2 = entrada incorrecta. """ 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}' debe ser 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("CSV vacío") 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("columnas faltantes: " + ", ".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"fila {i}: weight, confidence y topics deben ser números") if w <= 0: raise InputError(f"fila {i}: weight debe ser positivo") if not 1 <= c <= 5: raise InputError(f"fila {i}: confidence debe ser 1 (débil) a 5 (fuerte)") if not r["subject"]: raise InputError(f"fila {i}: subject está vacío") subs.append({"subject": r["subject"], "exam": parse_date(r["exam_date"], f"fila {i}: exam_date"), "weight": w, "confidence": c, "topics": t}) if not subs: raise InputError("sin asignaturas en el CSV") return subs def slots_for(hours, session, brk): """Número de sesiones que caben en `hours` con un descanso entre sesiones.""" 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 debe ser al menos 15 minutos y break no negativo") for s in subs: if s["exam"] <= start: raise InputError(f"{s['subject']}: exam {s['exam']} no es después de la fecha de inicio {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 # el examen toma la mitad del día days.append((d, n)) d += dt.timedelta(days=1) # sesiones objetivo: parte de los espacios disponibles antes de cada examen, por prioridad 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] # el día antes de un examen: un examen de años anteriores cronometrado primero for s in live: if (s["exam"] - day).days == 1 and len(today) < n: today.append((s["subject"], "Examen de años anteriores (cronometrado)")); 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 # asignaturas aún por debajo del objetivo primero, luego intercalar (evitar repetir la asignatura anterior) 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 = "Preguntas de práctica" if left <= 7 else ("Aprender + recuerdo" if s["planned"] < s["target"] * 0.6 else "Repaso mixto") 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']} sesiones para {s['topics']} temas; añade horas, elimina temas de bajo rendimiento o empieza antes")) elif s["planned"] < 1.5 * s["topics"]: findings.append(("MEDIUM", "TIGHT", f"{s['subject']}: {s['planned']} sesiones para {s['topics']} temas deja poco tiempo para un segundo pase")) if s["planned"] < 0.6 * s["target"]: findings.append(("MEDIUM", "BELOW_TARGET", f"{s['subject']}: {s['planned']} de {s['target']} sesiones objetivo caben antes del examen")) dates = sorted(exam_days) for a, b in zip(dates, dates[1:]): if (b - a).days <= 1: findings.append(("MEDIUM", "BACK_TO_BACK", f"exámenes el {a} ({', '.join(exam_days[a])}) y {b} ({', '.join(exam_days[b])}); termina la práctica de la segunda asignatura antes del primer examen")) for day, subjects in exam_days.items(): if len(subjects) > 1: findings.append(("MEDIUM", "SAME_DAY", f"{len(subjects)} exámenes el {day}: {', '.join(subjects)}")) if rest_day is None and len(days) > 10 and not off: findings.append(("LOW", "NO_REST_DAY", "sin día de descanso en un plan de más de 10 días; toma al menos medio día libre cada semana")) if max(weekday_hours, weekend_hours) > 8: findings.append(("LOW", "LONG_DAYS", "más de 8 horas de revisión al día rara vez se mantienen productivas; mantén 5-6 horas enfocadas")) 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 = ["# Horario de revisión", "", f"{s['start']} a {s['last_exam']}: {s['days']} días, {s['sessions']} sesiones de {s['session_min']} min ({s['study_hours']} h de estudio enfocado), {s['break_min']} min de descansos", "", "| Asignatura | Examen | Peso | Confianza | Prioridad | Temas | Objetivo | Planificado | Horas |", "|---|---|---|---|---|---|---|---|---|"] 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 += ["", "## Día a día", ""] for t in p["timetable"]: head = f"- **{t['dow']} {t['date']}**" + (f" (EXAMEN: {', '.join(t['exams'])})" if t["exams"] else "") if not t["sessions"]: out.append(head + ": descanso") 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 += ["", "## Hallazgos"] out += [f"- {f['severity']} {f['code']}: {f['message']}" for f in p["findings"]] or ["- ninguno"] out += ["", "Comienza cada sesión con 5 minutos de recuerdo de memoria sobre la sesión anterior de esa asignatura, y termina con 3 preguntas que no pudiste responder."] 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 de 50+10 = 3", slots_for(3, 50, 10) == 3) check("slots: 50 min cabe exactamente 1", slots_for(50 / 60, 50, 10) == 1) check("slots: menos de una sesión = 0", slots_for(0.5, 50, 10) == 0) check("slots: 25+5 en 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("sin sesiones en o después del día del examen", all(t["date"] < "2026-01-08" for t in p["timetable"])) check("el día antes del examen comienza con examen de años anteriores", p["timetable"][-1]["sessions"][0]["kind"] == "Examen de años anteriores (cronometrado)") check("preguntas de práctica en los últimos 7 días", all(x["kind"] != "Aprender + recuerdo" for t in p["timetable"] for x in t["sessions"])) subs = [S("Débil", D(2026, 3, 1), w=3, c=1), S("Fuerte", 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("la asignatura débil recibe más sesiones", pl["Débil"] > 3 * pl["Fuerte"]) check("prioridad = peso x (6 - confianza)", 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("máx. 2 sesiones de una asignatura por día", all( sum(1 for x in t["sessions"] if x["subject"] == subj) <= 2 for t in p["timetable"] for subj in "AB")) check("asignaturas intercaladas mientras ambas necesitan tiempo", 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("día de descanso vacío", 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("día libre vacío", 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("día de examen: la mitad de los espacios, solo otra asignatura", 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 ALTO", 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 y 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("horas de reloj con --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("CSV de punto y coma + coma decimal", subs[0]["weight"] == 4.5 and subs[0]["topics"] == 9) for bad, why in [("subject,exam_date\nA,2026-01-01\n", "columnas faltantes"), ("subject,exam_date,weight,confidence\nA,2026-13-01,1,3\n", "fecha incorrecta"), ("subject,exam_date,weight,confidence\nA,2026-01-01,1,9\n", "confianza fuera de rango"), ("subject,exam_date,weight,confidence\nA,2026-01-01,x,3\n", "no numérico")]: try: read_subjects(bad); check("rechaza " + why, False) except InputError: check("rechaza " + why, True) try: plan([S("A", D(2026, 1, 1))], D(2026, 1, 1)); check("rechaza examen no después del inicio", False) except InputError: check("rechaza examen no después del inicio", True) passed = sum(res) print(f"{passed}/{len(res)} pasados") return 0 if passed == len(res) else 1 def main(): ap = argparse.ArgumentParser(description="Planificador de horario de revisión de exámenes") ap.add_argument("csv", nargs="?", help="CSV de asignaturas") ap.add_argument("--start", help="primer día de revisión YYYY-MM-DD (por defecto hoy)") 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="duración de sesión enfocada (por defecto 50)") ap.add_argument("--break-min", type=int, default=10, help="descanso entre sesiones (por defecto 10)") ap.add_argument("--rest-day", choices=DAYS, help="día libre semanal") ap.add_argument("--off", default="", help="fechas separadas por comas sin revisión (YYYY-MM-DD)") ap.add_argument("--max-same", type=int, default=2, help="máx. sesiones de una asignatura por día (por defecto 2)") ap.add_argument("--day-start", help="hora de reloj de la primera sesión HH:MM (añade horas al horario)") 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("da un CSV, o --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 debe ser 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())