Familiarizzap / src /questionnaire.py
Sibucs's picture
Pubblicato da GitHub: f51db87
1aa20d3 verified
Raw History Blame Contribute Delete
7.04 kB
"""Validated questionnaire used after the four-stage recommended route."""
from __future__ import annotations
from typing import Any, Iterable
QUESTIONNAIRE_VERSION = "pilot-2026-11-07"
TEACHING_EXPERIENCE_CHOICES = (
"Meno di 1 anno",
"1-3 anni",
"4-10 anni",
"Pi霉 di 10 anni",
)
TEACHING_CONTEXT_CHOICES = (
"Corsi per adulti",
"Scuola",
"Universit脿",
"Formazione di interpreti",
"Corsi privati o individuali",
"Associazioni ed enti del terzo settore",
)
RATING_ITEMS = (
(
"q1_qcer_familiarity",
"Prima di questa prova, quanto conoscevi il QCER e i suoi descrittori?",
"1 = per nulla 路 5 = molto bene",
),
(
"q4_faster_orientation",
"Usare FamiliarizzApp mi permetterebbe di orientarmi pi霉 rapidamente "
"tra i livelli del QCER.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q5_effective_recognition",
"Usare FamiliarizzApp renderebbe pi霉 efficace il mio modo di "
"riconoscere il livello di un descrittore.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q6_easier_qcer_work",
"Usare FamiliarizzApp renderebbe pi霉 facile il mio lavoro con il QCER.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q7_difficult_to_learn",
"Imparare a usare FamiliarizzApp 猫 stato difficile per me.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q8_clear_interaction",
"La mia interazione con FamiliarizzApp 猫 stata chiara e comprensibile.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q9_easy_to_gain_familiarity",
"Credo che per me sarebbe facile acquisire dimestichezza nell鈥檜so di "
"FamiliarizzApp.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q10_easy_overall",
"Nel complesso, trovo FamiliarizzApp facile da usare.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q11_reuse_intention",
"Ho intenzione di usare di nuovo FamiliarizzApp nei prossimi mesi.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q12_recommend_to_colleague",
"Consiglierei FamiliarizzApp a un/a collega che insegna LIS.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q13_feedback_helpfulness",
"I feedback ricevuti dopo un tentativo mi hanno aiutato a capire "
"perch茅 il livello era quello.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
(
"q14_recognition_confidence",
"Dopo questa prova mi sento pi霉 sicuro/a nel riconoscere il livello "
"QCER di un descrittore.",
"1 = per nulla d鈥檃ccordo 路 5 = completamente d鈥檃ccordo",
),
)
RATING_KEYS = tuple(item[0] for item in RATING_ITEMS)
_RATING_LABELS = {key: text for key, text, _ in RATING_ITEMS}
QUESTIONNAIRE_RESEARCH_ITEMS = (
(
"data_collection_consent",
"Consenso alla raccolta e al trattamento dei dati del questionario",
),
("q1_qcer_familiarity", f"1. {_RATING_LABELS['q1_qcer_familiarity']}"),
("q2_teaching_experience", "2. Da quanti anni insegni LIS?"),
(
"q3_teaching_contexts",
"3. In quale contesto insegni?",
),
*(
(key, f"{number}. {_RATING_LABELS[key]}")
for number, key in enumerate(RATING_KEYS[1:], start=4)
),
(
"q15_problems",
"15. Quali problemi hai trovato usando FamiliarizzApp?",
),
(
"q16_positive_aspects",
"16. Ci sono lati positivi dell鈥檃pplicazione che vuoi sottolineare?",
),
)
class QuestionnaireValidationError(ValueError):
"""Raised when a required questionnaire response is missing or invalid."""
def questionnaire_is_submitted(
events: Iterable[dict[str, Any]],
version: str = QUESTIONNAIRE_VERSION,
) -> bool:
return any(
event.get("event_type") == "questionnaire_submitted"
and event.get("questionnaire_version") == version
for event in events
)
def validate_questionnaire(payload: dict[str, Any]) -> dict[str, Any]:
"""Return a compact, serialisable response set or a friendly error."""
if payload.get("data_collection_consent") is not True:
raise QuestionnaireValidationError(
"Per inviare il questionario devi confermare il consenso alla "
"raccolta delle risposte."
)
experience = str(payload.get("q2_teaching_experience") or "").strip()
if experience not in TEACHING_EXPERIENCE_CHOICES:
raise QuestionnaireValidationError(
"Indica da quanti anni insegni LIS."
)
raw_contexts = payload.get("q3_teaching_contexts") or []
if not isinstance(raw_contexts, (list, tuple)):
raw_contexts = []
contexts = [str(value).strip() for value in raw_contexts if str(value).strip()]
if any(value not in TEACHING_CONTEXT_CHOICES for value in contexts):
raise QuestionnaireValidationError(
"Una delle risposte sul contesto di insegnamento non 猫 valida."
)
context_other = _clean_text(payload.get("q3_teaching_context_other"), 500)
if not contexts and not context_other:
raise QuestionnaireValidationError(
"Indica almeno un contesto di insegnamento oppure compilane uno "
"nel campo 芦Altro禄."
)
normalised: dict[str, Any] = {
"data_collection_consent": True,
"q2_teaching_experience": experience,
"q3_teaching_contexts": list(dict.fromkeys(contexts)),
"q3_teaching_context_other": context_other,
}
for key in RATING_KEYS:
value = payload.get(key)
try:
rating = int(value)
except (TypeError, ValueError) as exc:
raise QuestionnaireValidationError(
"Rispondi a tutte le domande con scala da 1 a 5."
) from exc
if rating not in {1, 2, 3, 4, 5}:
raise QuestionnaireValidationError(
"Le risposte su scala devono essere comprese tra 1 e 5."
)
normalised[key] = rating
normalised["q15_problems"] = _clean_text(payload.get("q15_problems"), 4000)
normalised["q16_positive_aspects"] = _clean_text(
payload.get("q16_positive_aspects"), 4000
)
return normalised
def _clean_text(value: Any, maximum: int) -> str:
text = " ".join(str(value or "").split())
if len(text) > maximum:
raise QuestionnaireValidationError(
f"Una risposta aperta supera il limite di {maximum} caratteri."
)
return text