opensituas 0.1.0__tar.gz

opensituas-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.3
+Name: opensituas
+Version: 0.1.0
+Summary: CLI per il SITUAS (Sistema Informativo Territoriale delle Unità Amministrative e Statistiche, ISTAT), pensata per l'orchestrazione da parte di agenti AI
+Keywords: situas,istat,comuni,province,regioni,open-data,cli,api
+Author: Andrea Borruso
+Author-email: Andrea Borruso <aborruso@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Italian
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: httpx>=0.28
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.9
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+opensituas
+
+CLI per il **SITUAS** — Sistema Informativo Territoriale delle Unità Amministrative e
+Statistiche (ISTAT) — progettata per essere orchestrata da un agente AI: output
+strutturato (`table`/`json`/`csv`), errori auto-esplicativi, catalogo cachato.
+
+opensituas è un'idea di [Alice Corona](https://alice-corona.eu/).
+
+## Installazione
+
+```bash
+uv tool install opensituas        # CLI a livello di sistema
+# oppure, in sviluppo:
+uv pip install -e .
+```
+
+## Cosa espone SITUAS
+
+Due tipi di interrogazione, entrambi coperti:
+
+1. **Catalogo report** — 74 "microservizi" (report) su unità amministrative e statistiche
+   (ripartizioni, regioni, province/uts, comuni, sistemi locali del lavoro, ...). Ogni report
+   ha un periodo di validità e restituisce una tabella alla data scelta.
+2. **Query territoriali interattive** — storia delle variazioni di un'unità nel tempo
+   (`storia`) e ricerca dei codici/denominazioni Istat con periodi di validità (`cerca-codice`).
+
+## Comandi
+
+```bash
+# --- catalogo ---
+opensituas catalog                          # tutti i report (pfun, titolo, validità, ...)
+opensituas catalog "Comuni" --ambito "Unità amministrative"
+opensituas --output json catalog "Ripartizioni" | jq '.[].pfun'
+opensituas catalog --refresh                # rilegge dal gateway
+
+opensituas info 50                          # descrizione + colonne del report 50
+opensituas get 61                           # report DATA: dato più recente (fine validità)
+opensituas get 61 --output csv --out comuni.csv
+opensituas count 98 --from 17/03/1861 --to 31/05/2026
+opensituas get 61 --date 01/01/2020         # snapshot storico; errore chiaro se fuori validità
+
+# --- query territoriali ---
+opensituas storia comune Roma               # storia delle variazioni del comune
+opensituas storia comune 058091 --dettaglio # + provvedimento e unità coinvolte
+opensituas storia regione Lazio
+opensituas storia provincia Roma
+opensituas cerca-codice comune Roma         # codici/denominazioni + validità
+```
+
+## Output per agenti
+
+Il flag globale `--output` (`-o`) vale `table` (default), `json` o `csv`. In `json`/`csv`
+l'output su stdout è pulito (i messaggi diagnostici vanno su stderr), pronto per `jq`:
+
+```bash
+opensituas -o json storia comune Roma | jq '.storia[] | {data: ."data evento", evento: .variazione}'
+opensituas -o csv get 50 > comuni.csv
+```
+
+## Come funziona (in breve)
+
+- **Catalogo**: ottenuto via gateway POST (`get_elenco_microservizi`), cachato in
+  `~/.cache/opensituas/catalog.json` (TTL 7 giorni), con snapshot incluso come fallback.
+- **Dati report**: endpoint pubblici `situas-servizi.istat.it/publish` (`reportspooljson`,
+  `reportspooljsoncount`, `anagrafica_report_metadato_web`). Per i report `DATA`, senza
+  `--date` la CLI usa la **fine validità** (dato più recente); i link del catalogo
+  porterebbero invece la data di *inizio* (snapshot più vecchio). `--date`/`--from`/`--to`
+  sostituiscono il parametro data.
+- **Query territoriali**: servizi `var_get_ua_*` (storia) e `ricercacodice_*` via gateway.
+
+Dettagli in [docs/architecture.md](docs/architecture.md). Per orchestrazione da agente vedi
+[skills/situas-explorer/SKILL.md](skills/situas-explorer/SKILL.md).
+
+## Variabili d'ambiente
+
+| Variabile | Default | Descrizione |
+|---|---|---|
+| `OPENSITUAS_TIMEOUT` | `60` | Timeout richieste (secondi) |
+
+## Licenza
+
+MIT

opensituas-0.1.0/README.md

@@ -0,0 +1,82 @@
+opensituas
+
+CLI per il **SITUAS** — Sistema Informativo Territoriale delle Unità Amministrative e
+Statistiche (ISTAT) — progettata per essere orchestrata da un agente AI: output
+strutturato (`table`/`json`/`csv`), errori auto-esplicativi, catalogo cachato.
+
+opensituas è un'idea di [Alice Corona](https://alice-corona.eu/).
+
+## Installazione
+
+```bash
+uv tool install opensituas        # CLI a livello di sistema
+# oppure, in sviluppo:
+uv pip install -e .
+```
+
+## Cosa espone SITUAS
+
+Due tipi di interrogazione, entrambi coperti:
+
+1. **Catalogo report** — 74 "microservizi" (report) su unità amministrative e statistiche
+   (ripartizioni, regioni, province/uts, comuni, sistemi locali del lavoro, ...). Ogni report
+   ha un periodo di validità e restituisce una tabella alla data scelta.
+2. **Query territoriali interattive** — storia delle variazioni di un'unità nel tempo
+   (`storia`) e ricerca dei codici/denominazioni Istat con periodi di validità (`cerca-codice`).
+
+## Comandi
+
+```bash
+# --- catalogo ---
+opensituas catalog                          # tutti i report (pfun, titolo, validità, ...)
+opensituas catalog "Comuni" --ambito "Unità amministrative"
+opensituas --output json catalog "Ripartizioni" | jq '.[].pfun'
+opensituas catalog --refresh                # rilegge dal gateway
+
+opensituas info 50                          # descrizione + colonne del report 50
+opensituas get 61                           # report DATA: dato più recente (fine validità)
+opensituas get 61 --output csv --out comuni.csv
+opensituas count 98 --from 17/03/1861 --to 31/05/2026
+opensituas get 61 --date 01/01/2020         # snapshot storico; errore chiaro se fuori validità
+
+# --- query territoriali ---
+opensituas storia comune Roma               # storia delle variazioni del comune
+opensituas storia comune 058091 --dettaglio # + provvedimento e unità coinvolte
+opensituas storia regione Lazio
+opensituas storia provincia Roma
+opensituas cerca-codice comune Roma         # codici/denominazioni + validità
+```
+
+## Output per agenti
+
+Il flag globale `--output` (`-o`) vale `table` (default), `json` o `csv`. In `json`/`csv`
+l'output su stdout è pulito (i messaggi diagnostici vanno su stderr), pronto per `jq`:
+
+```bash
+opensituas -o json storia comune Roma | jq '.storia[] | {data: ."data evento", evento: .variazione}'
+opensituas -o csv get 50 > comuni.csv
+```
+
+## Come funziona (in breve)
+
+- **Catalogo**: ottenuto via gateway POST (`get_elenco_microservizi`), cachato in
+  `~/.cache/opensituas/catalog.json` (TTL 7 giorni), con snapshot incluso come fallback.
+- **Dati report**: endpoint pubblici `situas-servizi.istat.it/publish` (`reportspooljson`,
+  `reportspooljsoncount`, `anagrafica_report_metadato_web`). Per i report `DATA`, senza
+  `--date` la CLI usa la **fine validità** (dato più recente); i link del catalogo
+  porterebbero invece la data di *inizio* (snapshot più vecchio). `--date`/`--from`/`--to`
+  sostituiscono il parametro data.
+- **Query territoriali**: servizi `var_get_ua_*` (storia) e `ricercacodice_*` via gateway.
+
+Dettagli in [docs/architecture.md](docs/architecture.md). Per orchestrazione da agente vedi
+[skills/situas-explorer/SKILL.md](skills/situas-explorer/SKILL.md).
+
+## Variabili d'ambiente
+
+| Variabile | Default | Descrizione |
+|---|---|---|
+| `OPENSITUAS_TIMEOUT` | `60` | Timeout richieste (secondi) |
+
+## Licenza
+
+MIT

opensituas-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "opensituas"
+version = "0.1.0"
+description = "CLI per il SITUAS (Sistema Informativo Territoriale delle Unità Amministrative e Statistiche, ISTAT), pensata per l'orchestrazione da parte di agenti AI"
+readme = "README.md"
+authors = [
+    { name = "Andrea Borruso", email = "aborruso@gmail.com" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.12"
+keywords = ["situas", "istat", "comuni", "province", "regioni", "open-data", "cli", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: Italian",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.28",
+    "typer>=0.15",
+    "rich>=13.9",
+]
+
+[project.scripts]
+opensituas = "opensituas:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.11"]
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "opensituas"
+module-root = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff.lint]
+ignore = ["E402"]

opensituas-0.1.0/src/opensituas/__init__.py

@@ -0,0 +1,8 @@
+"""opensituas — CLI per il SITUAS (ISTAT), orchestrabile da agenti AI."""
+
+from __future__ import annotations
+
+from .cli import app, main
+
+__all__ = ["app", "main"]
+__version__ = "0.1.0"

opensituas-0.1.0/src/opensituas/base.py

@@ -0,0 +1,106 @@
+"""Strato HTTP per le API SITUAS.
+
+Due basi distinte:
+
+- **Gateway** (`GATEWAY_URL`): proxy POST verso i servizi Oracle ORDS. Riceve
+  `{"url": "<nome_servizio>?<query>"}`. Serve per il catalogo (`get_elenco_microservizi`)
+  e per tutte le query interattive (`ricercacodice_*`, `var_get_ua_*`).
+- **Publish** (`PUBLISH_BASE`): endpoint pubblici GET per i dati dei report
+  (`reportspooljson`, `reportspooljsoncount`, `anagrafica_report_metadato_web`).
+
+Particolarità scoperte sul campo:
+
+- I servizi `ricercacodice_*` rispondono vuoto senza un header `Referer` browser-like:
+  lo inviamo su **tutte** le chiamate al gateway.
+- L'envelope JSON varia: `resultset` (reportspooljson, ricercacodice) oppure `items`
+  (var_get_ua_*, catalogo). `rows()` normalizza entrambi.
+- Gli errori applicativi arrivano con HTTP 200, come `{"resultset":[{"ERRCODE":"..."}]}`
+  oppure `{"message": "..."}`: vanno letti dal payload, non dallo status code.
+"""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+
+GATEWAY_URL = "https://situas.istat.it/ShibO2Module/api/Report/ReportByUrl"
+PUBLISH_BASE = "https://situas-servizi.istat.it/publish"
+
+DEFAULT_TIMEOUT = 60.0
+
+_HEADERS = {
+    "Accept": "application/json, text/plain, */*",
+    "Content-Type": "application/json",
+    "Referer": "https://situas.istat.it/web/",
+    "language": "IT",
+}
+
+
+class SituasError(Exception):
+    """Errore applicativo restituito dalle API SITUAS."""
+
+
+def _client(timeout: float) -> httpx.Client:
+    return httpx.Client(timeout=timeout, headers=_HEADERS, follow_redirects=True)
+
+
+def gateway(service: str, timeout: float = DEFAULT_TIMEOUT) -> dict:
+    """Invoca un servizio ORDS tramite il gateway report.
+
+    `service` è il nome del servizio con la sua querystring, es.
+    ``"ricercacodice_criterio_lov?haRuolo&ptipounit=1"``.
+    """
+    try:
+        with _client(timeout) as client:
+            resp = client.post(GATEWAY_URL, content=json.dumps({"url": service}))
+            resp.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise SituasError(f"Gateway SITUAS irraggiungibile: {exc}") from exc
+    return _parse(resp, service)
+
+
+def publish_get(url: str, timeout: float = DEFAULT_TIMEOUT) -> dict:
+    """GET di un URL publish già formato (es. uno SPOOL_LINK del catalogo)."""
+    try:
+        with _client(timeout) as client:
+            resp = client.get(url)
+            resp.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise SituasError(f"Endpoint SITUAS irraggiungibile: {exc}") from exc
+    return _parse(resp, url)
+
+
+def rows(data: object) -> list[dict]:
+    """Estrae la lista di record da un payload SITUAS (envelope `resultset` o `items`)."""
+    if isinstance(data, dict):
+        for key in ("resultset", "items"):
+            value = data.get(key)
+            if isinstance(value, list):
+                return value
+    if isinstance(data, list):
+        return data
+    return []
+
+
+def _parse(resp: httpx.Response, ctx: str) -> dict:
+    # strict=False: alcuni metadati SITUAS contengono \r\n grezzi dentro le stringhe
+    # (caratteri di controllo non escapati), tecnicamente JSON non valido ma tollerabile.
+    try:
+        data = json.loads(resp.text, strict=False)
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise SituasError(f"Risposta non-JSON da SITUAS ({ctx[:80]})") from exc
+    _check_error(data, ctx)
+    return data
+
+
+def _check_error(data: object, ctx: str) -> None:
+    if isinstance(data, dict):
+        status = data.get("status")
+        if isinstance(status, int) and status >= 400:
+            raise SituasError(f"{data.get('title', 'Errore')} (status {status})")
+        if "message" in data and "resultset" not in data and "items" not in data:
+            raise SituasError(str(data["message"]))
+    recs = rows(data)
+    if len(recs) == 1 and isinstance(recs[0], dict) and "ERRCODE" in recs[0]:
+        raise SituasError(f"{recs[0]['ERRCODE']} ({ctx[:80]})")

opensituas-0.1.0/src/opensituas/catalog.py

@@ -0,0 +1,139 @@
+"""Catalogo dei report SITUAS (i 74 "microservizi").
+
+Il catalogo si ottiene SOLO via gateway (`get_elenco_microservizi`); il base publish
+restituisce 401. Viene cachato in ``~/.cache/opensituas/catalog.json`` (TTL 7 giorni),
+con fallback allo snapshot incluso nel package per il primo avvio offline.
+
+Ogni voce espone link pre-compilati con date valide (`SPOOL_LINK`, `COUNT_LINK`,
+`INFO_LINK`): sono la **fonte di verità** per la data. Per cambiare data si sostituisce
+solo il parametro nel link (vedi `apply_date`), senza ri-derivarla dalla validità.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from importlib.resources import files
+from pathlib import Path
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from . import base
+
+_CACHE_DIR = Path.home() / ".cache" / "opensituas"
+_CACHE_FILE = _CACHE_DIR / "catalog.json"
+_TTL = 7 * 24 * 3600  # 7 giorni
+_SERVICE = "get_elenco_microservizi"
+
+
+def _bundled() -> list[dict]:
+    raw = files("opensituas").joinpath("catalog_snapshot.json").read_text("utf-8")
+    return json.loads(raw).get("items", [])
+
+
+def load_catalog(refresh: bool = False) -> list[dict]:
+    """Restituisce il catalogo (lista di voci report).
+
+    Ordine: cache fresca → gateway → cache stantia → snapshot incluso.
+    """
+    if not refresh and _CACHE_FILE.exists():
+        if time.time() - _CACHE_FILE.stat().st_mtime < _TTL:
+            return json.loads(_CACHE_FILE.read_text("utf-8"))
+    try:
+        items = base.gateway(_SERVICE).get("items", [])
+        if items:
+            _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+            _CACHE_FILE.write_text(json.dumps(items, ensure_ascii=False), "utf-8")
+            return items
+    except base.SituasError:
+        pass
+    if _CACHE_FILE.exists():
+        return json.loads(_CACHE_FILE.read_text("utf-8"))
+    return _bundled()
+
+
+def get_entry(pfun: int | str, catalog: list[dict] | None = None) -> dict:
+    """Voce del catalogo per id report (`pfun`)."""
+    catalog = catalog if catalog is not None else load_catalog()
+    pid = str(pfun)
+    for entry in catalog:
+        if str(entry.get("Id report")) == pid:
+            return entry
+    raise base.SituasError(f"Report pfun={pfun} non presente nel catalogo")
+
+
+def filter_catalog(
+    catalog: list[dict],
+    keyword: str | None = None,
+    ambito: str | None = None,
+    unita: str | None = None,
+) -> list[dict]:
+    """Filtra le voci per parola chiave (sul titolo), ambito e unità territoriale."""
+
+    def match(entry: dict) -> bool:
+        if keyword and keyword.lower() not in entry.get("Titolo report", "").lower():
+            return False
+        if ambito and ambito.lower() not in entry.get("Ambito territoriale", "").lower():
+            return False
+        if unita and unita.lower() not in entry.get("Unità territoriale", "").lower():
+            return False
+        return True
+
+    return [e for e in catalog if match(e)]
+
+
+def is_range(entry: dict) -> bool:
+    """True se il report è a intervallo (PERIODO, parametri pdatada/pdataa)."""
+    return "pdatada" in entry.get("parametri necessari", "")
+
+
+def validity_end(entry: dict) -> str | None:
+    """Data di fine validità (DD/MM/YYYY) dal campo catalogo, o None se assente."""
+    val = entry.get("Inizio/fine validità report", "")
+    if " - " in val:
+        return val.split(" - ", 1)[1].strip() or None
+    return None
+
+
+def apply_date(
+    link: str,
+    date: str | None = None,
+    date_from: str | None = None,
+    date_to: str | None = None,
+    default_date: str | None = None,
+) -> str:
+    """Sostituisce nel link SOLO i parametri data (`pdata` o `pdatada`/`pdataa`).
+
+    Il resto del link (pre-validato dal catalogo) resta intatto. Per i report a data
+    singola (DATA), se non si passa ``date`` viene usata ``default_date`` (di norma la
+    fine validità, cioè il dato più recente): i link del catalogo portano invece la data
+    di *inizio* validità, che darebbe lo snapshot più vecchio. Solleva errore se si
+    mescola `--date` con `--from/--to` o si usa il pattern sbagliato per il tipo report.
+    """
+    if date and (date_from or date_to):
+        raise base.SituasError("Usa --date oppure --from/--to, non entrambi")
+
+    parts = urlsplit(link)
+    query = dict(parse_qsl(parts.query, keep_blank_values=True))
+    link_is_range = "pdatada" in query or "pdataa" in query
+
+    if link_is_range:
+        if date:
+            raise base.SituasError(
+                "Report a intervallo (PERIODO): usa --from/--to, non --date"
+            )
+        if date_from:
+            query["pdatada"] = date_from
+        if date_to:
+            query["pdataa"] = date_to
+    else:
+        if date_from or date_to:
+            raise base.SituasError(
+                "Report a data singola (DATA): usa --date, non --from/--to"
+            )
+        if date:
+            query["pdata"] = date
+        elif default_date:
+            query["pdata"] = default_date
+
+    new_query = urlencode(query, safe="/")
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, new_query, parts.fragment))