How jclezamap/calificar works
Tipo y propósito del proyecto (según README + tree)
Este repo no es una app full-stack; es principalmente una librería Python distribuida por PyPI (pyproject.toml, src/calificar, *.egg-info) cuyo objetivo es:
• Permitir que estudiantes (en Jupyter/Colab) registren respuestas de un taller.
• Calcular/validar resultados localmente (al menos estructura de puntos/nota).
• Enviar/registrar la calificación en un sistema remoto del docente (“Esto enviará tus datos al servidor”).
• Validar funciones con evafunciones(URL, GRUPO) usando una URL tipo GitHub como fuente de referencia/validación.
Además, el repo incluye material académico/datasets en Big_Data/Taller_* (muchos Tema_*.md, respuestas.json, .csv, .xlsx) que son *contenido y datos* más que runtime del paquete.
Implicación para el diagrama: el “sistema” a diagramar no es solo código; es el ecosistema: *Notebook/usuario + paquete calificar + servicios externos (API docente, GitHub) + artefactos de talleres/datos + canal de distribución (PyPI).*
Runtime del paquete
• src/calificar/__init__.py
Punto de entrada del paquete (exposición de API pública: taller, evafunciones, etc. según README).
• src/calificar/core.py
Núcleo lógico: aquí probablemente viven clases/funciones taller, evafunciones, validaciones, serialización, networking HTTP, etc. (es el componente central a descomponer en el diagrama).
Distribución/Release
• pyproject.toml
Build system y dependencias (clave para el diagrama de “supply chain”).
• publicar.bat
Script de publicación (flujo de release).
• src/calificar.egg-info/*
Metadatos de packaging (no es arquitectura runtime, pero sí indica “paquete installable”).
Contenido de talleres / fixtures / ejemplos
• Big_Data/README.md, Big_Data/Taller_1..3/*
Documentación, enunciados, datasets y respuestas.json (posibles claves/expected outputs o templates).
• enunciados.json, TALLERES.md
Posible índice/metadata de talleres y enunciados.
Implicación para el diagrama: separa “producto” (librería) vs “contenido” (talleres/datos) vs “infra de publicación” (PyPI).
Qué relaciones/interacciones se deducen del README
Flujos principales:
Inicialización
• Notebook/Colab → calificar.taller(CODIGO, GRUPO, NOMBRE_TALLER, NUM_PREGUNTAS)
• Se crea un objeto “Taller” con estado en memoria (vector/lista de respuestas).
Registro de respuestas
• Notebook → Taller.respuestas(indice, resultado)
• Estado local: Taller.resp (inspección).
Calificación/registro remoto
• Notebook → Taller.calificar()
• Paquete → Servidor remoto del docente (API) para:
• validar puntos (0/1 por ítem),
• calcular nota,
• registrar intento,
• devolver mensaje (incluye “tiempo restante”, lo que sugiere que el servidor guarda ventanas de tiempo/cierre).
Validación de funciones
• Notebook → cr.evafunciones(URL, GRUPO)
• eva.validar("nombre_funcion") genera “código secreto”.
• Esto sugiere que:
• el validador obtiene referencia desde una URL (probablemente GitHub/raw),
• ejecuta o compara outputs (o llama a un servicio) y retorna token/código.
Implicación para el diagrama: hay al menos dos integraciones externas:
• Grading/Notas API (Docente)
• Repositorio/URL de referencia (GitHub u otra fuente)
Diagrama 1 — *System Context* (máximo nivel, “qué es y con qué habla”)
Componentes a poner (cajas):
• Estudiante (actor)
• Notebook Runtime (Jupyter/Colab/Python kernel)
• Librería calificar (instalada vía pip)
• Servidor de Calificaciones (Docente) (externo)
• Repositorio de Taller/Referencia (GitHub URL) (externo)
• (Opcional) PyPI como canal de distribución
Relaciones (flechas):
• Estudiante → Notebook: escribe soluciones y ejecuta celdas
• Notebook → calificar: invoca taller(), respuestas(), calificar(), evafunciones()
• calificar → Servidor Docente: POST/HTTP “registro de respuestas / obtención de nota / ventana de tiempo”
• calificar → GitHub URL: GET/HTTP “descarga referencia/metadata para validación”
• PyPI → Notebook: pip install calificar
Detalle importante a etiquetar en las flechas:
• Tipo de datos: {CODIGO, GRUPO, NOMBRE_TALLER, respuestas[], timestamp} hacia servidor
• Respuesta del servidor: {vector puntos[], nota, mensaje, deadline/tiempo_restante}
Por qué este diagrama es clave aquí: el principal riesgo/arquitectura está en integraciones y flujos de datos, no en microservicios internos.
Diagrama 2 — *Container/Runtime View* (dentro del lado “cliente”)
Aquí “contenedores” no son Docker; son módulos runtime.
Cajas recomendadas:
• User Code (Notebook cells)
• calificar package
• __init__.py (API pública)
• core.py (lógica)
• Local Memory State
• objeto Taller (respuestas en RAM)
• configuración (código(s), grupo, id taller, num preguntas)
• HTTP Client (puede ser requests u otro; si no se ve en el tree, dibújalo como “HTTP client (dependency)”)
• Remote Grading API
• Remote Reference Source (GitHub/raw)
Flechas:
• User Code → API pública (taller, evafunciones)
• Taller.respuestas() → Local Memory State (mutación)
• Taller.calificar() → HTTP Client → Remote Grading API
• evafunciones.validar() → HTTP Client → Remote Reference Source (y/o Remote API si aplica) → devuelve “secret code”
Etiquetas a añadir:
• “sync call” (bloqueante) vs “async” (probablemente sync)
• “serialization: JSON” hacia el servidor (altamente probable, dado respuestas.json y uso típico)
Diagrama 3 — *Component View* (dentro de core.py)
Aunque solo ves core.py, puedes y debes separarlo conceptualmente en componentes (aunque estén en un solo archivo hoy). “No sobrepensar” aquí significa partirlo en piezas funcionales:
Subcomponentes a dibujar (como bloques dentro de calificar.core):
Taller Factory / Constructor
• crea instancia con metadata: CODIGO, GRUPO, NOMBRE_TALLER, NUM_PREGUNTAS
Answer Store
• estructura de almacenamiento resp (lista/dict)
• validaciones de índice, tipo, rango
Scoring/Grading Orchestrator
• arma payload
• llama endpoint remoto
• interpreta respuesta (puntos, nota, mensaje)
Networking Layer
• construcción de URL endpoints
• retries/timeouts (si existen; si no, dibujar como “debería” o “implícito”)
Function Validator (evafunciones)
• manejo de URL de referencia
• introspección de función por nombre (lookup en namespace)
• comparación/validación
• generación del “código secreto”
Interacciones internas:
• Taller.respuestas() → Answer Store
• Taller.calificar() → Scoring Orchestrator → Networking Layer → Remote Grading API
• evafunciones.validar() → Function Validator → Networking Layer → GitHub URL → retorna token
Por qué dibujar esto aunque esté en un archivo: porque el diagrama debe reflejar responsabilidades y contratos, no necesariamente la organización actual del código.
Pautas específicas para este tipo de proyecto (librería + servicio externo)
• Enfatiza contratos de API y data flow (payloads, tokens, códigos secretos, tiempos).
• Distingue claramente “local evaluation/collection” vs “authoritative grading” (servidor).
• Incluye límites de confianza:
• Cliente (estudiante) es no-confiable
• Servidor docente es autoridad
• Explicita fuentes externas (GitHub URL) porque cambian el comportamiento del validador y son puntos de fallo.
Si quieres un diagrama aún más “real”: agrega un bloque “Docente/Administración” y “DB/Storage” detrás del “Servidor Docente” (aunque no esté en el repo). Está justificado por el README: “registrar sus calificaciones”.
Elementos visuales que debes exigir en el diagrama
• Labels claros (ej. “Remote Grading API”, “Function Reference Repo”, “Notebook Runtime”).
• Flechas direccionales con verbos: “submit answers”, “fetch reference”, “return grade”.
• Azul: componentes locales (Notebook, calificar)
• Rojo/Naranja: servicios externos (Grading API, GitHub)
• Verde: artefactos/paquetes (PyPI, wheel/sdist)
• Gris: datos/contenido (Big_Data datasets, enunciados.json)
Qué NO olvidar (detalle “esencial”)
• El objeto Taller como entidad central de estado (respuestas, metadata, nota).
• El flujo evafunciones como camino alterno al de “respuestas numéricas”.
• La dependencia de tiempo/cierre de taller (servidor devuelve “tiempo restante”): sugiere que el servidor mantiene reglas y calendario.
• El canal de distribución (PyPI) y el flujo de publicación (publicar.bat, pyproject.toml) si el diagrama incluye lifecycle.
Entregable recomendado (rápido y preciso)
Dibuja 3 láminas:
Componentes de core (Taller/AnswerStore/GradingOrchestrator/Networking/Validator)
Con eso capturas “tantos componentes como sea posible” sin inventar microservicios, y el diagrama queda fiel al propósito real del repo.