fix: handle escaped urls

Author: aborruso

LOG.md

@@ -2,6 +2,13 @@
 
 Questo file documenta gli avanzamenti significativi e le decisioni chiave del progetto `normattiva_2_md`.
 
+## 2026-01-12
+
+### URL con escape backslash
+
+- Normalizzazione URL normattiva.it con backslash in CLI/API
+- Aggiornati test sicurezza per URL con escape
+
 ## 2026-01-11
 
 ### Coverage Reporting Implementation

openspec/changes/update-url-escape-handling/proposal.md

@@ -0,0 +1,19 @@
+# Update escaped URL handling
+
+## Summary
+Allow conversion when normattiva URLs include backslash-escaped delimiters by normalizing them before validation and download.
+
+## Motivation
+
+- Some terminals or copy sources escape `?`, `;`, `!`, `=` with backslashes, causing URL validation or download failures.
+- Normalize input to reduce user friction and make pasted links work reliably.
+
+## Impact
+
+- CLI/API input handling: normalize escaped URLs before `validate_normattiva_url` and `extract_params_from_normattiva_url`.
+- Tests: add coverage for escaped URL input.
+
+## Open Questions / Risks
+
+- Should normalization remove only backslashes before reserved delimiters or strip all backslashes in URLs?
+- Should the normalized URL be echoed in logs/metadata instead of the raw input?

openspec/changes/update-url-escape-handling/specs/markdown-conversion/spec.md

@@ -0,0 +1,11 @@
+# markdown-conversion Specification Delta
+
+## ADDED Requirements
+
+### Requirement: Escaped Normattiva URL Normalization
+The system SHALL normalize normattiva.it URLs containing escape characters from user input before validation and download.
+
+#### Scenario: Backslash-escaped URL from clipboard
+- **WHEN** user provides a normattiva.it URL containing backslash-escaped reserved characters (for example `\?`, `\;`, `\!`, `\=`)
+- **THEN** the system SHALL remove the escape backslashes to produce a valid URL
+- **AND** proceed with validation and download using the normalized URL

openspec/changes/update-url-escape-handling/tasks.md

@@ -0,0 +1,15 @@
+# Tasks for update-url-escape-handling
+
+## URL Normalization
+
+- [ ] Identify URL intake points (CLI, `convert_url`, `is_normattiva_url`) and add a normalization helper for escaped delimiters.
+- [ ] Normalize backslash-escaped reserved characters before validation and download.
+
+## Error Messaging
+
+- [ ] Ensure logs and metadata use the normalized URL consistently.
+
+## Validation
+
+- [ ] Add a unit or CLI test for escaped URL input (use the example from the request).
+- [ ] Run relevant tests (`python -m unittest ...` or `make test`).

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "normattiva2md"
-version = "2.1.5"
+version = "2.1.6"
 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.5",
+    version="2.1.6",
     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

@@ -37,10 +37,15 @@
     download_akoma_ntoso,
     extract_params_from_normattiva_url,
     is_normattiva_url,
+    normalize_normattiva_url,
     validate_normattiva_url,
 )
 from .utils import load_env_file
-from .xml_parser import construct_article_eid, extract_metadata_from_xml, filter_xml_to_article
+from .xml_parser import (
+    construct_article_eid,
+    extract_metadata_from_xml,
+    filter_xml_to_article,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -81,22 +86,24 @@ def convert_url(
     # Load .env file for API keys
     load_env_file()
 
+    normalized_url = normalize_normattiva_url(url)
+
     # Validate URL
     try:
-        validate_normattiva_url(url)
+        validate_normattiva_url(normalized_url)
     except ValueError as e:
         raise InvalidURLError(
-            f"URL non valido: {e}. "
-            f"L'URL deve essere HTTPS e dominio normattiva.it"
+            f"URL non valido: {e}. L'URL deve essere HTTPS e dominio normattiva.it"
         )
 
     if not quiet:
-        logger.info(f"Conversione URL: {url}")
+        logger.info(f"Conversione URL: {normalized_url}")
 
     # Extract parameters from URL
-    params, session = extract_params_from_normattiva_url(url, quiet=quiet)
+    params, session = extract_params_from_normattiva_url(normalized_url, quiet=quiet)
+
     if not params:
-        logger.warning(f"Impossibile estrarre parametri da {url}")
+        logger.warning(f"Impossibile estrarre parametri da {normalized_url}")
         return None
 
     # Download XML to temp file
@@ -114,7 +121,7 @@ def convert_url(
             "dataGU": params["dataGU"],
             "codiceRedaz": params["codiceRedaz"],
             "dataVigenza": params["dataVigenza"],
-            "url": url,
+            "url": normalized_url,
             "url_xml": f"https://www.normattiva.it/do/atto/caricaAKN?dataGU={params['dataGU']}&codiceRedaz={params['codiceRedaz']}&dataVigenza={params['dataVigenza']}",
         }
 
@@ -132,7 +139,7 @@ def convert_url(
         )
 
         if result:
-            result.url = url
+            result.url = normalized_url
             result.url_xml = metadata["url_xml"]
 
         return result
@@ -182,8 +189,7 @@ def convert_xml(
     # Check file exists
     if not os.path.exists(xml_path):
         raise XMLFileNotFoundError(
-            f"File XML non trovato: '{xml_path}'. "
-            f"Verifica che il path sia corretto."
+            f"File XML non trovato: '{xml_path}'. Verifica che il path sia corretto."
         )
 
     if not quiet:
@@ -352,7 +358,9 @@ def search_law(
             )
 
         if response.status_code != 200:
-            logger.warning(f"Errore Exa API (HTTP {response.status_code}): {response.text}")
+            logger.warning(
+                f"Errore Exa API (HTTP {response.status_code}): {response.text}"
+            )
             return []
 
         data = response.json()
@@ -373,7 +381,9 @@ def search_law(
             query_lower,
             re.IGNORECASE,
         )
-        requested_article = article_match.group(1).replace(" ", "") if article_match else None
+        requested_article = (
+            article_match.group(1).replace(" ", "") if article_match else None
+        )
 
         for result in raw_results:
             result_url = result.get("url")

src/normattiva2md/cli.py

@@ -42,9 +42,9 @@ def print_rich_help():
     # Legal warning
     warning_text = Text()
     warning_text.append(
-        "⚠️  I testi presenti nella banca dati \"Normattiva\" non hanno carattere di ufficialità.\n"
+        '⚠️  I testi presenti nella banca dati "Normattiva" non hanno carattere di ufficialità.\n'
         "L'unico testo ufficiale e definitivo è quello pubblicato sulla Gazzetta Ufficiale Italiana.",
-        style="bold yellow on dark_red"
+        style="bold yellow on dark_red",
     )
     warning_panel = Panel(
         warning_text,
@@ -183,7 +183,7 @@ def print_rich_help():
     footer_text.append("↑↓ PgUp/PgDn Spazio ", style="dim yellow")
     footer_text.append("| Esci: ", style="dim italic")
     footer_text.append("q", style="dim yellow")
-    
+
     footer = Panel(
         footer_text,
         border_style="dim",
@@ -203,6 +203,7 @@ def print_rich_help():
 from .utils import sanitize_output_path, generate_snake_case_filename, load_env_file
 from .normattiva_api import (
     is_normattiva_url,
+    normalize_normattiva_url,
     validate_normattiva_url,
     extract_params_from_normattiva_url,
     download_akoma_ntoso,
@@ -599,6 +600,7 @@ def main():
 
     # Auto-detect: URL o file locale?
     if is_normattiva_url(input_source):
+        input_source = normalize_normattiva_url(input_source)
         # Gestione URL
         if not quiet_mode:
             print(f"Rilevato URL normattiva.it: {input_source}", file=sys.stderr)

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

src/normattiva2md/normattiva_api.py

@@ -1,10 +1,35 @@
+import os
 import re
 import sys
+from datetime import datetime
 from urllib.parse import urlparse
-from .constants import ALLOWED_DOMAINS, DEFAULT_TIMEOUT, VERSION, MAX_FILE_SIZE_BYTES, MAX_FILE_SIZE_MB
+
 import requests
-import os
-from datetime import datetime
+
+from .constants import (
+    ALLOWED_DOMAINS,
+    DEFAULT_TIMEOUT,
+    VERSION,
+    MAX_FILE_SIZE_BYTES,
+    MAX_FILE_SIZE_MB,
+)
+
+
+def normalize_normattiva_url(url):
+    """
+    Normalizza URL normattiva.it rimuovendo escape backslash.
+
+    Args:
+        url: URL string
+
+    Returns:
+        str: URL normalizzato
+    """
+    if not isinstance(url, str):
+        return url
+
+    return url.replace("\\", "")
+
 
 def validate_normattiva_url(url):
     """
@@ -20,6 +45,7 @@ def validate_normattiva_url(url):
         ValueError: If URL is invalid or not from allowed domain
     """
     try:
+        url = normalize_normattiva_url(url)
         parsed = urlparse(url)
 
         # Check scheme is HTTPS
@@ -39,6 +65,7 @@ def validate_normattiva_url(url):
     except Exception as e:
         raise ValueError(f"URL non valido: {e}")
 
+
 def is_normattiva_url(input_str):
     """
     Verifica se l'input è un URL di normattiva.it
@@ -52,17 +79,20 @@ def is_normattiva_url(input_str):
     if not isinstance(input_str, str):
         return False
 
+    normalized = normalize_normattiva_url(input_str)
+
     # Check if it looks like a URL
-    if not re.match(r"https?://(www\.)?normattiva\.it/", input_str, re.IGNORECASE):
+    if not re.match(r"https?://(www\.)?normattiva\.it/", normalized, re.IGNORECASE):
         return False
 
     # Validate URL for security
     try:
-        validate_normattiva_url(input_str)
+        validate_normattiva_url(normalized)
         return True
     except ValueError:
         return False
 
+
 def is_normattiva_export_url(url):
     """
     Verifica se l'URL è un URL di esportazione atto intero di normattiva.it
@@ -82,6 +112,7 @@ def is_normattiva_export_url(url):
     # Check if it's an export URL
     return "/esporta/attoCompleto" in url and is_normattiva_url(url)
 
+
 def extract_params_from_normattiva_url(url, session=None, quiet=False):
     """
     Scarica la pagina normattiva e estrae i parametri necessari per il download
@@ -100,6 +131,8 @@ def extract_params_from_normattiva_url(url, session=None, quiet=False):
     Returns:
         tuple: (params dict, session)
     """
+    url = normalize_normattiva_url(url)
+
     # Reject export URLs as they require authentication
     if is_normattiva_export_url(url):
         print(