Release v2.1.9: fix progress messages for OpenData fallback

- Remove misleading error when caricaAKN unavailable
- Add progress indicators: initial message, animated dots during polling, success message
- Show progress on stderr even when output goes to stdout
- Suppress only with explicit --quiet flag
- Update LOG.md

Fixes confusing UX where users thought command was stuck

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: aborruso

LOG.md

@@ -2,6 +2,20 @@
 
 Questo file documenta gli avanzamenti significativi e le decisioni chiave del progetto `normattiva_2_md`.
 
+## 2026-01-29
+
+### Fix messaggi di progresso fallback OpenData
+
+- Rimosso messaggio di errore fuorviante quando link caricaAKN non disponibile
+- Sostituito con messaggio informativo: "⚠️ Link caricaAKN non trovato, tentativo con fallback..."
+- Aggiunti indicatori di progresso per download via OpenData:
+  - Messaggio iniziale "🔄 Tentativo download via API OpenData..."
+  - Indicatore animato "⏳ Preparazione collezione OpenData..." con puntini durante polling
+  - Messaggio di successo "✅ File XML (OpenData) salvato in: ..."
+- Modificato quiet mode: messaggi di progresso visibili su stderr anche quando output va a stdout
+- Messaggi soppressi solo con flag --quiet esplicito
+- Fix UX: utente ora vede chiaramente che download è in corso, evita confusione su comando bloccato
+
 ## 2026-01-12
 
 ### URL con escape backslash

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "normattiva2md"
-version = "2.1.8"
+version = "2.1.9"
 description = "Convertitore da XML Akoma Ntoso a formato Markdown con download automatico delle leggi citate e cross-references inline (CLI: normattiva2md)"
 readme = "README.md"
 requires-python = ">=3.7"

setup.py

@@ -19,7 +19,7 @@ def read_readme():
 
 setup(
     name="normattiva2md",
-    version="2.1.8",
+    version="2.1.9",
     description="Convertitore da XML Akoma Ntoso a formato Markdown con download automatico delle leggi citate e cross-references inline (CLI: normattiva2md)",
     long_description=read_readme(),
     long_description_content_type="text/markdown",

src/normattiva2md/cli.py

@@ -667,8 +667,9 @@ def main():
             params = None
             session = None
             if not args.opendata:
+                # Show progress even when output goes to stdout (unless --quiet)
                 params, session = extract_params_from_normattiva_url(
-                    input_source, quiet=quiet_mode
+                    input_source, quiet=args.quiet
                 )
 
             if not quiet_mode:
@@ -718,12 +719,13 @@ def main():
                     ),
                 }
             else:
+                # Show progress even when output goes to stdout (unless --quiet)
                 success, metadata, session = download_akoma_ntoso_via_opendata(
-                    input_source, xml_temp_path, session=session, quiet=quiet_mode
+                    input_source, xml_temp_path, session=session, quiet=args.quiet
                 )
                 if not success:
                     success, metadata, session = download_akoma_ntoso_via_export(
-                        input_source, xml_temp_path, session=session, quiet=quiet_mode
+                        input_source, xml_temp_path, session=session, quiet=args.quiet
                     )
                 if not success:
                     print(

src/normattiva2md/constants.py

@@ -7,4 +7,4 @@
 MAX_FILE_SIZE_MB = 50
 MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024
 DEFAULT_TIMEOUT = 30
-VERSION = "2.1.8"
+VERSION = "2.1.9"

src/normattiva2md/normattiva_api.py

@@ -195,20 +195,13 @@ def extract_params_from_normattiva_url(url, session=None, quiet=False):
         if all(k in params for k in ["dataGU", "codiceRedaz", "dataVigenza"]):
             return params, session
 
-    # Se il link caricaAKN non è presente, probabilmente l'XML non è disponibile
+    # Se il link caricaAKN non è presente, ritorna None per tentare il fallback
     if not link_match:
-        print(
-            "❌ ERRORE: Normattiva non espone il link caricaAKN per questo atto.",
-            file=sys.stderr,
-        )
-        print(
-            "   In questi casi l'esportazione XML sembra richiedere autenticazione",
-            file=sys.stderr,
-        )
-        print(
-            "   o non essere disponibile per l'atto richiesto.",
-            file=sys.stderr,
-        )
+        if not quiet:
+            print(
+                "⚠️  Link caricaAKN non trovato, tentativo con fallback...",
+                file=sys.stderr,
+            )
         return None, session
 
     # Estrai parametri dagli input hidden usando regex (fallback)
@@ -447,6 +440,9 @@ def download_akoma_ntoso_via_opendata(url, output_path, session=None, quiet=Fals
         "Accept-Language": "it-IT,it;q=0.9,en;q=0.8",
     }
 
+    if not quiet:
+        print("🔄 Tentativo download via API OpenData...", file=sys.stderr)
+
     try:
         response = session.get(
             url, headers={**headers, "Accept": "text/html"}, timeout=DEFAULT_TIMEOUT
@@ -519,6 +515,10 @@ def download_akoma_ntoso_via_opendata(url, output_path, session=None, quiet=Fals
 
     status_url = f"{base_url}/api/v1/ricerca-asincrona/check-status/{token}"
     stato = None
+
+    if not quiet:
+        print("⏳ Preparazione collezione OpenData", end="", file=sys.stderr, flush=True)
+
     for _ in range(60):
         try:
             status_response = session.get(
@@ -534,8 +534,14 @@ def download_akoma_ntoso_via_opendata(url, output_path, session=None, quiet=Fals
                 break
         except requests.RequestException:
             pass
+
+        if not quiet:
+            print(".", end="", file=sys.stderr, flush=True)
         time.sleep(2)
 
+    if not quiet:
+        print()  # New line after progress dots
+
     if stato != 3:
         print("❌ ERRORE: ricerca OpenData non completata in tempo utile.", file=sys.stderr)
         return False, None, session