Release v2.1.8: OpenData AKN fallback

Author: aborruso

DEVELOPMENT.md

@@ -74,6 +74,9 @@ source .venv/bin/activate  # Linux/macOS
 # or
 .venv\Scripts\activate  # Windows
 
+# Install the package in editable mode so tests can import `normattiva2md`
+pip3 install -e .
+
 # Then run tests
 make test
 ```
@@ -91,17 +94,25 @@ make test
 
 ```bash
 source .venv/bin/activate
+pip3 install -e .
 python3 -m unittest discover -s tests
 ```
 
 ### Alternative: pytest (requires install)
 
 ```bash
 source .venv/bin/activate
+pip3 install -e .
 pip3 install pytest
 python3 -m pytest tests/ -v
 ```
 
+### Note on network-dependent tests
+
+- Some tests hit external services (Normattiva, Exa API, programmagoverno.gov.it).
+- These can fail due to network or API availability; in that case, the failures are not necessarily regressions.
+- For consistent results, ensure network access and configure `EXA_API_KEY` if running Exa tests.
+
 ### Coverage Testing
 
 **Current coverage: 40%** (Target: 70%+)

LOG.md

@@ -1467,5 +1467,13 @@ Creata pianificazione completa per rendere normattiva2md usabile da notebook e s
 ## 2026-01-01
 - Improved CLI help output with Rich library for better readability and organization
 
+## 2026-01-29
+### Fallback OpenData AKN + flag for OpenData
+
+- **Fallback automatico**: se l'export Akoma (`caricaAKN`) non è disponibile, usa OpenData AKN (ZIP) per recuperare il file XML.
+- **Nuovo flag CLI**: `--opendata` per forzare il download via OpenData su qualsiasi norma.
+- **API Python**: `convert_url(..., force_opendata=True)` per forzare OpenData.
+- **Selezione XML**: scelta automatica del file di vigenza più adatto dal pacchetto ZIP.
+
 ## 2026-01-21
 - Bumped version to v2.1.7 for upcoming release

README.md

@@ -233,6 +233,9 @@ La CLI riconosce automaticamente gli URL di `normattiva.it` e scarica il documen
 # Conversione diretta URL → Markdown (output su file)
 normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" legge.md
 
+# Forza download via OpenData (quando manca export Akoma)
+normattiva2md --opendata "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" legge.md
+
 # Conversione diretta con output su stdout (utile per pipe)
 normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82"
 
@@ -438,7 +441,8 @@ opzioni:
                          File Markdown di output (default: stdout)
    -s SEARCH, --search SEARCH
                          Cerca documento in linguaggio naturale (richiede Exa AI API)
-   --keep-xml            Mantiene il file XML temporaneo dopo la conversione
+  --keep-xml            Mantiene il file XML temporaneo dopo la conversione
+  --opendata            Forza download Akoma Ntoso via API OpenData (ZIP AKN)
    -q, --quiet           Modalità silenziosa (nessun output su stderr)
    -c, --completo        Forza download completo anche con URL articolo-specifico
    --with-references     Scarica anche tutti i riferimenti legislativi citati

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "normattiva2md"
-version = "2.1.7"
+version = "2.1.8"
 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.7",
+    version="2.1.8",
     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/api.py

@@ -35,6 +35,8 @@
 from .models import ConversionResult, SearchResult
 from .normattiva_api import (
     download_akoma_ntoso,
+    download_akoma_ntoso_via_export,
+    download_akoma_ntoso_via_opendata,
     extract_params_from_normattiva_url,
     is_normattiva_url,
     normalize_normattiva_url,
@@ -54,6 +56,7 @@ def convert_url(
     url: str,
     article: Optional[str] = None,
     with_urls: bool = False,
+    force_opendata: bool = False,
     quiet: bool = False,
 ) -> Optional[ConversionResult]:
     """
@@ -82,6 +85,9 @@ def convert_url(
 
         >>> # Con link inline
         >>> result = convert_url("https://...", with_urls=True)
+
+        >>> # Forza download via OpenData
+        >>> result = convert_url("https://...", force_opendata=True)
     """
     # Load .env file for API keys
     load_env_file()
@@ -100,30 +106,48 @@ def convert_url(
         logger.info(f"Conversione URL: {normalized_url}")
 
     # Extract parameters from URL
-    params, session = extract_params_from_normattiva_url(normalized_url, quiet=quiet)
-
-    if not params:
-        logger.warning(f"Impossibile estrarre parametri da {normalized_url}")
-        return None
+    params = None
+    session = None
+    if not force_opendata:
+        params, session = extract_params_from_normattiva_url(
+            normalized_url, quiet=quiet
+        )
 
     # Download XML to temp file
     with tempfile.NamedTemporaryFile(suffix=".xml", delete=False) as tmp:
         xml_path = tmp.name
 
     try:
-        success = download_akoma_ntoso(params, xml_path, session, quiet=quiet)
-        if not success:
-            logger.warning(f"Download fallito per {url}")
-            return None
-
-        # Build metadata
-        metadata = {
-            "dataGU": params["dataGU"],
-            "codiceRedaz": params["codiceRedaz"],
-            "dataVigenza": params["dataVigenza"],
-            "url": normalized_url,
-            "url_xml": f"https://www.normattiva.it/do/atto/caricaAKN?dataGU={params['dataGU']}&codiceRedaz={params['codiceRedaz']}&dataVigenza={params['dataVigenza']}",
-        }
+        if params and not force_opendata:
+            success = download_akoma_ntoso(params, xml_path, session, quiet=quiet)
+            if not success:
+                logger.warning(f"Download fallito per {url}")
+                return None
+
+            # Build metadata
+            metadata = {
+                "dataGU": params["dataGU"],
+                "codiceRedaz": params["codiceRedaz"],
+                "dataVigenza": params["dataVigenza"],
+                "url": normalized_url,
+                "url_xml": (
+                    "https://www.normattiva.it/do/atto/caricaAKN"
+                    f"?dataGU={params['dataGU']}"
+                    f"&codiceRedaz={params['codiceRedaz']}"
+                    f"&dataVigenza={params['dataVigenza']}"
+                ),
+            }
+        else:
+            success, metadata, session = download_akoma_ntoso_via_opendata(
+                normalized_url, xml_path, session=session, quiet=quiet
+            )
+            if not success:
+                success, metadata, session = download_akoma_ntoso_via_export(
+                    normalized_url, xml_path, session=session, quiet=quiet
+                )
+            if not success:
+                logger.warning(f"Download fallito per {url}")
+                return None
 
         # Add article to metadata if specified
         if article:

src/normattiva2md/cli.py

@@ -138,6 +138,9 @@ def print_rich_help():
     proc_table.add_column("Description")
 
     proc_table.add_row("--with-urls", "Genera link agli URL normattiva.it")
+    proc_table.add_row(
+        "--opendata", "Forza download Akoma Ntoso via API OpenData (ZIP AKN)"
+    )
     proc_table.add_row("--with-references", "Scarica anche leggi citate")
     proc_table.add_row("--provvedimenti", "Esporta provvedimenti attuativi CSV")
     proc_table.add_row("--validate", "Validazione strutturale del Markdown")
@@ -207,6 +210,8 @@ def print_rich_help():
     validate_normattiva_url,
     extract_params_from_normattiva_url,
     download_akoma_ntoso,
+    download_akoma_ntoso_via_export,
+    download_akoma_ntoso_via_opendata,
 )
 from .exa_api import lookup_normattiva_url
 from .akoma_utils import parse_article_reference
@@ -405,6 +410,11 @@ def main():
         action="store_true",
         help="Genera link Markdown agli URL originali di normattiva.it per gli articoli citati",
     )
+    parser.add_argument(
+        "--opendata",
+        action="store_true",
+        help="Forza download Akoma Ntoso via API OpenData (ZIP AKN)",
+    )
     parser.add_argument(
         "-q", "--quiet", action="store_true", help="Disabilita output non essenziali"
     )
@@ -653,46 +663,79 @@ def main():
                         f"Rilevato riferimento articolo: {article_ref}", file=sys.stderr
                     )
 
-            # Estrai parametri dalla pagina
-            params, session = extract_params_from_normattiva_url(
-                input_source, quiet=quiet_mode
-            )
-            if not params:
-                print("❌ Impossibile estrarre parametri dall'URL", file=sys.stderr)
-                sys.exit(1)
+            # Estrai parametri dalla pagina (se non forziamo OpenData)
+            params = None
+            session = None
+            if not args.opendata:
+                params, session = extract_params_from_normattiva_url(
+                    input_source, quiet=quiet_mode
+                )
 
             if not quiet_mode:
-                print(f"\nParametri estratti:", file=sys.stderr)
-                print(f"  dataGU: {params['dataGU']}", file=sys.stderr)
-                print(f"  codiceRedaz: {params['codiceRedaz']}", file=sys.stderr)
-                print(f"  dataVigenza: {params['dataVigenza']}\n", file=sys.stderr)
+                if params:
+                    print(f"\nParametri estratti:", file=sys.stderr)
+                    print(f"  dataGU: {params['dataGU']}", file=sys.stderr)
+                    print(f"  codiceRedaz: {params['codiceRedaz']}", file=sys.stderr)
+                    print(f"  dataVigenza: {params['dataVigenza']}\n", file=sys.stderr)
+                elif args.opendata:
+                    print(
+                        "⚠️ OpenData forzato: download via OpenData (ZIP AKN)",
+                        file=sys.stderr,
+                    )
+                else:
+                    print(
+                        "⚠️ Link caricaAKN non disponibile: tentativo fallback OpenData",
+                        file=sys.stderr,
+                    )
 
             # Crea file XML temporaneo con tempfile module (più sicuro)
             temp_fd, xml_temp_path = tempfile.mkstemp(
-                suffix=f"_{params['codiceRedaz']}.xml", prefix="akoma2md_"
+                suffix=f"_{params['codiceRedaz'] if params else 'export'}.xml",
+                prefix="akoma2md_",
             )
             os.close(temp_fd)  # Close file descriptor, we'll write with requests
 
             # Scarica XML
-            if not download_akoma_ntoso(
-                params, xml_temp_path, session, quiet=quiet_mode
-            ):
-                print("❌ Errore durante il download del file XML", file=sys.stderr)
-                sys.exit(1)
+            if params and not args.opendata:
+                if not download_akoma_ntoso(
+                    params, xml_temp_path, session, quiet=quiet_mode
+                ):
+                    print(
+                        "❌ Errore durante il download del file XML",
+                        file=sys.stderr,
+                    )
+                    sys.exit(1)
+                metadata = {
+                    "dataGU": params["dataGU"],
+                    "codiceRedaz": params["codiceRedaz"],
+                    "dataVigenza": params["dataVigenza"],
+                    "url": input_source,
+                    "url_xml": (
+                        "https://www.normattiva.it/do/atto/caricaAKN"
+                        f"?dataGU={params['dataGU']}"
+                        f"&codiceRedaz={params['codiceRedaz']}"
+                        f"&dataVigenza={params['dataVigenza']}"
+                    ),
+                }
+            else:
+                success, metadata, session = download_akoma_ntoso_via_opendata(
+                    input_source, xml_temp_path, session=session, quiet=quiet_mode
+                )
+                if not success:
+                    success, metadata, session = download_akoma_ntoso_via_export(
+                        input_source, xml_temp_path, session=session, quiet=quiet_mode
+                    )
+                if not success:
+                    print(
+                        "❌ Errore durante il download via fallback OpenData/HTML",
+                        file=sys.stderr,
+                    )
+                    sys.exit(1)
 
             # Converti a Markdown
             if not quiet_mode:
                 print(f"\nConversione in Markdown...", file=sys.stderr)
 
-            # Prepare metadata dict for front matter
-            metadata = {
-                "dataGU": params["dataGU"],
-                "codiceRedaz": params["codiceRedaz"],
-                "dataVigenza": params["dataVigenza"],
-                "url": input_source,  # The original URL
-                "url_xml": f"https://www.normattiva.it/do/atto/caricaAKN?dataGU={params['dataGU']}&codiceRedaz={params['codiceRedaz']}&dataVigenza={params['dataVigenza']}",
-            }
-
             # Add article reference to metadata if present (or if overridden by --completo)
             if article_ref:
                 metadata["article"] = article_ref

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.7"
+VERSION = "2.1.8"