viaggiatreno 0.1.2__tar.gz

viaggiatreno-0.1.2/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# hatch-vcs generated version files
+packages/*/src/*/_version.py
+
+# Virtual environments
+.venv

viaggiatreno-0.1.2/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: viaggiatreno
+Version: 0.1.2
+Summary: ViaggiaTreno API Client - Core Library
+Project-URL: Homepage, https://github.com/matteoredaelli/pyviaggiatreno
+Project-URL: Documentation, https://github.com/matteoredaelli/pyviaggiatreno/blob/main/README.md
+Project-URL: Repository, https://github.com/matteoredaelli/pyviaggiatreno.git
+Project-URL: Issues, https://github.com/matteoredaelli/pyviaggiatreno/issues
+Author-email: Matteo Redaelli <matteo.redaelli@gmail.com>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.5
+Description-Content-Type: text/markdown
+
+# viaggiatreno
+
+Client Python per le API non ufficiali di [ViaggiaTreno](http://www.viaggiatreno.it),
+il sistema informativo in tempo reale della rete ferroviaria italiana.
+
+La libreria fornisce:
+
+- **`ViaggiaTrenoClient`** — client HTTP asincrono (basato su `httpx`) per tutti
+  gli endpoint REST di ViaggiaTreno (stazioni, partenze/arrivi, andamento treni,
+  tratte, infomobilità, meteo, statistiche).
+- **Modelli dati tipizzati** (pydantic): `StationDetail`, `TrainBoardItem`,
+  `TrainStatus`, `DettaglioTratta`, `Statistics`, e altri.
+- **Parser** per le risposte non-JSON (RSS infomobilità, autocomplete testuali).
+
+## Installazione
+
+```bash
+pip install viaggiatreno
+```
+
+## Esempio
+
+```python
+import asyncio
+from viaggiatreno import ViaggiaTrenoClient
+
+
+async def main() -> None:
+    async with ViaggiaTrenoClient() as client:
+        stazioni = await client.autocompleta_stazione("Milano")
+        for s in stazioni:
+            print(s)
+
+
+asyncio.run(main())
+```
+
+## Licenza
+
+Vedi il file `LICENSE` nel repository.
+
+Repository: https://github.com/matteoredaelli/pyviaggiatreno

viaggiatreno-0.1.2/README.md

@@ -0,0 +1,42 @@
+# viaggiatreno
+
+Client Python per le API non ufficiali di [ViaggiaTreno](http://www.viaggiatreno.it),
+il sistema informativo in tempo reale della rete ferroviaria italiana.
+
+La libreria fornisce:
+
+- **`ViaggiaTrenoClient`** — client HTTP asincrono (basato su `httpx`) per tutti
+  gli endpoint REST di ViaggiaTreno (stazioni, partenze/arrivi, andamento treni,
+  tratte, infomobilità, meteo, statistiche).
+- **Modelli dati tipizzati** (pydantic): `StationDetail`, `TrainBoardItem`,
+  `TrainStatus`, `DettaglioTratta`, `Statistics`, e altri.
+- **Parser** per le risposte non-JSON (RSS infomobilità, autocomplete testuali).
+
+## Installazione
+
+```bash
+pip install viaggiatreno
+```
+
+## Esempio
+
+```python
+import asyncio
+from viaggiatreno import ViaggiaTrenoClient
+
+
+async def main() -> None:
+    async with ViaggiaTrenoClient() as client:
+        stazioni = await client.autocompleta_stazione("Milano")
+        for s in stazioni:
+            print(s)
+
+
+asyncio.run(main())
+```
+
+## Licenza
+
+Vedi il file `LICENSE` nel repository.
+
+Repository: https://github.com/matteoredaelli/pyviaggiatreno

viaggiatreno-0.1.2/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.32", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "viaggiatreno"
+dynamic = ["version"]
+description = "ViaggiaTreno API Client - Core Library"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Matteo Redaelli", email = "matteo.redaelli@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/matteoredaelli/pyviaggiatreno"
+Documentation = "https://github.com/matteoredaelli/pyviaggiatreno/blob/main/README.md"
+Repository = "https://github.com/matteoredaelli/pyviaggiatreno.git"
+Issues = "https://github.com/matteoredaelli/pyviaggiatreno/issues"
+
+# Derive the version from Git tags (e.g. tag "v0.5.0" -> version "0.5.0").
+# The repository root is two levels up from this package.
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../.." }
+
+# Write the resolved version to a generated module so it is importable at
+# runtime (viaggiatreno.__version__) without re-inspecting Git.
+[tool.hatch.build.hooks.vcs]
+version-file = "src/viaggiatreno/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/viaggiatreno"]

viaggiatreno-0.1.2/src/viaggiatreno/__init__.py

@@ -0,0 +1,85 @@
+"""ViaggiaTreno API Client - Core library.
+
+Libreria per interrogare le API non ufficiali di ViaggiaTreno: client HTTP
+asincrono, parser delle risposte e modelli dati tipizzati (pydantic).
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from viaggiatreno.api.client import ViaggiaTrenoClient, format_viaggiatreno_datetime
+from viaggiatreno.api.parsers import (
+    parse_infomobilita_rss,
+    parse_infomobilita_rss_box,
+    parse_infomobilita_ticker,
+    parse_station_autocomplete,
+    parse_station_nts_autocomplete,
+    parse_train_autocomplete,
+)
+from viaggiatreno.models.common import (
+    CLIENT_COMPANIES,
+    REGIONS,
+    TRAIN_STATUS_DESCRIPTIONS,
+    ViaggiaTrenoBaseModel,
+)
+from viaggiatreno.models.route import DettaglioTratta, TrattaSegment
+from viaggiatreno.models.service import (
+    InfomobilitaNews,
+    InfomobilitaNewsHeadline,
+    StationWeather,
+    Statistics,
+)
+from viaggiatreno.models.station import (
+    StationAutocompleteItem,
+    StationDetail,
+    StationNTSAutocompleteItem,
+    StationSearchResult,
+)
+from viaggiatreno.models.train import (
+    Fermata,
+    TrainAutocompleteItem,
+    TrainBoardItem,
+    TrainSearchResult,
+    TrainStatus,
+    TrattaCanvasItem,
+)
+
+try:
+    # Generated at build time by hatch-vcs from the Git tag.
+    from viaggiatreno._version import __version__  # type: ignore[import-not-found,unused-ignore]
+except ImportError:  # pragma: no cover - only when running from an unbuilt tree
+    try:
+        __version__ = version("viaggiatreno")
+    except PackageNotFoundError:
+        __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "CLIENT_COMPANIES",
+    "REGIONS",
+    "TRAIN_STATUS_DESCRIPTIONS",
+    "DettaglioTratta",
+    "Fermata",
+    "InfomobilitaNews",
+    "InfomobilitaNewsHeadline",
+    "StationAutocompleteItem",
+    "StationDetail",
+    "StationNTSAutocompleteItem",
+    "StationSearchResult",
+    "StationWeather",
+    "Statistics",
+    "TrainAutocompleteItem",
+    "TrainBoardItem",
+    "TrainSearchResult",
+    "TrainStatus",
+    "TrattaCanvasItem",
+    "TrattaSegment",
+    "ViaggiaTrenoBaseModel",
+    "ViaggiaTrenoClient",
+    "__version__",
+    "format_viaggiatreno_datetime",
+    "parse_infomobilita_rss",
+    "parse_infomobilita_rss_box",
+    "parse_infomobilita_ticker",
+    "parse_station_autocomplete",
+    "parse_station_nts_autocomplete",
+    "parse_train_autocomplete",
+]

viaggiatreno-0.1.2/src/viaggiatreno/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.2'
+__version_tuple__ = version_tuple = (0, 1, 2)
+
+__commit_id__ = commit_id = None

viaggiatreno-0.1.2/src/viaggiatreno/api/__init__.py

@@ -0,0 +1,22 @@
+"""Package API per la libreria ViaggiaTreno."""
+
+from viaggiatreno.api.client import ViaggiaTrenoClient, format_viaggiatreno_datetime
+from viaggiatreno.api.parsers import (
+    parse_infomobilita_rss,
+    parse_infomobilita_rss_box,
+    parse_infomobilita_ticker,
+    parse_station_autocomplete,
+    parse_station_nts_autocomplete,
+    parse_train_autocomplete,
+)
+
+__all__ = [
+    "ViaggiaTrenoClient",
+    "format_viaggiatreno_datetime",
+    "parse_infomobilita_rss",
+    "parse_infomobilita_rss_box",
+    "parse_infomobilita_ticker",
+    "parse_station_autocomplete",
+    "parse_station_nts_autocomplete",
+    "parse_train_autocomplete",
+]

viaggiatreno-0.1.2/src/viaggiatreno/api/client.py

@@ -0,0 +1,355 @@
+"""Client asincrono per le API di ViaggiaTreno."""
+
+import time
+from datetime import UTC, datetime
+from types import TracebackType
+from typing import Self
+from urllib.parse import quote
+
+import httpx
+
+from viaggiatreno.api.parsers import (
+    parse_infomobilita_rss,
+    parse_infomobilita_rss_box,
+    parse_infomobilita_ticker,
+    parse_station_autocomplete,
+    parse_station_nts_autocomplete,
+    parse_train_autocomplete,
+)
+from viaggiatreno.models.route import DettaglioTratta, TrattaSegment
+from viaggiatreno.models.service import (
+    InfomobilitaNews,
+    InfomobilitaNewsHeadline,
+    StationWeather,
+    Statistics,
+)
+from viaggiatreno.models.station import (
+    StationAutocompleteItem,
+    StationDetail,
+    StationNTSAutocompleteItem,
+    StationSearchResult,
+)
+from viaggiatreno.models.train import (
+    TrainAutocompleteItem,
+    TrainBoardItem,
+    TrainSearchResult,
+    TrainStatus,
+    TrattaCanvasItem,
+)
+
+DEFAULT_BASE_URL = "http://www.viaggiatreno.it/infomobilita/resteasy/viaggiatreno"
+DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+
+
+def format_viaggiatreno_datetime(dt: datetime | str | None = None) -> str:
+    """Formatta la data/ora nel formato atteso dagli endpoint partenze/arrivi.
+
+    Esempio formato ViaggiaTreno: Sun Oct 04 2026 08:12:27 GMT+0200 (URL-encoded).
+    """
+    if dt is None:
+        now = datetime.now(UTC).astimezone()
+        formatted = now.strftime("%a %b %d %Y %H:%M:%S GMT%z")
+    elif isinstance(dt, datetime):
+        formatted = dt.strftime("%a %b %d %Y %H:%M:%S GMT%z")
+    else:
+        # Se è già stringa
+        formatted = dt
+
+    return quote(formatted)
+
+
+class ViaggiaTrenoClient:
+    """Client asincrono per tutte le chiamate REST di ViaggiaTreno."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 20.0,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._external_client = client
+        self._client: httpx.AsyncClient | None = client
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                timeout=self.timeout,
+                headers={"User-Agent": DEFAULT_USER_AGENT},
+                follow_redirects=True,
+            )
+        return self._client
+
+    async def close(self) -> None:
+        if self._client and not self._external_client and not self._client.is_closed:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> Self:
+        await self._get_client()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def _request(self, path: str) -> httpx.Response:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        client = await self._get_client()
+        response = await client.get(url)
+        return response
+
+    # -------------------------------------------------------------------------
+    # STAZIONI
+    # -------------------------------------------------------------------------
+
+    async def autocompleta_stazione(self, prefisso: str) -> list[StationAutocompleteItem]:
+        """Suggerimenti stazioni per prefisso (GET /autocompletaStazione/{prefisso})."""
+        r = await self._request(f"autocompletaStazione/{quote(prefisso)}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        return parse_station_autocomplete(r.text)
+
+    async def autocompleta_stazione_imposta_viaggio(
+        self, prefisso: str
+    ) -> list[StationAutocompleteItem]:
+        """Suggerimenti stazioni per imposta viaggio (GET /autocompletaStazioneImpostaViaggio/{prefisso})."""
+        r = await self._request(f"autocompletaStazioneImpostaViaggio/{quote(prefisso)}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        return parse_station_autocomplete(r.text)
+
+    async def autocompleta_stazione_nts(self, prefisso: str) -> list[StationNTSAutocompleteItem]:
+        """Suggerimenti stazioni e posti tecnici con codice NTS RICS (GET /autocompletaStazioneNTS/{prefisso})."""
+        r = await self._request(f"autocompletaStazioneNTS/{quote(prefisso)}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        return parse_station_nts_autocomplete(r.text)
+
+    async def cerca_stazione(self, prefisso: str) -> list[StationSearchResult]:
+        """Ricerca stazioni con risposta JSON strutturata (GET /cercaStazione/{prefisso})."""
+        r = await self._request(f"cercaStazione/{quote(prefisso)}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        data = r.json()
+        return [StationSearchResult.model_validate(item) for item in data]
+
+    async def regione(self, codice_stazione: str) -> int | None:
+        """Codice regione numerico di una stazione (GET /regione/{codiceStazione})."""
+        r = await self._request(f"regione/{quote(codice_stazione)}")
+        if r.status_code == 204 or not r.text.strip():
+            return None
+        r.raise_for_status()
+        try:
+            return int(r.text.strip())
+        except ValueError:
+            return None
+
+    async def dettaglio_stazione(
+        self, codice_stazione: str, codice_regione: int
+    ) -> StationDetail | None:
+        """Dettagli e coordinate di una stazione (GET /dettaglioStazione/{codiceStazione}/{codiceRegione})."""
+        r = await self._request(f"dettaglioStazione/{quote(codice_stazione)}/{codice_regione}")
+        if r.status_code == 204 or not r.text.strip():
+            return None
+        r.raise_for_status()
+        data = r.json()
+        return StationDetail.model_validate(data)
+
+    async def elenco_stazioni(self, codice_regione: int) -> list[StationDetail]:
+        """Elenco completo stazioni di una regione (GET /elencoStazioni/{codiceRegione})."""
+        r = await self._request(f"elencoStazioni/{codice_regione}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        data = r.json()
+        return [StationDetail.model_validate(item) for item in data]
+
+    # -------------------------------------------------------------------------
+    # PARTENZE E ARRIVI
+    # -------------------------------------------------------------------------
+
+    async def partenze(
+        self,
+        codice_stazione: str,
+        data_ora: datetime | str | None = None,
+    ) -> list[TrainBoardItem]:
+        """Tabellone partenze da una stazione (GET /partenze/{codiceStazione}/{dataOra})."""
+        encoded_date = format_viaggiatreno_datetime(data_ora)
+        r = await self._request(f"partenze/{quote(codice_stazione)}/{encoded_date}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        data = r.json()
+        return [TrainBoardItem.model_validate(item) for item in data]
+
+    async def arrivi(
+        self,
+        codice_stazione: str,
+        data_ora: datetime | str | None = None,
+    ) -> list[TrainBoardItem]:
+        """Tabellone arrivi in una stazione (GET /arrivi/{codiceStazione}/{dataOra})."""
+        encoded_date = format_viaggiatreno_datetime(data_ora)
+        r = await self._request(f"arrivi/{quote(codice_stazione)}/{encoded_date}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        data = r.json()
+        return [TrainBoardItem.model_validate(item) for item in data]
+
+    # -------------------------------------------------------------------------
+    # TRENI
+    # -------------------------------------------------------------------------
+
+    async def cerca_numero_treno_autocomplete(
+        self, numero_treno: int | str
+    ) -> list[TrainAutocompleteItem]:
+        """Corse attive per un numero treno (GET /cercaNumeroTrenoTrenoAutocomplete/{numeroTreno})."""
+        r = await self._request(f"cercaNumeroTrenoTrenoAutocomplete/{numero_treno}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        return parse_train_autocomplete(r.text)
+
+    async def cerca_numero_treno(self, numero_treno: int | str) -> TrainSearchResult | None:
+        """Identificativi corsa corrente per un treno in JSON (GET /cercaNumeroTreno/{numeroTreno})."""
+        r = await self._request(f"cercaNumeroTreno/{numero_treno}")
+        if r.status_code == 204 or not r.text.strip():
+            return None
+        r.raise_for_status()
+        data = r.json()
+        return TrainSearchResult.model_validate(data)
+
+    async def andamento_treno(
+        self,
+        codice_stazione_origine: str,
+        numero_treno: int | str,
+        data_partenza: int | str,
+    ) -> TrainStatus | None:
+        """Stato dettagliato treno e fermate (GET /andamentoTreno/{codiceStazioneOrigine}/{numeroTreno}/{dataPartenza})."""
+        r = await self._request(
+            f"andamentoTreno/{quote(codice_stazione_origine)}/{numero_treno}/{data_partenza}"
+        )
+        if r.status_code == 204 or not r.text.strip():
+            return None
+        r.raise_for_status()
+        data = r.json()
+        return TrainStatus.model_validate(data)
+
+    async def tratte_canvas(
+        self,
+        codice_stazione_origine: str,
+        numero_treno: int | str,
+        data_partenza: int | str,
+    ) -> list[TrattaCanvasItem]:
+        """Itinerario visuale ad albero (GET /tratteCanvas/{codiceStazioneOrigine}/{numeroTreno}/{dataPartenza})."""
+        r = await self._request(
+            f"tratteCanvas/{quote(codice_stazione_origine)}/{numero_treno}/{data_partenza}"
+        )
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        data = r.json()
+        return [TrattaCanvasItem.model_validate(item) for item in data]
+
+    # -------------------------------------------------------------------------
+    # TRATTE E RETE
+    # -------------------------------------------------------------------------
+
+    async def elenco_tratte(
+        self,
+        categorie: str = "ES*,IC,EXP,EC,EN,REG",
+        timestamp: int | None = None,
+    ) -> list[TrattaSegment]:
+        """Segmenti della rete e occupazione da treni (GET /elencoTratte/0/6/{categorie}/null/{timestamp})."""
+        ts = timestamp if timestamp is not None else int(time.time() * 1000)
+        r = await self._request(f"elencoTratte/0/6/{quote(categorie)}/null/{ts}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        data = r.json()
+        return [TrattaSegment.model_validate(item) for item in data]
+
+    async def dettagli_tratta(
+        self,
+        tratta_ab: int,
+        tratta_ba: int,
+        categorie: str = "ES*,IC,EXP,EC,EN,REG",
+    ) -> list[DettaglioTratta]:
+        """Treni presenti su un segmento (GET /dettagliTratta/0/{trattaAB}/{trattaBA}/{categorie}/null)."""
+        r = await self._request(f"dettagliTratta/0/{tratta_ab}/{tratta_ba}/{quote(categorie)}/null")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        data = r.json()
+        return [DettaglioTratta.model_validate(item) for item in data]
+
+    # -------------------------------------------------------------------------
+    # INFORMAZIONI DI SERVIZIO
+    # -------------------------------------------------------------------------
+
+    async def statistiche(self, timestamp: int | None = None) -> Statistics | None:
+        """Statistiche treni circolanti e programmati (GET /statistiche/{timestamp})."""
+        ts = timestamp if timestamp is not None else int(time.time() * 1000)
+        r = await self._request(f"statistiche/{ts}")
+        if r.status_code == 204 or not r.text.strip():
+            return None
+        r.raise_for_status()
+        data = r.json()
+        return Statistics.model_validate(data)
+
+    async def datimeteo(self, codice_regione: int) -> dict[str, StationWeather]:
+        """Previsioni meteo per stazioni di una regione (GET /datimeteo/{codiceRegione})."""
+        r = await self._request(f"datimeteo/{codice_regione}")
+        if r.status_code == 204 or not r.text.strip():
+            return {}
+        r.raise_for_status()
+        data = r.json()
+        results: dict[str, StationWeather] = {}
+        for station_id, weather_dict in data.items():
+            results[station_id] = StationWeather.model_validate(weather_dict)
+        return results
+
+    async def infomobilita_rss(self, is_info_lavori: bool = False) -> list[InfomobilitaNews]:
+        """Notizie circolazione o lavori programmati (GET /infomobilitaRSS/{isInfoLavori})."""
+        param = "true" if is_info_lavori else "false"
+        r = await self._request(f"infomobilitaRSS/{param}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        return parse_infomobilita_rss(r.text)
+
+    async def infomobilita_rss_box(
+        self, is_info_lavori: bool = False
+    ) -> list[InfomobilitaNewsHeadline]:
+        """Titoli sintetici delle notizie di infomobilità (GET /infomobilitaRSSBox/{isInfoLavori})."""
+        param = "true" if is_info_lavori else "false"
+        r = await self._request(f"infomobilitaRSSBox/{param}")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        return parse_infomobilita_rss_box(r.text)
+
+    async def infomobilita_ticker(self) -> list[str]:
+        """Avvisi brevi del ticker scorrevole (GET /infomobilitaTicker)."""
+        r = await self._request("infomobilitaTicker")
+        if r.status_code == 204 or not r.text.strip():
+            return []
+        r.raise_for_status()
+        return parse_infomobilita_ticker(r.text)
+
+    async def language(self, id_lingua: str = "it") -> dict[str, str]:
+        """Dizionario di traduzione dell'interfaccia (GET /language/{idLingua})."""
+        r = await self._request(f"language/{quote(id_lingua)}")
+        if r.status_code == 204 or not r.text.strip():
+            return {}
+        r.raise_for_status()
+        return r.json()