{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# normattiva2md - Quickstart\n",
    "\n",
    "Questo notebook mostra come usare `normattiva2md` come libreria Python per convertire documenti legali italiani da normattiva.it a Markdown.\n",
    "\n",
    "## Installazione\n",
    "\n",
    "```bash\n",
    "pip install normattiva2md\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Conversione da URL\n",
    "\n",
    "Il caso d'uso più comune: convertire un documento direttamente dall'URL di normattiva.it"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 102,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Titolo: ((Disposizioni per favorire e semplificare l'accesso degli utenti e,\n",
      "Data GU: 20040117\n",
      "Codice Redazionale: 004G0015\n",
      "\n",
      "Lunghezza markdown: 23626 caratteri\n"
     ]
    }
   ],
   "source": [
    "from normattiva2md import convert_url\n",
    "\n",
    "# Legge Stanca (Legge 4/2004 - Accessibilità)\n",
    "url = \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4\"\n",
    "\n",
    "result = convert_url(url, quiet=True)\n",
    "\n",
    "if result:\n",
    "    print(f\"Titolo: {result.title}\")\n",
    "    print(f\"Data GU: {result.data_gu}\")\n",
    "    print(f\"Codice Redazionale: {result.codice_redaz}\")\n",
    "    print(f\"\\nLunghezza markdown: {len(result.markdown)} caratteri\")\n",
    "else:\n",
    "    print(\"Conversione fallita\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visualizzare il contenuto (primi 750 caratteri)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 103,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "---\n",
      "url: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4\n",
      "url_xml: https://www.normattiva.it/do/atto/caricaAKN?dataGU=20040117&codiceRedaz=004G0015&dataVigenza=20260101\n",
      "url_permanente: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig=2022-07-16\n",
      "dataGU: 20040117\n",
      "codiceRedaz: 004G0015\n",
      "dataVigenza: 20260101\n",
      "---\n",
      "\n",
      "# ((Disposizioni per favorire e semplificare l'accesso degli utenti e,\n",
      "in particolare, delle persone con disabilita' agli strumenti\n",
      "informatici)).\n",
      "\n",
      "La Camera dei deputati ed il Senato della Repubblica hanno\n",
      "\n",
      "approvato;\n",
      "\n",
      "IL PRESIDENTE DELLA REPUBBLICA\n",
      "\n",
      "Promulga la seguente legge:\n",
      "\n",
      "## Art. 1.\n",
      "\n",
      "(Obiettivi e finalita)\n",
      "\n",
      "1. La Repubblica riconosce e tutela il diritto di ogni persona ad accede\n"
     ]
    }
   ],
   "source": [
    "# Mostra i primi 750 caratteri\n",
    "print(result.markdown[:750])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Salvare su file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 104,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "File salvato: legge_stanca.md\n"
     ]
    }
   ],
   "source": [
    "# Salva il markdown su file\n",
    "result.save(\"legge_stanca.md\")\n",
    "print(\"File salvato: legge_stanca.md\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Estrarre un singolo articolo\n",
    "\n",
    "Puoi estrarre solo un articolo specifico usando il parametro `article`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 105,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "---\n",
      "url: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4\n",
      "url_xml: https://www.normattiva.it/do/atto/caricaAKN?dataGU=20040117&codiceRedaz=004G0015&dataVigenza=20260101\n",
      "url_permanente: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig=2022-07-16\n",
      "dataGU: 20040117\n",
      "codiceRedaz: 004G0015\n",
      "dataVigenza: 20260101\n",
      "article: 3\n",
      "---\n",
      "\n",
      "## Art. 3. - (Soggetti erogatori)\n",
      "\n",
      "1. La presente legge si applica alle pubbliche amministrazioni di cui al comma 2 dell'articolo 1 del decreto legislativo 30 marzo 2001, n. 165, e successive modificazioni, agli enti pubblici economici, alle aziende private concessionarie di servizi pubblici, alle aziende municipalizzate regionali, agli enti di assistenza e di riabilitazione pubblici, alle aziende di trasporto e di telecomunicazione a prevalente partecipazione di capitale pubblico e alle aziende appaltatrici di servizi informatici, agli organismi di diritto pubblico ai sensi dell'articolo 2, paragrafo 1, punto 4, della direttiva 2014/24/UE del Parlamento europeo e del Consiglio, del 26 febbraio 2014 nonche' a tutti i soggetti che usufruiscono di contributi pubblici o agevolazioni per l'erogazione dei propri servizi tramite sistemi informativi o internet.\n",
      "\n",
      "1-bis. La presente legge si applica altresi' ai soggetti giuridici diversi da quelli di cui al comma 1, che offrono servizi al pubblico attraverso siti web o applicazioni mobili, con un fatturato medio, negli ultimi tre anni di attivita', superiore a ((cinquecento)) milioni di euro.\n",
      "\n",
      "2. Le disposizioni della presente legge in ordine agli obblighi per l'accessibilita' non si applicano ai contenuti che si trovano esclusivamente su dispositivi mobili o programmi utente per dispositivi mobili sviluppati per gruppi chiusi di utenti o per uso specifico in determinati contesti e non disponibili e usati da ampi segmenti di utenti. Le medesime disposizioni non si applicano ai contenuti di extranet o intranet, di cui all'articolo 2, comma 1, lettera a-quater), pubblicati prima del 23 settembre 2019 fino a una loro revisione sostanziale.\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Estrai solo l'articolo 3\n",
    "result_art3 = convert_url(url, article=\"3\", quiet=True)\n",
    "\n",
    "if result_art3:\n",
    "    print(result_art3.markdown)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Articoli con estensione (bis, ter, etc.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 106,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "---\n",
      "url: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4\n",
      "url_xml: https://www.normattiva.it/do/atto/caricaAKN?dataGU=20040117&codiceRedaz=004G0015&dataVigenza=20260101\n",
      "url_permanente: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig=2022-07-16\n",
      "dataGU: 20040117\n",
      "codiceRedaz: 004G0015\n",
      "dataVigenza: 20260101\n",
      "article: 3quater\n",
      "---\n",
      "\n",
      "## Art. 3-quater. - (( (Dichiarazione di accessibilita'). ))\n",
      "\n",
      "((\n",
      "\n",
      "1. I soggetti erogatori, forniscono e aggiornano periodicamente una dichiarazione di accessibilita' particolareggiata, esaustiva e chiara sulla conformita' dei rispettivi siti web e applicazioni mobili alla presente legge.\n",
      "\n",
      "2. La dichiarazione di accessibilita' comprende, altresi', i seguenti elementi:\n",
      "\n",
      "- a) indicazione delle parti di contenuto del sito web o dell'applicazione mobile non accessibili per onere sproporzionato ai sensi dell'articolo 3-ter, con le motivazioni che ne giustificano l'inaccessibilita' e l'indicazione di eventuali soluzioni di accessibilita' alternative fornite dai soggetti erogatori;\n",
      "- b) la descrizione del meccanismo di feedback, e relativo link, istituito per consentire a chiunque di notificare ai soggetti erogatori eventuali difetti dei sistemi informatici, ivi compresi i siti web e le applicazioni mobili, in termini di conformita' ai principi di accessibilita' di cui all'articolo 3-bis e alle prescrizioni in materia di accessibilita' dettate dalle linee guida di cui all'articolo 11, nonche' di richiedere le informazioni non accessibili e l'adeguamento dei sistemi;\n",
      "- c) il link alla procedura di cui all'articolo 3-quinquies cui e' possibile fare ricorso in caso di risposta insoddisfacente o di mancata risposta, nel termine di trenta giorni, alla notifica o alla richiesta di cui alla lettera b).\n",
      "\n",
      "3. Il modello di dichiarazione di accessibilita' e' definito con le linee guida di cui all'articolo 11, nel rispetto di quanto stabilito dalla Commissione europea.\n",
      "\n",
      "4. La dichiarazione di accessibilita' e' fornita in un formato accessibile ed e' pubblicata sul sito web del soggetto erogatore.\n",
      "\n",
      "5. Per le applicazioni mobili la dichiarazione di accessibilita' e' fornita in un formato accessibile e e' resa accessibile nel sito web del soggetto erogatore che ha sviluppato l'applicazione mobile, unitamente ad altre informazioni disponibili al momento di scaricare l'applicazione.\n",
      "\n",
      "))\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Esempio con articolo 16-bis (se presente nel documento)\n",
    "result_art3quater = convert_url(url, article=\"3quater\", quiet=True)\n",
    "print(result_art3quater.markdown if result_art3quater else \"Articolo 3quater non trovato\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Accedere ai metadata\n",
    "\n",
    "L'oggetto `ConversionResult` contiene tutti i metadata del documento:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 107,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Metadata completi:\n",
      "  codiceRedaz: 004G0015\n",
      "  dataGU: 20040117\n",
      "  dataVigenza: 20260101\n",
      "  urn_nir: urn:nir:stato:legge:2004-01-09;4\n",
      "  url: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4\n",
      "  url_xml: https://www.normattiva.it/do/atto/caricaAKN?dataGU=20040117&codiceRedaz=004G0015&dataVigenza=20260101\n",
      "  url_permanente: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig=2022-07-16\n"
     ]
    }
   ],
   "source": [
    "# Accesso diretto ai metadata\n",
    "print(\"Metadata completi:\")\n",
    "for key, value in result.metadata.items():\n",
    "    print(f\"  {key}: {value}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 108,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Data GU: 20040117\n",
      "Codice Redaz: 004G0015\n",
      "Data Vigenza: 20260101\n",
      "URL: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4\n",
      "URL XML: https://www.normattiva.it/do/atto/caricaAKN?dataGU=20040117&codiceRedaz=004G0015&dataVigenza=20260101\n"
     ]
    }
   ],
   "source": [
    "# Shortcut properties\n",
    "print(f\"Data GU: {result.data_gu}\")\n",
    "print(f\"Codice Redaz: {result.codice_redaz}\")\n",
    "print(f\"Data Vigenza: {result.data_vigenza}\")\n",
    "print(f\"URL: {result.url}\")\n",
    "print(f\"URL XML: {result.url_xml}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Generare link ai riferimenti\n",
    "\n",
    "Con `with_urls=True`, i riferimenti normativi nel testo diventano link cliccabili:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 109,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Trovati 12 link a normattiva.it\n",
      "  - comma 2 dell'articolo 1 del decreto legislativo 30 marzo 2001, n. 165\n",
      "  - articolo 17 del decreto legislativo n. 82 del 2005\n",
      "  - articolo 13, comma 1, lettera c), della legge 12 marzo 1999, n. 68\n",
      "  - D.Lgs. 27 maggio 2022, n. 82\n",
      "  - comma 4 dell'articolo 7 del decreto legislativo 30 marzo 2001, n. 165\n"
     ]
    }
   ],
   "source": [
    "result_with_links = convert_url(url, with_urls=True, quiet=True)\n",
    "\n",
    "# Cerca link nel markdown\n",
    "import re\n",
    "links = re.findall(r'\\[([^\\]]+)\\]\\(https://www\\.normattiva\\.it[^)]+\\)', result_with_links.markdown)\n",
    "print(f\"Trovati {len(links)} link a normattiva.it\")\n",
    "for link in links[:5]:\n",
    "    print(f\"  - {link}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Classe Converter per uso avanzato\n",
    "\n",
    "Per batch processing o configurazione persistente, usa la classe `Converter`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 110,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "OK: ((Disposizioni per favorire e semplificare l'acces...\n",
      "OK: Codice dell'amministrazione digitale....\n",
      "\n",
      "Convertiti 2/2 documenti\n"
     ]
    }
   ],
   "source": [
    "from normattiva2md import Converter\n",
    "\n",
    "# Crea converter con configurazione\n",
    "conv = Converter(quiet=True)\n",
    "\n",
    "# Batch processing\n",
    "urls = [\n",
    "    \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4\",\n",
    "    \"https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82\",\n",
    "]\n",
    "\n",
    "results = []\n",
    "for url in urls:\n",
    "    result = conv.convert_url(url)\n",
    "    if result:\n",
    "        results.append(result)\n",
    "        print(f\"OK: {result.title[:50]}...\")\n",
    "\n",
    "print(f\"\\nConvertiti {len(results)}/{len(urls)} documenti\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Gestione errori"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 111,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "URL non valido: URL non valido: URL non valido: Dominio non consentito: example.com. Domini permessi: www.normattiva.it, normattiva.it. L'URL deve essere HTTPS e dominio normattiva.it\n"
     ]
    }
   ],
   "source": [
    "from normattiva2md import (\n",
    "    convert_url,\n",
    "    InvalidURLError,\n",
    "    ConversionError,\n",
    "    Normattiva2MDError,\n",
    ")\n",
    "\n",
    "# Test URL invalido\n",
    "try:\n",
    "    result = convert_url(\"https://example.com/not-normattiva\")\n",
    "except InvalidURLError as e:\n",
    "    print(f\"URL non valido: {e}\")\n",
    "except Normattiva2MDError as e:\n",
    "    print(f\"Errore generico: {e}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 112,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Articolo '999' non trovato nel documento\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Articolo 999 non trovato nel documento\n"
     ]
    }
   ],
   "source": [
    "# Articolo non trovato (errore soft - ritorna None)\n",
    "result = convert_url(url, article=\"999\", quiet=True)\n",
    "if result is None:\n",
    "    print(\"Articolo 999 non trovato nel documento\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. Uso con pandas (esempio)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 113,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>titolo</th>\n",
       "      <th>data_gu</th>\n",
       "      <th>codice_redaz</th>\n",
       "      <th>lunghezza</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>((Disposizioni per favorire e semplificare l'a...</td>\n",
       "      <td>20040117</td>\n",
       "      <td>004G0015</td>\n",
       "      <td>23626</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Codice dell'amministrazione digitale.</td>\n",
       "      <td>20050516</td>\n",
       "      <td>005G0104</td>\n",
       "      <td>230300</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                              titolo   data_gu codice_redaz  \\\n",
       "0  ((Disposizioni per favorire e semplificare l'a...  20040117     004G0015   \n",
       "1              Codice dell'amministrazione digitale.  20050516     005G0104   \n",
       "\n",
       "   lunghezza  \n",
       "0      23626  \n",
       "1     230300  "
      ]
     },
     "execution_count": 113,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Esempio: creare un DataFrame con i metadata di più documenti\n",
    "import pandas as pd\n",
    "\n",
    "data = []\n",
    "for r in results:\n",
    "    data.append({\n",
    "        \"titolo\": r.title,\n",
    "        \"data_gu\": r.data_gu,\n",
    "        \"codice_redaz\": r.codice_redaz,\n",
    "        \"lunghezza\": len(r.markdown),\n",
    "    })\n",
    "\n",
    "df = pd.DataFrame(data)\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Risorse\n",
    "\n",
    "- **Repository**: https://github.com/ondata/normattiva_2_md\n",
    "- **PyPI**: https://pypi.org/project/normattiva2md/\n",
    "- **Documentazione URL**: vedere `docs/URL_NORMATTIVA.md` nel repository"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
