Familiarizzap / src /catalog.py
Sibucs's picture
Pubblicato da GitHub: f51db87
1aa20d3 verified
Raw History Blame Contribute Delete
8.5 kB
from __future__ import annotations
import json
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Iterable
from .settings import Settings
PILOT_CEFR_LEVELS = ["A1", "A2", "A2+", "B1", "B1+", "B2"]
DEMO_CEFR_LEVELS = [*PILOT_CEFR_LEVELS, "C1", "C2"]
REQUIRED_FIELDS = {
"descriptor_id",
"schema",
"modality",
"activity",
"scale",
"correct_level",
"descriptor_text",
"rationale",
"hint_1",
"hint_2",
"language",
"source",
"source_version",
"license_or_permission",
"content_version",
"status",
"active",
}
TEXT_FIELDS = {
"schema",
"modality",
"activity",
"scale",
"descriptor_text",
"rationale",
"hint_1",
"hint_2",
}
class CatalogError(ValueError):
"""Raised when the descriptor catalog is invalid."""
@dataclass(frozen=True)
class CatalogLoadResult:
catalog: "Catalog"
source_label: str
is_demo: bool
class Catalog:
def __init__(
self,
descriptors: Iterable[dict[str, Any]],
*,
allowed_statuses: Iterable[str] = ("approved",),
allowed_levels: Iterable[str] = PILOT_CEFR_LEVELS,
):
validated: list[dict[str, Any]] = []
seen_ids: set[str] = set()
status_filter = {
str(status).strip().casefold() for status in allowed_statuses
}
level_order = [
str(level).strip().upper() for level in allowed_levels
]
for raw in descriptors:
missing = REQUIRED_FIELDS.difference(raw)
if missing:
raise CatalogError(
"Campi mancanti nel catalogo: " + ", ".join(sorted(missing))
)
item = dict(raw)
for field in TEXT_FIELDS:
item[field] = str(item[field] or "").strip()
descriptor_id = str(item["descriptor_id"]).strip()
if not descriptor_id or descriptor_id in seen_ids:
raise CatalogError(
f"Identificativo mancante o duplicato: {descriptor_id!r}"
)
seen_ids.add(descriptor_id)
item["descriptor_id"] = descriptor_id
item["correct_level"] = str(item["correct_level"]).strip().upper()
if item["correct_level"] not in level_order:
raise CatalogError(
f"Livello QCER non valido per {descriptor_id}: "
f"{item['correct_level']}"
)
item["status"] = str(item["status"]).strip().casefold()
if not isinstance(item["active"], bool):
raise CatalogError(
f"Il campo active deve essere booleano per {descriptor_id}."
)
if (
item["active"]
and item["status"] in status_filter
and str(item["scale"]).strip()
and str(item["descriptor_text"]).strip()
and str(item["descriptor_text"]).strip().casefold()
!= "nessun descrittore"
):
validated.append(item)
if not validated:
raise CatalogError("Il catalogo non contiene descrittori utilizzabili.")
self._descriptors = validated
self._by_id = {item["descriptor_id"]: item for item in validated}
self._level_order = level_order
@classmethod
def from_json(
cls,
path: Path,
*,
allowed_statuses: Iterable[str] = ("approved",),
allowed_levels: Iterable[str] = PILOT_CEFR_LEVELS,
) -> "Catalog":
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as exc:
raise CatalogError(f"Impossibile leggere il catalogo: {exc}") from exc
if not isinstance(payload, list):
raise CatalogError("Il catalogo deve essere una lista JSON.")
return cls(
payload,
allowed_statuses=allowed_statuses,
allowed_levels=allowed_levels,
)
def get(self, descriptor_id: str) -> dict[str, Any]:
try:
return dict(self._by_id[descriptor_id])
except KeyError as exc:
raise CatalogError(f"Descrittore sconosciuto: {descriptor_id}") from exc
def all(self) -> list[dict[str, Any]]:
return [dict(item) for item in self._descriptors]
@property
def level_order(self) -> list[str]:
return list(self._level_order)
def choices(
self,
field: str,
*,
schema: str | None = None,
modality: str | None = None,
activity: str | None = None,
) -> list[str]:
items = self._descriptors
filters = {
"schema": schema,
"modality": modality,
"activity": activity,
}
for key, value in filters.items():
if value is not None:
items = [item for item in items if item[key] == value]
return sorted(
{
str(item[field]).strip()
for item in items
if str(item[field]).strip()
}
)
def for_scale(
self, schema: str, modality: str, activity: str, scale: str
) -> list[dict[str, Any]]:
return [
dict(item)
for item in self._descriptors
if item["schema"] == schema
and item["modality"] == modality
and item["activity"] == activity
and item["scale"] == scale
]
def levels_for(self, descriptor_ids: list[str]) -> list[str]:
levels = {self._by_id[item_id]["correct_level"] for item_id in descriptor_ids}
return [level for level in self._level_order if level in levels]
def level_distance(self, first: str, second: str) -> int:
try:
return abs(
self._level_order.index(str(first).strip().upper())
- self._level_order.index(str(second).strip().upper())
)
except ValueError as exc:
raise CatalogError(
f"Impossibile calcolare la distanza tra {first!r} e {second!r}."
) from exc
def load_catalog(settings: Settings) -> CatalogLoadResult:
if settings.content_file_path:
path = Path(settings.content_file_path).expanduser()
if not path.is_absolute():
path = settings.base_dir / path
return CatalogLoadResult(
catalog=Catalog.from_json(
path,
allowed_statuses=("approved",),
allowed_levels=PILOT_CEFR_LEVELS,
),
source_label=(
"completo incluso (831 esercizi, 52 scale)"
if path.name == "catalog.full.json"
else f"file {path.name}"
),
is_demo=False,
)
if settings.content_repo_id:
try:
from huggingface_hub import hf_hub_download
path = hf_hub_download(
repo_id=settings.content_repo_id,
repo_type="dataset",
filename="catalog.json",
revision=settings.content_revision,
token=settings.hf_data_token or None,
)
return CatalogLoadResult(
catalog=Catalog.from_json(
Path(path),
allowed_statuses=("approved",),
allowed_levels=PILOT_CEFR_LEVELS,
),
source_label=(
f"{settings.content_repo_id}@{settings.content_revision}"
),
is_demo=False,
)
except Exception as exc:
raise CatalogError(
"Il catalogo remoto configurato non è disponibile o non è valido: "
f"{exc}"
) from exc
sample_path = settings.base_dir / "data" / "catalog.sample.json"
return CatalogLoadResult(
catalog=Catalog.from_json(
sample_path,
allowed_statuses=("demo",),
allowed_levels=DEMO_CEFR_LEVELS,
),
source_label="catalogo dimostrativo 2.0 incluso",
is_demo=True,
)