Metadata-Version: 2.4
Name: calificar
Version: 0.1.20
Summary: Permite calificar talleres a través de Python
Author-email: Juan Carlos Lezama <jclezamap@gmail.com>
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.4.0
Requires-Dist: numpy>=1.22.0
Requires-Dist: requests>=2.28.0
Dynamic: license-file

# 📦 calificar

[![PyPI version](https://img.shields.io/pypi/v/calificar.svg?color=blue)](https://pypi.org/project/calificar/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/calificar.svg)](https://pypi.org/project/calificar/)

**calificar** es una librería diseñada para la evaluación automática de talleres y retos de programación en entornos Python (Jupyter, Google Colab, etc.). Permite a los estudiantes validar sus procesos en tiempo real y registrar sus calificaciones de forma automática en el sistema del docente.

---

## 📍 Índice
- [📦 calificar](#-calificar)
  - [📍 Índice](#-índice)
  - [🆕 Novedades](#-novedades)
  - [🚀 Instalación](#-instalación)
  - [🛠️ Configuración Inicial](#️-configuración-inicial)
    - [📋 Parámetros requeridos:](#-parámetros-requeridos)
  - [📝 Cómo Responder](#-cómo-responder)
  - [✅ Calificar y Validar](#-calificar-y-validar)
    - [1. Obtener Nota y Registrar](#1-obtener-nota-y-registrar)
    - [2. Validación de Funciones (`evafunciones`)](#2-validación-de-funciones-evafunciones)
  - [📓 Actividades en Colab (`evacolab`)](#-actividades-en-colab-evacolab)
  - [🔍 Funciones Auxiliares](#-funciones-auxiliares)
    - [Ver respuestas guardadas](#ver-respuestas-guardadas)
  - [💡 Ejemplos Completos](#-ejemplos-completos)
    - [👨‍💻 Caso Individual](#-caso-individual)
    - [👥 Caso en Parejas](#-caso-en-parejas)
    - [📓 Actividad en Colab](#-actividad-en-colab)
  - [📄 Licencia](#-licencia)

---

## 🆕 Novedades

* **Nueva clase `evacolab`:** valida tu notebook de Google Colab contra la rúbrica de la actividad y registra la entrega. Consulta la sección [📓 Actividades en Colab](#-actividades-en-colab-evacolab).
* **Nuevo resultado de `calificar()`:** la validación de puntos ya no aparece como `1;0;0;...`. Ahora se muestra una tabla vertical con cada pregunta en verde (correcta) o en rojo (incorrecta), numerada desde **P0**, igual que los índices de Python.
* **Resumen al crear el taller:** al inicializar `cr.taller(...)` se muestra tu nota y el tiempo restante para el cierre. El detalle por pregunta aparece solo cuando ejecutas `calificar()`.

---

## 🚀 Instalación

Instálalo fácilmente usando `pip`:

```bash
pip install calificar

```

En Google Colab o Jupyter, antepón `!` al comando. Si ya lo tenías instalado, agrega `-U` para obtener la última versión:

```python
!pip install -U calificar

```

> Si ya habías importado la librería en la sesión, reinicia el entorno de ejecución después de actualizar.

Luego, impórtalo en tu entorno de trabajo:

```python
import calificar as cr

```

---

## 🛠️ Configuración Inicial

Para comenzar, debes inicializar tu taller. Esta función conecta tu código con el sistema de notas.

```python
Taller1 = cr.taller('CODIGO', GRUPO, 'NOMBRE_TALLER', NUM_PREGUNTAS)

```

Al crear el taller verás una tarjeta con tu **nota** y el **mensaje** del sistema, que incluye el tiempo restante para el cierre. En este paso no se muestra qué preguntas están correctas: ese detalle aparece cuando ejecutas `calificar()`.

### 📋 Parámetros requeridos:

* **`CODIGO`**: Tu cédula o código estudiantil (entre comillas).
* **`GRUPO`**: El número de grupo que te asignó el docente.
* **`NOMBRE_TALLER`**: El identificador del taller (ej: `'taller1BD2026i'`).
* **`NUM_PREGUNTAS`**: Cantidad total de preguntas del taller.

---

## 📝 Cómo Responder

En Python, las listas e índices comienzan en **0**. Si vas a responder la pregunta **#1**, el índice que debes usar es **0**.

```python
# Sintaxis: Taller1.respuestas(INDICE_PREGUNTA, RESULTADO)

# Ejemplo:
resultado_ejercicio0 = 12.5
Taller1.respuestas(0, resultado_ejercicio0) 

```

---

## ✅ Calificar y Validar

### 1. Obtener Nota y Registrar

Cuando termines tus ejercicios, ejecuta la función de calificación. Esto enviará tus datos al servidor.

```python
Taller1.calificar()

```

**Al ejecutarlo verás una tarjeta con:**

1. 📝 **Nota:** Tu calificación actual y cuántas preguntas tienes correctas.
2. 🔢 **Validación de Puntos:** Una tabla vertical con una fila por pregunta. Cada fila muestra la respuesta que enviaste y el resultado, en verde si es correcta o en rojo si es incorrecta.
3. 💬 **Mensaje:** Confirmación de registro y el tiempo restante para el cierre del taller.

Ejemplo de la tabla:

| Pregunta | Tu respuesta | Resultado |
|:--------:|:------------:|:----------|
| 🟩 P0 | 12.5 | ✔ Correcta |
| 🟥 P1 | 7 | ✘ Incorrecta |
| 🟥 P2 | — | ✘ Incorrecta |

> Las preguntas se numeran desde **P0**, igual que el índice que usaste en `respuestas()`. Así, **P0** corresponde a la pregunta **#1** del enunciado. Un guion (—) indica que esa pregunta no tiene respuesta guardada.

### 2. Validación de Funciones (`evafunciones`)

Si el taller requiere crear una función de Python, usa esta herramienta para obtener un código de validación:

```python
# Configuración del validador
URL = "https://github.com/usuario/repo/taller1"
eva = cr.evafunciones(URL, GRUPO)

# Si tu función es correcta, esto generará un código secreto
codigo = eva.validar("nombre_de_tu_funcion")

# Guarda ese código como respuesta al punto correspondiente
Taller1.respuestas(4, codigo)

```

---

## 📓 Actividades en Colab (`evacolab`)

Algunas actividades se entregan como un notebook de Google Colab. En ese caso, `evacolab` envía tu notebook a la plataforma, lo revisa con la rúbrica de la actividad y registra la entrega.

```python
ev = cr.evacolab(codigo='CODIGO', actividad=NUM_ACTIVIDAD)
ev.validar()

```

**Parámetros:**

* **`codigo`**: Tu cédula o código estudiantil (entre comillas). Debe estar registrado en la lista del curso.
* **`actividad`**: El número o nombre de la actividad que indicó el docente.

**Antes de validar:**

* Ejecútalo **dentro de Google Colab**, porque la función lee el notebook que tienes abierto.
* Pon la celda de validación al final del notebook.
* Ejecuta todas las celdas (**Entorno de ejecución → Ejecutar todas**). La rúbrica revisa que las celdas estén ejecutadas y que tengan resultados y gráficos visibles.

**Al ejecutarlo verás una tarjeta con:**

1. 📝 **Nota:** Tu calificación y el porcentaje de requisitos cumplidos.
2. 📋 **Rúbrica:** Cada requisito de la actividad (variables, funciones, imports, celdas ejecutadas, gráficos, etc.) con **SI** en verde o **NO** en rojo.
3. ⚠️ **Alerta de posible copia:** Aparece si tu notebook se parece mucho a otra entrega de la misma actividad. El docente verá el detalle.

> Si necesitas los datos completos de la validación, quedan guardados en `ev.resultado`.

---

## 🔍 Funciones Auxiliares

### Ver respuestas guardadas

Usa esta función para ver qué datos tienes almacenados en memoria antes de enviar la calificación final:

```python
Taller1.resp

```

---

## 💡 Ejemplos Completos

### 👨‍💻 Caso Individual

```python
import calificar as cr

# 1. Inicio
Taller1 = cr.taller('1026', 1, 'taller1BD2026i', 5)

# 2. Desarrollo (Pregunta 1: ¿Cuánto es 6+6?)
a = 12
Taller1.respuestas(0, a)

# 3. Calificación
Taller1.calificar()

```

### 👥 Caso en Parejas

Si trabajan dos personas, separen sus códigos con un punto y coma (`;`) dentro de las comillas:

```python
Taller1 = cr.taller('1011;1012', 12, 'taller1FC2026i', 9)

```

### 📓 Actividad en Colab

```python
# Primera celda del notebook
!pip install -U calificar
import calificar as cr

# ... desarrollo de la actividad en las celdas intermedias ...

# Última celda del notebook
ev = cr.evacolab(codigo='1026', actividad=3)
ev.validar()

```

---

## 📄 Licencia

Este proyecto está bajo la Licencia MIT.
