Manual de uso de qbank

pip install calcprop-qbank

qbank-init y lint llegan con la 0.6.0; si tenías una versión anterior, actualiza con pip install -U calcprop-qbank. La versión en desarrollo se instala desde el repositorio (hace falta git):

pip install "calcprop-qbank[jupyter] @ git+https://github.com/mbujosab/calcprop-qbank"

Si no estás familiarizado con Python o los entornos virtuales, lee la sección siguiente.

qbank requiere Python 3.9 o superior. Comprueba si ya lo tienes instalado:

Si el comando devuelve algo como Python 3.11.2 estás listo. Si no, descarga Python desde python.org e instálalo (en Windows marca la opción Add Python to PATH).

Un entorno virtual es una carpeta que contiene una copia aislada de Python con sus propios paquetes instalados, independiente del resto del sistema. Esto evita conflictos entre proyectos que requieren versiones distintas de las mismas librerías.

Trabajar siempre dentro de un entorno virtual es una buena práctica, aunque no es estrictamente obligatorio para un uso sencillo de qbank.

Abre una terminal (en Windows: Símbolo del sistema o PowerShell) y sitúate en el directorio donde quieres trabajar, por ejemplo:

mkdir mis_cuestionarios
cd mis_cuestionarios

Crea el entorno virtual (llámalo como quieras; aquí usamos .venv):

Actívalo:

Cuando el entorno está activo, verás su nombre entre paréntesis al comienzo del prompt, por ejemplo (.venv). A partir de ese momento, pip y python apuntan al entorno virtual y no al sistema.

Con el entorno activo:

pip install calcprop-qbank

o, para la versión en desarrollo (hace falta tener git):

pip install "calcprop-qbank[jupyter] @ git+https://github.com/mbujosab/calcprop-qbank"

Verifica la instalación:

python -c "import qbank; print('qbank', qbank.__version__)"
qbank-init --help

Si ves qbank 0.6.0 (o posterior) y la ayuda de qbank-init, todo está en orden. Si en cambio sale AttributeError: … no attribute '__version__' o qbank-init no existe, tienes una versión anterior a la 0.6: actualiza con pip install -U calcprop-qbank. Para los PDF y el XML de Moodle hace falta además pdflatex con los paquetes automultiplechoice (lo instala el programa Auto Multiple Choice) y moodle (tlmgr install moodle en TeX Live).

En Windows, dentro del entorno virtual, usa python (no python3). Si al activarlo en PowerShell (.venv\Scripts\Activate.ps1) sale un error de permisos, ejecuta antes:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

La forma recomendada de trabajar es un proyecto creado con qbank-init:

qbank-init mi-banco
cd mi-banco
make lint          # comprueba las preguntas de ejemplo (sin LaTeX)
make amc           # PDF de revisión (vista profe) en build/amc/

El proyecto contiene cinco preguntas de ejemplo, los scripts que las exportan, un Makefile, nueva_pregunta.py (un guion para escribir una pregunta en Python y guardarla como JSON) y, en prompts/, instrucciones para escribir preguntas con ayuda de una IA. Su README.org explica el flujo completo. El resto de este manual describe las piezas que esos scripts usan.

qbank importa calcprop, así que al escribir from qbank import * tienes acceso al motor lógico. Las variables proposicionales (en la Guía, etiquetas) se crean con v() y los nombres los eliges tú; solo tienen que ser consistentes dentro de la misma pregunta:

from qbank import *

A = v('A')    # variable proposicional A

Las fórmulas se construyen combinando variables con los operadores de Python:

La semántica también acepta True (siempre verdadero) o False (siempre falso). alguno y unoDe aceptan cualquier número de proposiciones.

Atención — precedencia de operadores: la precedencia de Python difiere de la lógica matemática. En lógica, → tiene menor precedencia que ∧ y ∨, por lo que A ∧ B → C se lee como (A ∧ B) → C. En Python, >> tiene mayor precedencia que & y |, así que v('A') & v('B') >> v('C') se evalúa como v('A') & (v('B') >> v('C')), que no es lo que se espera. Usa siempre paréntesis explícitos en implicaciones compuestas:

(v('A') & v('B')) >> v('C')   # correcto: (A ∧ B) → C
v('A') & v('B') >> v('C')     # incorrecto: A ∧ (B → C)

La función test(formula, hipotesis) comprueba si una fórmula es consecuencia lógica de una lista de fórmulas hipótesis:

test(v('C'), [v('A'), v('A') >> v('C')])    # True  (modus ponens)
test(v('C'), [v('B')])                      # False (B no implica C)
test(True,   [])                            # True
test(False,  [])                            # False

No necesitas llamar a test directamente: qbank lo invoca al generar las variantes. Conviene tener presente lo que responde: «¿se deduce esto de las hipótesis?», no «¿es verdad?». De la hipótesis v('crec') no se sigue -v('decr'), salvo que un axioma declare que ambas son excluyentes (unoDe(v('crec'), v('decr'))).

Un Supuesto es una afirmación que se añade al enunciado del problema y cuya semántica se incorpora como hipótesis para evaluar las cuestiones que le siguen.

Supuesto(enunciado, semantica, precond=True)

Un Supuesto con enunciado vacío es un axioma: añade su fórmula sin texto.

Supuesto('$\\mathcal{A}$ es verdadero. ', v('A'))
Supuesto('$\\mathcal{A} \\Rightarrow \\mathcal{C}$. ', v('A') >> v('C'))
Supuesto('', unoDe(v('inv'), v('sing')))          # axioma: los dos mundos son excluyentes

Si la precondición de un supuesto no se cumple en una variante concreta, esa variante se descarta.

Una Cuestion es una posible respuesta. qbank determina si es correcta o no según las hipótesis activas en cada variante.

Cuestion(enunciado, semantica, precond=True, exp="")

Cuestion("Entonces $\\mathcal{C}$ es verdadero", v("C"))
Cuestion("Esta afirmación es siempre falsa", False)
Cuestion("$\\mathcal{B}$ es consecuencia de $\\mathcal{A}$", v("B"), precond=v("A"))
Cuestion("$f(@{a}) < f(@{b})$", v("crec"), exp="Porque $@{a} < @{b}$ y $f$ es creciente.")

Semánticas y precondiciones como cadenas. Tanto Supuesto como Cuestion aceptan semantica y precond escritas como la cadena que las representa ("v('A') >> v('B')", "True", "lambda ns: ns['x'] > 0"), que es exactamente lo que guarda el formato JSON. Es la forma de escribir una lambda en Python si la pregunta se va a guardar con save_problema: una función Python no se puede serializar; su cadena, sí.

ProblemaTipo toma una lista plana de componentes y genera todas las combinaciones posibles, una variante por cada combinación.

ProblemaTipo(componentes, setup=None, export=None, seed=None, nombre=None)

Las funciones de exportación no leen export: pasa tú last_choice=, instances= y cols= a AMCblock, QuizMoodle, QuizAMCProfe y las demás (los ejemplos de este manual lo hacen). Los scripts de un banco de qbank-init sí lo leen de cada JSON.

El parámetro setup permite que los valores numéricos o simbólicos cambien en cada variante. En cada iteración:

1. Se ejecuta el setup y sus variables forman el espacio de nombres ns de la variante.
2. Los textos (enunciados, cuestiones y exp) que contengan marcadores @{variable} reciben la sustitución.
3. Las semánticas y precondiciones que sean lambda ns: ... se evalúan con ese diccionario.

El delimitador @ se eligió para evitar conflictos con el modo matemático de \LaTeX{}. Para una arroba literal, escribe @@.

{
  "version": "1",
  "tipo": "ProblemaTipo",
  "nombre": "L-01-Monotonia",
  "seed": 1,
  "setup": "import numpy as np\na = int(np.random.randint(1, 10))",
  "export": {"last_choice": true, "cols": 2, "instances": 6},
  "componentes": [
    "Texto fijo ",
    {"tipo": "Supuesto", "enunciado": "", "semantica": "unoDe(v('A'), v('B'))", "precond": "True"},
    [
      {"tipo": "Supuesto", "enunciado": "alternativa 1 ", "semantica": "v('A')", "precond": "True"},
      {"tipo": "Supuesto", "enunciado": "alternativa 2 ", "semantica": "v('B')", "precond": "True"}
    ],
    " Entonces:",
    [
      {"tipo": "Cuestion", "enunciado": "¿A?", "semantica": "v('A')", "precond": "True", "exp": ""},
      {"tipo": "Cuestion", "enunciado": "¿B?", "semantica": "v('B')", "precond": "True", "exp": ""}
    ],
    {"tipo": "Cuestion", "enunciado": "$a = @{a}$", "semantica": "True", "precond": "True", "exp": ""}
  ]
}

Cada Supuesto es un objeto con tipo, enunciado, semantica y precond; cada Cuestion añade exp. Las fórmulas y lambdas van como cadenas, exactamente como se escribirían en Python. Las barras de LaTeX se doblan (\\mathcal).

Puedes añadir claves propias de nivel superior, como "_nivel": "M" o "_tema": qbank las ignora al cargar y save_problema las conserva.

Regla para instances: con setup aleatorio, instances = max(1, ceil(60 / variantes por instancia)), para que la vista alumno tenga al menos 60 variantes; lint imprime el valor necesario.

problema_to_dict devuelve el dict y save_problema lo escribe en un fichero; load_problema acepta una ruta o un dict y devuelve un ProblemaTipo listo para iterar.

import os, tempfile
ruta = os.path.join(tempfile.gettempdir(), "ordenar.json")   # p. ej. preguntas/ordenar.json
save_problema(ordenar, ruta)
p2 = load_problema(ruta)                                    # o load_problema(dict)
assert problema_to_dict(p2) == problema_to_dict(ordenar)

(El ejemplo guarda en un directorio temporal para no tocar los JSON de ejemplosManual/, que usan las secciones siguientes.)

Para bancos de varios problemas en un solo fichero, save_banco(lista, ruta) y load_banco(ruta); los proyectos de qbank-init usan en cambio un fichero por pregunta.

El fichero ejemplosManual/matriz_rango.json:

{
  "version": "1",
  "tipo": "ProblemaTipo",
  "nombre": "matriz_rango",
  "seed": 7,
  "setup": "import numpy as np\nn = int(np.random.randint(3, 6))\nk = int(np.random.randint(2, n))",
  "export": {"last_choice": true, "cols": 2, "instances": 4},
  "componentes": [
    "Considere una matriz $A$ de $@{n}$ filas y $@{k}$ columnas. ",
    [
      {"tipo": "Supuesto", "enunciado": "Suponga que $A$ tiene rango máximo ($\\mathrm{rg}(A)=@{k}$). ",
       "semantica": "v('MaxRk')", "precond": "True"},
      {"tipo": "Supuesto", "enunciado": "Suponga que $A$ tiene rango deficiente ($\\mathrm{rg}(A)<@{k}$). ",
       "semantica": "-v('MaxRk')", "precond": "True"}
    ],
    "Indique qué afirmaciones son correctas: ",
    [
      {"tipo": "Cuestion", "enunciado": "Las $@{k}$ columnas de $A$ son linealmente independientes.",
       "semantica": "v('MaxRk')", "precond": "True", "exp": "…"},
      {"tipo": "Cuestion", "enunciado": "Alguna columna de $A$ es combinación lineal de las demás.",
       "semantica": "-v('MaxRk')", "precond": "True", "exp": "…"}
    ],
    "… (otros dos huecos: $A^\\top A$ invertible / singular; $Ax = 0$ con solución única / infinitas)"
  ]
}

p = load_problema("ejemplosManual/matriz_rango.json")
for etiqueta, partes in p.por_partes():
    for enunciado, cuestiones in partes:
        print(f"Variante {etiqueta}: {enunciado}")
        for texto, correcto, activa, exp in cuestiones:
            print(f"  {'✓' if correcto else '✗'} {texto}")
    if int(etiqueta) == 2:
        break
print(len(list(p.por_partes())), "variantes por instancia;",
      len(list(p.por_partes(instances=4))), "con instances=4")

Variante 1: Considere una matriz $A$ de $3$ filas y $2$ columnas. Suponga que $A$ tiene rango máximo ($\mathrm{rg}(A)=2$). Indique qué afirmaciones son correctas:
  ✓ Las $2$ columnas de $A$ son linealmente independientes.
  ✓ $A^\top A$ es invertible.
  ✓ El sistema $Ax = 0$ tiene solo la solución trivial.
Variante 2: Considere una matriz $A$ de $4$ filas y $2$ columnas. Suponga que $A$ tiene rango máximo ($\mathrm{rg}(A)=2$). Indique qué afirmaciones son correctas:
  ✓ Las $2$ columnas de $A$ son linealmente independientes.
  ✓ $A^\top A$ es invertible.
  ✗ El sistema $Ax = 0$ tiene infinitas soluciones.
16 variantes por instancia; 64 con instances=4

La lógica proposicional y los valores numéricos actúan de forma independiente: v('MaxRk') no «sabe» cuánto valen \(n\) y \(k\); su valor de verdad lo determina el supuesto elegido. El setup solo aporta los números que aparecen en el texto. El segundo supuesto afirma -v('MaxRk') directamente, y por eso las cuestiones con esa semántica se deducen sin necesidad de un axioma unoDe.

problema_to_python devuelve el código Python que recrea el problema como listas editables, y save_problema_py lo escribe en un fichero. El resultado se ejecuta tal cual y puede volver a guardarse con save_problema: si el problema tiene setup, su código aparece en la cadena _SETUP, y las lambdas van entre comillas.

codigo = problema_to_python(load_problema("ejemplosManual/ejercicio.json"))
print("\n".join(codigo.splitlines()[:30]))   # las primeras 30 líneas

from qbank import Supuesto, Cuestion, ProblemaTipo
from calcprop import *

ejercicio = [
    r'Considere ',
    [
        Supuesto(
            enunciado = r'$\mathcal{A}$ ',
            semantica = v('A'),
            precond = True
        ),
        Supuesto(
            enunciado = r'$\mathcal{B}$ ',
            semantica = v('B'),
            precond = True
        ),
    ],
    [
        Supuesto(
            enunciado = r'y que $\mathcal{A}\Rightarrow\mathcal{C}$. ',
            semantica = v('A') >> v('C'),
            precond = True
        ),
        Supuesto(
            enunciado = r'y que $\mathcal{B}\Leftrightarrow\mathcal{D}$. ',
            semantica = v('B') ** v('D'),
            precond = True
        ),
    ],
    r'Entonces, con toda seguridad: ',

Cinco ficheros ilustran, de forma acumulativa, las mecánicas de este capítulo, y Tutorial.ipynb los recorre ejecutándolos: ej_a_literales (valores de verdad literales, tres huecos), ej_b_mundos (una lista de Supuesto), ej_c_precond (axioma unoDe y precond por mundo), ej_d_setup_vars (setup, @{var}, seed, instances y exp dinámico) y ej_e_lambda (semántica lambda que inyecta fórmulas). Los otros cuatro (ejercicio, matriz_rango, numeros y superheroes) son los que usan este manual y Demo.ipynb. Todos pasan lint sin ERROR ni AVISO.

AMCblock(nombre, etiqueta, enunciado, cuestiones,
         last_choice=False, cols=1, profe=False, *,
         aux_latex="", last_choice_text="Ninguna de las anteriores")

p = load_problema("ejemplosManual/ejercicio.json")
etiqueta, partes = next(iter(p.por_partes()))
enunciado, cuestiones = partes[0]
print(AMCblock("MiCuestionario", etiqueta, enunciado, cuestiones, last_choice=True, cols=2))

\element{MiCuestionario}{
 \begin{questionmult}{MiCuestionario-1}
  Considere $\mathcal{A}$ y que $\mathcal{A}\Rightarrow\mathcal{C}$. Entonces, con toda seguridad:
   \begin{multicols}{2}\AMCBoxedAnswers
      \begin{choices}
       \correctchoice{se da $\mathcal{C}$}
       \correctchoice{se da $\mathcal{A}$}
       \correctchoice{se dan $\mathcal{A}$ y $\mathcal{C}$}
       \lastchoices
       \wrongchoice  {Ninguna de las anteriores}
      \end{choices}
   \end{multicols}
 \end{questionmult} }

Para escribir todas las variantes de la vista alumno:

with open("preguntas.tex", "w") as f:
    for etiqueta, partes in p.por_partes():
        enunciado, cuestiones = partes[0]
        f.write(AMCblock("MiCuestionario", etiqueta, enunciado, cuestiones, last_choice=True, cols=2))

Un AMCblock por parte produciría dos preguntas con el mismo identificador y la segunda sin las hipótesis. AMC_multipart genera un único questionmult con un bloque de casillas por parte, cada uno con su propia opción por defecto si last_choice:

AMC_multipart(nombre, etiqueta, enunciado, partes,
              last_choice=False, cols=1, profe=False, *,
              aux_latex="", last_choice_text="Ninguna de las anteriores")

partes es la lista de pares (enunciado, cuestiones) que devuelven por_partes() y por_partes_profe(); enunciado es un texto común previo, normalmente "" porque el de la primera parte ya contiene las hipótesis. Los demás parámetros son los de AMCblock.

multi = load_problema("ejemplosManual/superheroes.json")      # tres partes
with open("preguntas_multi.tex", "w") as f:
    for etiqueta, partes in multi.por_partes():
        if len(partes) > 1:
            f.write(AMC_multipart("Superheroes", etiqueta, "", partes, last_choice=True))
        else:
            f.write(AMCblock("Superheroes", etiqueta, partes[0][0], partes[0][1], last_choice=True))

QuizAMCProfe(nombre, directorio, problema, cols=1, *, last_choice=False,
             aux_latex="", last_choice_text="Ninguna de las anteriores")
# Devuelve int: número de entradas escritas (una por mundo)

Recorre por_partes_profe() y escribe en directorio/nombre_profe.tex una pregunta AMC por mundo (con AMC_multipart si tiene varias partes), con todas las cuestiones de cada hueco marcadas y las rechazadas en \explain{}. problema puede ser un ProblemaTipo o un diccionario {nombre: ProblemaTipo}. directorio admite / final o no.

Los ficheros generados se incluyen en el preámbulo del documento AMC con la orden \input{preguntas.tex}; dentro de \onecopy, \insertgroup[1]{MiCuestionario} inserta una variante por copia (sin el [1] se insertarían todas) y \shufflegroup las baraja. El README de la plantilla da el procedimiento completo; consulta la documentación de AMC para el formato del documento.

QuizMoodle     (nombre, directorio, problema, last_choice=False, instances=1, *,
                aux_latex="", last_choice_text="Las demás opciones son falsas")
# Devuelve int: número de variantes escritas
QuizMoodleProfe(nombre, directorio, problema, *, aux_latex="",
                last_choice=False, instances=1,
                last_choice_text="Las demás opciones son falsas")

QuizMoodleProfe solo admite last_choice, instances y last_choice_text por palabra clave; con los mismos valores que en QuizMoodle escribe las mismas variantes. Las dos escriben directorio/nombre.tex: para tener ambas vistas, dales nombres distintos (p. ej. MiCuestionario y MiCuestionarioProfe). Como el resto de exportadores, ninguna de las dos lee export del problema: pásale last_choice=True si la pregunta usa la opción por defecto (o, con ejercicio.json, 16 de las 48 variantes saldrían sin ninguna opción correcta).

Cada bloque cloze recibe un peso igual a su número de opciones menos uno, y Moodle lo puntúa como una opción múltiple con varias respuestas (las correctas marcadas suman, las incorrectas marcadas restan, sin bajar de cero).

p = load_problema("ejemplosManual/ejercicio.json")
QuizMoodle("EjemploMoodle", "ejemplosManual/", p, last_choice=True)

cd ejemplosManual
xelatex EjemploMoodle.tex

Se generan ejemplosManual/EjemploMoodle-moodle.xml (para importar en Moodle) y ejemplosManual/EjemploMoodle.pdf (vista previa de las preguntas). Las letras acentuadas, la ñ, la ü y los signos ¿ y ¡ las convierte codchar (ver la referencia) de forma automática.

Un ProblemaTipo cuya lista plana abre varias partes se exporta como una pregunta cloze con un bloque de opciones por parte, sin hacer nada especial. El fichero ejemplosManual/superheroes.json es un ejercicio de tres partes (cuatro mundos, uno por héroe, y seis huecos repartidos en tres bloques):

p = load_problema("ejemplosManual/superheroes.json")
etiqueta, partes = next(iter(p.por_partes()))
for enunciado, cuestiones in partes:
    print(enunciado.strip() or "(sin texto)")
    for texto, correcto, _, exp in cuestiones:
        print(f"    {'✓' if correcto else '✗'} {texto}")
print(len(list(p.por_partes())), "variantes")

Conteste qué afirmaciones sobre Spider-Man (Peter Parker) son ciertas. Uno de sus superpoderes consiste en
    ✓ tener sentidos superdesarrollados
    ✗ volar
En su vestimenta destaca:
    ✗ la capa
    ✓ el color azul
En cuanto al origen de sus superpoderes:
    ✓ son fruto de una mutación
    ✗ realmente son fruto de entrenamiento y tecnología
256 variantes

import os
os.makedirs("ejemplosManual/exportaciones", exist_ok=True)
QuizMoodle("Superheroes", "ejemplosManual/exportaciones", p, last_choice=True)  # Moodle: cloze
with open("ejemplosManual/exportaciones/superheroes_amc.tex", "w") as f:       # AMC: un questionmult
    for etiqueta, partes in p.por_partes():
        f.write(AMC_multipart("Superheroes", etiqueta, "", partes, last_choice=True))

Importar a mano (Banco de preguntas → Importar) basta para una pregunta suelta, pero al corregir una pregunta ya subida hay que borrar antes sus variantes viejas de la categoría, y con cientos de variantes por pregunta eso es tedioso y propenso a errores. El banco qbank-PEconometria tiene dos scripts que reproducen desde el terminal los formularios de Moodle con la sesión del navegador, sin servicios web ni permisos de administración: scripts/moodle_sync.py (banco de preguntas) y scripts/moodle_quiz.py (cuestionarios). No forman parte de la plantilla: están escritos para el Campus Virtual de la UCM (Moodle 4.3 con auth_saml2; constantes BASE y COURSEID al principio de moodle_sync.py, o --base y --curso). Para otro Moodle hay que copiarlos y comprobar que sus páginas son iguales; si no lo son, los scripts fallan sin tocar nada.

La sesión. Entra en el campus con el navegador, abre las herramientas de desarrollo (F12; Firefox: Almacenamiento → Cookies; Chrome: Application → Cookies), copia el valor de la cookie MoodleSession del dominio del campus y guárdalo, solo el valor, en ~/.config/moodle-ucm/session (permisos 600) o en la variable MOODLE_SESSION. Equivale a tu contraseña mientras dure la sesión: no la pegues en ningún fichero versionado. Caduca con la sesión del navegador (en la UCM, tras una hora de inactividad); si un script dice que no hay sesión, copia otra.

Siempre simulan. Sin --ejecutar los dos scripts solo dicen lo que harían; ejecútalos primero así y compara con lo que esperas.

PY=~/ruta/a/qbank/.venv/bin/python
$PY scripts/moodle_sync.py categorias                      # categorías y nº de preguntas
$PY scripts/moodle_sync.py preguntas L-14-LeerElVIF        # ids de una categoría
$PY scripts/moodle_sync.py reimportar build/moodle/X.xml   # simula
$PY scripts/moodle_sync.py reimportar build/moodle/X.xml --ejecutar
$PY scripts/moodle_sync.py importar X.xml --ejecutar       # solo importar
$PY scripts/moodle_sync.py borrar L-14-A L-14-B --ejecutar # vaciar categorías

$PY scripts/moodle_quiz.py cuestionarios                   # cmid, nombre, ranuras, apertura
$PY scripts/moodle_quiz.py ranuras 185724                  # ranuras de un cuestionario
$PY scripts/moodle_quiz.py aleatorias 185725 L-15-A L-15-B --ejecutar

Actualizar preguntas: reimportar. Recibe un XML con las preguntas corregidas (para unas pocas, fusiona solo sus *-moodle.xml en un fichero aparte; el de todo el banco también vale). Para cada categoría $course$/top/<nombre> del XML que ya exista borra sus preguntas visibles y, después, importa el XML una sola vez: Moodle reutiliza la categoría del mismo nombre (conserva su id) y crea las que falten. Las categorías no se borran nunca, y es deliberado: las ranuras aleatorias de un cuestionario filtran por el id de la categoría, y borrar una categoría para volver a importarla deja esas ranuras rotas. --solo y --excluir limitan las categorías afectadas. Salvaguardas: aborta si el recuento que muestra Moodle no cuadra con el listado o si una pregunta aparece en dos categorías; fotografía todo el banco antes y después de borrar y se detiene antes de importar si cambió algo fuera de lo previsto; al final compara el recuento de cada categoría con el XML y dice TODO CORRECTO.

Cuestionarios: aleatorias. Añade al final del cuestionario (por su cmid, el número de mod/quiz/view.php?id=…) una ranura «pregunta aleatoria» por cada categoría dada, una por página y en el orden dado, y comprueba después que las ranuras nuevas son las pedidas. Usa el mismo servicio AJAX que el botón del navegador.

Lo que se hace a mano, en el navegador: las fechas de apertura y cierre, la visibilidad para los estudiantes y quitar ranuras. moodle_quiz.py tiene una orden apertura que reenvía el formulario de ajustes, pero no se usa: la única vez que se probó, Moodle devolvió un 404 sin guardar nada y la sesión quedó bloqueada.

Con moderación. El cortafuegos de la UCM llegó a dejar colgadas dos sesiones (toda petición con esa cookie quedaba sin respuesta, y durante un rato no se pudo abrir sesión desde la misma IP) tras ráfagas de peticiones rápidas. Por eso los scripts esperan dos segundos entre peticiones. Haz una tarea, comprueba el resultado y para.

Supuesto(enunciado, semantica, precond=True)
Cuestion(enunciado, semantica, precond=True, exp="")
    semantica y precond: fórmula calcprop, True/False, lambda ns: …, o la cadena de cualquiera de ellos
ProblemaTipo(componentes, setup=None, export=None, seed=None, nombre=None)
    → .por_partes(instances=1, base_seed=None, verbose=False)   vista alumno, por partes
    → .por_partes_profe(verbose=True)                           vista profe: todas las cuestiones
    → itera (etiqueta, enunciado, cuestiones)                    solo ejercicios de una parte
ProblemaVF(enunciado, cuestiones, NumPreguntas)                  verdadero/falso (apéndice)
ProblemaTipoEditor(source=None)                                  editor visual en Jupyter (apéndice)
qbank.__version__                                                versión instalada, p. ej. "0.6.0"

problema_from_dict(d)              → ProblemaTipo o ProblemaVF
problema_to_dict(problema)         → dict (conserva las claves propias del JSON)
load_problema(ruta_o_dict)         → ProblemaTipo o ProblemaVF
save_problema(problema, ruta)
load_banco(ruta)                   → lista de problemas
save_banco(problemas, ruta)        # acepta lista o dict
problema_to_python(problema, varname="ejercicio")  → str   (ProblemaTipo)
save_problema_py(problema, ruta, varname="ejercicio")

AMCblock     (nombre, etiqueta, enunciado, cuestiones,
              last_choice=False, cols=1, profe=False, *,
              aux_latex="", last_choice_text="Ninguna de las anteriores")      → str
AMC_multipart(nombre, etiqueta, enunciado, partes,
              last_choice=False, cols=1, profe=False, *,
              aux_latex="", last_choice_text="Ninguna de las anteriores")      → str
QuizAMCProfe (nombre, directorio, problema, cols=1, *, last_choice=False,
              aux_latex="", last_choice_text="Ninguna de las anteriores")      → int (mundos)
AMC_VF       (nombre, etiqueta, enunciado, cuestiones, opc=None)               → str (ProblemaVF)

QuizMoodle      (nombre, directorio, problema, last_choice=False, instances=1, *,
                 aux_latex="", last_choice_text="Las demás opciones son falsas")  → int (variantes)
QuizMoodleProfe (nombre, directorio, problema, *, aux_latex="",
                 last_choice=False, instances=1,
                 last_choice_text="Las demás opciones son falsas")                → int
QuizVFMoodle    (nombre, directorio, GenVar, num, opc=None)                       (ProblemaVF)
codchar(s)      vocales acentuadas minúsculas y ñ → secuencias LaTeX (lo aplican las funciones Moodle)

QuizLectura(nombre, directorio, problemas, *, aux_latex="", titulo=None,
            last_choice=None, last_choice_text="Ninguna de las anteriores",
            extras=0, max_semillas=400)                                    → int (ejemplos)
ProblemaTipo.por_partes_lectura(seed=None, verbose=False, descartes=False)
    # → Lectura(etiqueta, mundo, ns, partes, descarte); ParteLectura(enunciado, huecos);
    #   Alternativa(texto, valor, exp, motivo)

lint(problema_o_ruta, instances=None, seed=None, patrones=None)  → list[Aviso]
    # Aviso(nivel, codigo, mensaje, donde); nivel ∈ {ERROR, AVISO, INFO}; errores primero
    # patrones=True (o nº de sorteos): añade la regla 11, patrones memorizables (más lenta)
tabla_mundos(problema_o_ruta)                     → str   # tabla Cuestion × mundo
python -m qbank.lint FICHEROS.json [--instances N] [--seed S] [--tabla] [--quiet] [--patrones [N]]
    # también `qbank-lint`; código de salida 1 si hay algún ERROR

qbank-init DIR [--forzar]        copia la plantilla (preguntas/, scripts/, Makefile, config.py,
                                 nueva_pregunta.py, README.org, prompts/, CLAUDE.md) en DIR; equivale a
                                 python -m qbank._plantilla DIR

v("X")           variable proposicional X
-v("X")          negación de X
v("X") & v("Y")  conjunción (X ∧ Y)
v("X") | v("Y")  disyunción (X ∨ Y)
v("X") >> v("Y") implicación (X → Y)
v("X") ** v("Y") bicondicional (X ↔ Y)
alguno(P, Q, R)  al menos una de la lista es verdadera
unoDe(P, Q, R)   exactamente una de la lista es verdadera
True             tautología (siempre verdadero)
False            contradicción (siempre falso)

test(formula, lista_de_formulas)  → bool
    Devuelve True si formula es consecuencia lógica de la lista de hipótesis.

Si un Supuesto o una Cuestion tiene una precondición que no se satisface en una combinación determinada, esa variante completa se descarta. Es el comportamiento esperado: evita combinaciones de hipótesis incoherentes. En la vista profe, las cuestiones rechazadas se ven; un Supuesto rechazado hace desaparecer la variante también allí.

Los campos enunciado y exp son cadenas Python que se insertan tal cual en el .tex. Usa cadenas crudas (r"...") para no doblar las barras invertidas:

Cuestion(r"$\mathbf{X}^\top\mathbf{X}$ es invertible", -v("Mcoli"))

En JSON cada barra se dobla: "$\\mathbf{X}^\\top\\mathbf{X}$".

El símbolo % es, en LaTeX, el inicio de un comentario: escribe siempre \% (y fuera de los dólares: al $5$\,\%). Nada de ° (usa ^\circ) ni de comillas angulares «» o rectas "…" (usa ``así''): el paquete moodle no las admite o las deforma. Acentos, ñ, ¿ y ¡ sí se pueden teclear. lint avisa de todo esto; la Guía lo explica.

Con $$...$$, nunca \[...\] ni \(...\) directamente: el paquete moodle necesita los dólares, y los exportadores AMC convierten $$...$$ a \[...\] automáticamente (automultiplechoice a veces produce errores «Missing $» con $$). Separa dos expresiones en línea contiguas con un espacio ($A$ $B$, no $A$$B$).

Sí, con \includegraphics en el texto (el enunciado es LaTeX), pero cada destino la quiere de una forma. En AMC vale un PDF a tamaño natural; los documentos de la plantilla ya cargan graphicx:

"Observe la figura. \\begin{center}\\includegraphics{fig.pdf}\\end{center} Entonces:"

El paquete moodle incrusta la imagen en el XML (en base64) y solo sabe de mapas de bits: hace falta un PNG del mismo nombre y compilar con pdflatex -shell-escape, porque llama a base64. Un patrón que funciona: generar fig.pdf y fig.png (p. ej. con pdftoppm -png -r 200), referenciar el PDF en el JSON y, en el script de Moodle, sustituir .pdf por .png en el .tex (con width igual a la anchura natural del PDF, para que Moodle no lo agrande); el banco de Probabilidad y Estadística del autor lo hace así en su scripts/gen_moodle.py. Si la ruta de la figura va en el setup como variable e interpolada con @{fig}, la misma pregunta sirve para los dos destinos. Ten en cuenta el tamaño: una figura en cada una de 150 variantes multiplica el XML.

codchar(s) convierte las letras del español con tilde o diéresis, mayúsculas y minúsculas, y la ñ a órdenes de acento de LaTeX (á → \'{a}, ü → \"{u}), y los signos ¿ y ¡ a \textquestiondown y \textexclamdown. Las funciones Moodle lo aplican automáticamente; no hace falta llamarlo a mano. El paquete moodle convierte esas órdenes en entidades HTML (á, ü, ¿), que se leen bien se declare el XML como se declare. Un carácter que codchar no cubra (las comillas “ ”, por ejemplo) pasa tal cual: con xelatex sale bien; con pdflatex llega al XML en UTF-8 con la declaración iso-8859-1 y lo corrige scripts/fix_moodle_xml.py de la plantilla (ver la sección 6). Hasta la 0.7.0 codchar solo cubría las minúsculas acentuadas y la ñ, y un banco con una copia antigua de ese script mostraba en Moodle antigüedad o ¿Qué. Para AMC no suele hacer falta si el documento principal usa inputenc con UTF-8.

Pasa un diccionario a QuizMoodle: todas van al cuestionario MiExamen, y cada clave da nombre a sus variantes (Seccion-A-1, Seccion-A-2, …):

QuizMoodle("MiExamen", "salida/", {"Seccion-A": p_a, "Seccion-B": p_b}, last_choice=True)

Un banco de qbank-init guarda cada pregunta en su propio fichero, y el script scripts/merge_moodle_xml.py fusiona sus XML en _banco.xml.

ProblemaVF sirve para un formato distinto: un banco de afirmaciones del que se extrae aleatoriamente un subconjunto en cada variante. No usa cálculo proposicional; la corrección de cada ítem se indica con True o False. No lo revisa lint ni lo exportan los scripts de qbank-init: para un banco nuevo, una pregunta de tres huecos de ProblemaTipo cubre el mismo uso con todas las herramientas.

ProblemaVF(enunciado, cuestiones, NumPreguntas)

enunciado = "Indique qué afirmaciones son verdaderas:"
banco = [
    ("Todo alumno que va a clase aprueba",   False),
    ("Todo alumno que sabe aprueba",         True),
    ("Si suspenden todos es frustrante",     True),
    ("Si aprueban todos eres buen profesor", False),
]
import random
random.seed(42)
GenVar = iter(ProblemaVF(enunciado, banco, 3))  # 3 ítems por variante

for _ in range(2):
    etiqueta, enunc, cuestiones = next(GenVar)
    print(f"Variante {etiqueta}: {enunc}")
    for texto, correcto in cuestiones:
        print(f"  {'✓' if correcto else '✗'} {texto}")

Variante 1: Indique qué afirmaciones son verdaderas:
  ✗ Todo alumno que va a clase aprueba
  ✗ Si aprueban todos eres buen profesor
  ✓ Todo alumno que sabe aprueba
Variante 2: Indique qué afirmaciones son verdaderas:
  ✓ Todo alumno que sabe aprueba
  ✗ Todo alumno que va a clase aprueba
  ✓ Si suspenden todos es frustrante

Se exporta con AMC_VF(nombre, etiqueta, enunciado, cuestiones) (un bloque por variante) y QuizVFMoodle(nombre, directorio, GenVar, num) (num variantes). Se guarda y carga en JSON sin restricciones.

ProblemaTipoProfe

emite DeprecationWarning; usa ProblemaTipo(...).por_partes_profe(). Firma:

ProblemaTipoProfe(lista, setup=None)

ProblemaMultiParte y SubPregunta

ProblemaMultiParte emite DeprecationWarning y devuelve un ProblemaTipo equivalente (lista plana); SubPregunta es su contenedor. Para código nuevo, define directamente un ProblemaTipo y recórrelo con por_partes(). Firmas:

ProblemaMultiParte(componentes, subpreguntas, setup=None)
SubPregunta(intro, cuestiones)

ProblemaTipoEditor es un formulario interactivo para diseñar un ProblemaTipo desde un cuaderno de Jupyter, sin escribir la lista de listas a mano. Requiere ipywidgets:

pip install "calcprop-qbank[jupyter]"

(la orden con git+https://… de la instalación rápida ya incluye el extra [jupyter]).

En JupyterLab ≥ 4 es necesario que la extensión @jupyter-widgets/jupyterlab-manager esté habilitada: compruébalo con jupyter labextension list. Si el widget se muestra como texto (VBox(children=...), ejecuta una sola vez desde el terminal:

mkdir -p ~/.local/share/jupyter/labextensions/@jupyter-widgets
ln -sfn $(python -c "import jupyterlab_widgets, os; \
  print(os.path.dirname(jupyterlab_widgets.__file__))")/labextension \
  ~/.local/share/jupyter/labextensions/@jupyter-widgets/jupyterlab-manager

y reinicia JupyterLab (en Jupyter Notebook clásico no hace falta).

from qbank import ProblemaTipoEditor
editor = ProblemaTipoEditor()                   # editor vacío
editor = ProblemaTipoEditor('mi_problema.json') # cargar desde fichero
p = editor.to_problema()                        # ProblemaTipo listo para iterar
d = editor.to_dict()                            # dict JSON equivalente
save_problema(editor.to_problema(), "mi_problema.json")   # o el botón 💾 Guardar

El editor no tiene un método save: para guardar, usa el botón 💾 Guardar o pasa editor.to_problema() a save_problema, como en la última línea del bloque.

El formulario tiene una cabecera (Nombre:, Setup: con el campo semilla:, y Export: con la casilla last_choice y el campo cols:), la lista de huecos y una barra de botones. Cada hueco (Hueco 1, Hueco 2, etc.) tiene un tipo, texto, supuestos o cuestiones, y sus alternativas (+ alt): filas con enunciado, semántica, precondición y, en las cuestiones, explicación. Los botones de cada hueco lo suben o bajan (▲ / ▼), insertan otro hueco debajo (＋) o lo borran (✕); el botón + hueco añade uno al final. La barra inferior tiene ▶ Preview (genera hasta N variantes, con la casilla vista profe), { } JSON y </> .py (muestran el JSON o el guion Python), 💾 Guardar y 📂 Cargar (en el fichero indicado) y ⬇ .json / ⬇ .py (descargas al navegador). Al guardar conserva las claves de export que el formulario no edita (como instances) y las claves propias del JSON. Demo.ipynb (sección 8) lo muestra en uso.