Normattiva2MD

https://pypi.org/project/normattiva2md/
Admin
Normattiva2MD is a command-line tool designed to convert XML documents in Akoma Ntoso format...
Tokens:13,195
Snippets:142
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install normattiva2md from source

Source: https://pypi.org/project/normattiva2md

Clone the repository, set up a virtual environment, and install the package in editable mode from its source code.

```bash
git clone https://github.com/ondata/normattiva_2_md.git
cd normattiva_2_md
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows
pip3 install -e .
```

--------------------------------

### Install normattiva2md from source

Source: https://pypi.org/project/normattiva2md/2.1.5

Clone the repository and install the package in editable mode for development or direct execution.

```bash
git clone https://github.com/ondata/normattiva_2_md.git
cd normattiva_2_md
pip install -e .
normattiva2md input.xml output.md
```

--------------------------------

### Install normattiva2md using uv

Source: https://pypi.org/project/normattiva2md/2.1.5

Install the normattiva2md package using the uv package installer.

```bash
uv tool install normattiva2md
```

--------------------------------

### Interactive Session Example

Source: https://pypi.org/project/normattiva2md/2.1.5

Demonstrates an interactive session using --debug-search, showing the process of selecting a result, confirming download, and specifying a filename.

```bash
$ normattiva2md -s "legge stanca accessibilità" --debug-search

🔍 Risultati trovati per: legge stanca
Seleziona il numero del risultato desiderato (1-5), o 0 per annullare:
  [1] DECRETO-LEGGE 7 giugno 2024, n. 73...
      URL: https://www.normattiva.it/...
      Preferenza: -30

  [2] LEGGE 24 maggio 1970, n. 336...
      URL: https://www.normattiva.it/uri-res/N2Ls?...
      Preferenza: 24

  [3] LEGGE 9 gennaio 2004, n. 4...
      URL: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig
      Preferenza: 24

Scelta: 3
✅ URL selezionato manualmente: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig

📥 Vuoi scaricare questo documento? (s/N): s
📝 Nome file [legge_9_gennaio_2004_n_4.md]:
✅ URL selezionato: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig
Rilevato URL normattiva.it: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig
...
✅ Conversione completata: legge_9_gennaio_2004_n_4.md
```

--------------------------------

### Run Basic Tests

Source: https://pypi.org/project/normattiva2md

Execute basic tests using the installed package.

```bash
normattiva2md sample.xml output.md
```

--------------------------------

### Natural Language Search Example

Source: https://pypi.org/project/normattiva2md/2.1.5

Example of performing a natural language search for 'legge stanca accessibilità' and saving the output to 'legge_stanca.md'. Requires Exa AI API configuration.

```bash
# Natural language search (requires Exa AI - ALWAYS use -s)
normattiva2md -s "legge stanca accessibilità" legge_stanca.md
normattiva2md -s "decreto dignità" > decreto.md
```

--------------------------------

### Clone Repository and Set Up Virtual Environment

Source: https://pypi.org/project/normattiva2md/2.1.5

Clone the normattiva2md repository and set up a Python virtual environment. Activate the environment and install the project in editable mode.

```bash
git clone https://github.com/ondata/normattiva_2_md.git
cd normattiva_2_md
python3 -m venv .venv
source .venv/bin/activate  # Su Windows: .venv\Scripts\activate
pip3 install -e .
```

--------------------------------

### Install normattiva2md using pip

Source: https://pypi.org/project/normattiva2md/2.1.5

Install the normattiva2md package using the pip package installer.

```bash
pip install normattiva2md
```

--------------------------------

### Quick Start: Convert URL, XML, and Search Law

Source: https://pypi.org/project/normattiva2md/2.1.5

Demonstrates basic usage for converting a law from a URL, converting a local XML file, and searching for laws using natural language. Requires Exa API key for search.

```python
from normattiva2md import convert_url, convert_xml, search_law

# Conversione da URL
result = convert_url("https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4")
print(result.markdown[:500])
print(result.title)
print(result.metadata)
result.save("legge_stanca.md")

# Conversione da file XML locale
result = convert_xml("documento.xml")
result.save("output.md")

# Ricerca in linguaggio naturale (richiede Exa API key)
results = search_law("legge stanca accessibilità")
for r in results:
    print(f"[{r.score:.2f}] {r.title}")
    print(f"  URL: {r.url}")

```

--------------------------------

### Example Markdown Output

Source: https://pypi.org/project/normattiva2md/2.1.5

This is an example of the generated Markdown, showcasing the YAML front matter, heading structure, and highlighted legislative changes.

```markdown
---
url: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82
url_xml: https://www.normattiva.it/do/atto/caricaAKN?dataGU=20050307&codiceRedaz=005G0104&dataVigenza=20251101
dataGU: 20050307
codiceRedaz: 005G0104
dataVigenza: 20251101
---

# Codice dell'amministrazione digitale. 

## Capo I - PRINCIPI GENERALI

### Sezione I - Definizioni, finalita' e ambito di applicazione

#### Art. 1. - Definizioni

1. Ai fini del presente codice si intende per:

- a) documento informatico: il documento elettronico...
- b) firma digitale: un particolare tipo di firma...
- c) ((identità digitale)): la rappresentazione informatica...

#### Art. 2. - Finalita' e ambito di applicazione

1. Lo Stato, le Regioni e le autonomie locali...

### Sezione II - ((Carta della cittadinanza digitale))

#### Art. 3. - Diritto all'uso delle tecnologie

1. I cittadini e le imprese hanno il diritto...

```

--------------------------------

### Quick Start: Basic Conversions and Search

Source: https://pypi.org/project/normattiva2md

Demonstrates the fundamental functions for converting legal documents from URLs or local XML files, and performing natural language searches for laws.

```APIDOC
## Quick Start: Basic Conversions and Search

This section covers the basic usage of the `normattiva2md` library for common tasks.

### Functions

- `convert_url(url)`: Converts a legal document from a given URL.
- `convert_xml(file_path)`: Converts a legal document from a local XML file.
- `search_law(query)`: Searches for laws using natural language queries (requires Exa API key).

### Usage Examples

```python
from normattiva2md import convert_url, convert_xml, search_law

# Conversion from URL
result = convert_url("https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4")
print(result.markdown[:500])
print(result.title)
print(result.metadata)
result.save("legge_stanca.md")

# Conversion from local XML file
result = convert_xml("documento.xml")
result.save("output.md")

# Natural language search (requires Exa API key)
results = search_law("legge stanca accessibilità")
for r in results:
    print(f"[{r.score:.2f}] {r.title}")
    print(f"  URL: {r.url}")
```
```

--------------------------------

### Force Full Conversion from Article URL

Source: https://pypi.org/project/normattiva2md/2.1.5

Force a complete conversion of the document even when starting from an article-specific URL. Use the --completo flag.

```bash
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto-legge:2018-07-12;87~art3" --completo legge_completa.md
```

```bash
normattiva2md -c "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53~art16bis" legge_completa.md
```

--------------------------------

### Create Standalone Executable with PyInstaller

Source: https://pypi.org/project/normattiva2md/2.1.5

Install PyInstaller and use it to create a single-file executable of the normattiva2md project. The executable will be located in the 'dist' directory.

```bash
pip install pyinstaller
pyinstaller --onefile --name normattiva2md __main__.py
```

--------------------------------

### Execute normattiva2md directly from source

Source: https://pypi.org/project/normattiva2md

Run the normattiva2md script directly from the cloned repository without performing a formal installation. This is useful for development or testing.

```bash
git clone https://github.com/ondata/normattiva_2_md.git
cd normattiva_2_md
python3 __main__.py input.xml output.md
```

--------------------------------

### Run Basic Tests

Source: https://pypi.org/project/normattiva2md/2.1.5

Execute basic tests for normattiva2md using the installed package or the standalone executable. These tests convert a sample XML file to Markdown.

```bash
# Test di base (con package installato)
normattiva2md sample.xml output.md

# Test dell'eseguibile
./dist/normattiva2md sample.xml output.md
```

--------------------------------

### Configure Exa AI API Key using .env file

Source: https://pypi.org/project/normattiva2md/2.1.5

Create a .env file to store your Exa AI API key for natural language search functionality. This is the recommended method.

```bash
echo 'EXA_API_KEY="your-exa-api-key-here"' > .env
cat .env
```

--------------------------------

### Convert with Absolute Paths

Source: https://pypi.org/project/normattiva2md/2.1.5

Demonstrates using absolute paths for both input XML and output Markdown files.

```bash
# With absolute paths
normattiva2md /percorso/documento.xml /percorso/output.md
```

--------------------------------

### Convert URL to Markdown (output to file)

Source: https://pypi.org/project/normattiva2md

Directly converts a Normattiva URL to a Markdown file. This is the recommended method.

```bash
# Conversione diretta URL → Markdown (output su file)
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" legge.md
```

--------------------------------

### Convert URL to Markdown (output to file)

Source: https://pypi.org/project/normattiva2md/2.1.5

Directly convert a Normattiva URL to a Markdown file. The CLI automatically fetches the Akoma Ntoso document.

```bash
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" legge.md
```

--------------------------------

### Create Standalone Executable

Source: https://pypi.org/project/normattiva2md

Build a single executable file for local use with PyInstaller.

```bash
pip install pyinstaller
python3 -m PyInstaller --onefile --name normattiva2md __main__.py
```

--------------------------------

### Display Help Information

Source: https://pypi.org/project/normattiva2md/2.1.5

Shows how to display the help information for the normattiva2md command.

```bash
# Display help
normattiva2md --help
```

--------------------------------

### Normattiva2md CLI Usage

Source: https://pypi.org/project/normattiva2md/2.1.5

Displays the help message and lists all available command-line arguments and options for the normattiva2md tool.

```bash
utilizzo: normattiva2md [-h] [-v] [-i INPUT] [-o OUTPUT] [-s SEARCH]
                       [--keep-xml] [-q] [-c] [--with-references]
                       [--with-urls] [--debug-search] [--auto-select]
                       [--exa-api-key EXA_API_KEY]
                       [file_input] [file_output]

Converte un file XML Akoma Ntoso in formato Markdown

argomenti posizionali:
  file_input            File XML di input in formato Akoma Ntoso o URL normattiva.it
  file_output           File Markdown di output (default: stdout)

opzioni:
   -h, --help            Mostra questo messaggio di aiuto
   -v, --version         Mostra la versione del programma
   -i INPUT, --input INPUT
                         File XML di input in formato Akoma Ntoso o URL normattiva.it
   -o OUTPUT, --output OUTPUT
                         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
   -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
   --with-urls           Genera link markdown agli articoli citati su normattiva.it
   --provvedimenti       Esporta provvedimenti attuativi in CSV (richiede URL normattiva.it)
   --debug-search        Modalità debug interattiva per la ricerca (mostra tutti i risultati)
   --auto-select         Seleziona automaticamente il miglior risultato (default: True)
   --exa-api-key EXA_API_KEY
                         API key di Exa AI (alternativa a EXA_API_KEY env var)

nota: per ricerca in linguaggio naturale usare -s/--search

```

--------------------------------

### Keep Downloaded XML

Source: https://pypi.org/project/normattiva2md/2.1.5

Convert a Normattiva URL to Markdown while also preserving the downloaded XML file. Use the --keep-xml flag.

```bash
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" legge.md --keep-xml
```

--------------------------------

### Convert Article with Extension from URL

Source: https://pypi.org/project/normattiva2md/2.1.5

Convert a specific article with an extension (e.g., art. 16-bis) from a Normattiva URL to a Markdown file.

```bash
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53~art16bis" art16bis.md
```

--------------------------------

### Test Standalone Executable

Source: https://pypi.org/project/normattiva2md

Run tests using the generated standalone executable.

```bash
./dist/normattiva2md sample.xml output.md
```

--------------------------------

### Convert Specific Article from URL

Source: https://pypi.org/project/normattiva2md/2.1.5

Convert a specific article (e.g., art. 3) from a Normattiva URL to a Markdown file.

```bash
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto-legge:2018-07-12;87~art3" art3.md
```

--------------------------------

### Convert URL to Markdown (output to stdout)

Source: https://pypi.org/project/normattiva2md/2.1.5

Directly convert a Normattiva URL to Markdown and output to standard output, useful for piping to other commands.

```bash
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82"
```

--------------------------------

### Convert Local XML to Markdown (Positional Arguments)

Source: https://pypi.org/project/normattiva2md

Converts a local XML file to Markdown using positional arguments for input and output files. This is the simplest method for local files.

```bash
# Argomenti posizionali (più semplice)
normattiva2md input.xml output.md
```

--------------------------------

### Generate Markdown Links to Normattiva Articles

Source: https://pypi.org/project/normattiva2md

Converts an XML file or a Normattiva URL to Markdown, generating markdown links to cited articles on normattiva.it. This is enabled using the --with-urls flag.

```bash
# Generate markdown links to cited articles on normattiva.it
normattiva2md --with-urls input.xml output.md
normattiva2md --with-urls "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" legge_con_link.md
```

--------------------------------

### Convert Local XML to Markdown (Named Arguments)

Source: https://pypi.org/project/normattiva2md/2.1.5

Convert a local XML file to Markdown using named arguments for input and output files. Supports short (-i, -o) and long (--input, --output) flags.

```bash
normattiva2md -i input.xml -o output.md
```

```bash
normattiva2md --input input.xml --output output.md
```

--------------------------------

### Configure Exa AI API Key using environment variable (Linux/macOS)

Source: https://pypi.org/project/normattiva2md/2.1.5

Set the EXA_API_KEY environment variable directly in your terminal for natural language search. This configuration is temporary for the current session.

```bash
export EXA_API_KEY='your-exa-api-key-here'
echo $EXA_API_KEY
```

--------------------------------

### Markdown Conversion Only (No CSV)

Source: https://pypi.org/project/normattiva2md/2.1.5

Perform a standard Markdown conversion of a law URL without attempting to export implementing provisions as CSV. CSV is only generated if provisions exist.

```bash
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:1973;295" legge.md
```

--------------------------------

### Configure Exa AI API Key using environment variable (Linux/macOS)

Source: https://pypi.org/project/normattiva2md

Set the EXA_API_KEY environment variable for Exa AI integration. This method is suitable for Linux and macOS systems.

```bash
# Configura la variabile d'ambiente con la tua API key
export EXA_API_KEY='your-exa-api-key-here'

# Verifica che sia configurata
echo $EXA_API_KEY
```

--------------------------------

### Advanced Options

Source: https://pypi.org/project/normattiva2md

Explore advanced options for fine-tuning the conversion process, such as extracting specific articles, generating markdown links, and enabling quiet mode.

```APIDOC
## Advanced Options

Customize the conversion process with several advanced options.

### Options

- `article`: Specify a particular article to extract (e.g., `article="16bis"`).
- `with_urls`: Set to `True` to generate markdown links for references within the document.
- `quiet`: Set to `True` to disable logging output during conversion.

### Usage Examples

```python
# Extract a single article
result = convert_url(url, article="16bis")

# Generate markdown links for references
result = convert_url(url, with_urls=True)

# Enable quiet mode (no logging)
result = convert_url(url, quiet=True)
```
```

--------------------------------

### Export Implementing Provisions to CSV

Source: https://pypi.org/project/normattiva2md/2.1.5

Export implementing provisions for a given law URL into a CSV file. The CSV file is named based on the law's year and number.

```bash
normattiva2md --provvedimenti "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2024;207" legge.md
```

--------------------------------

### Advanced Options for URL Conversion

Source: https://pypi.org/project/normattiva2md/2.1.5

Illustrates advanced options for the `convert_url` function, including extracting a single article, generating markdown links to references, and enabling silent mode to suppress logging.

```python
# Estrai singolo articolo
result = convert_url(url, article="16bis")

# Genera link markdown ai riferimenti
result = convert_url(url, with_urls=True)

# Modalità silenziosa (no logging)
result = convert_url(url, quiet=True)


```

--------------------------------

### Generate Markdown Links to Articles

Source: https://pypi.org/project/normattiva2md/2.1.5

Converts an XML file or URL to Markdown, generating markdown links to cited articles on normattiva.it.

```bash
# Generate markdown links to articles cited on normattiva.it
normattiva2md --with-urls input.xml output.md
normattiva2md --with-urls "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" legge_con_link.md
```

--------------------------------

### Pass Exa AI API Key as CLI parameter

Source: https://pypi.org/project/normattiva2md/2.1.5

Provide the Exa AI API key directly as a command-line argument for temporary use with the natural language search feature.

```bash
normattiva2md -s "legge stanca accessibilità" --exa-api-key "your-exa-api-key" output.md
```

--------------------------------

### Filter Article to Stdout

Source: https://pypi.org/project/normattiva2md/2.1.5

Extract a single article from a local XML file and redirect the output to standard output.

```bash
normattiva2md --art 3 input.xml > articolo.md
```

--------------------------------

### Advanced Usage with Converter Class

Source: https://pypi.org/project/normattiva2md/2.1.5

Utilizes the Converter class for persistent configuration, performing search and conversion in one step, and batch processing multiple URLs. Requires an Exa API key or EXA_API_KEY environment variable.

```python
from normattiva2md import Converter

# Converter con configurazione persistente
conv = Converter(
    exa_api_key="your-key",  # o usa EXA_API_KEY da .env
    quiet=True
)

# Ricerca e conversione in un passo
result = conv.search_and_convert("decreto dignità")
result.save("decreto_dignita.md")

# Batch processing
urls = [
    "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4",
    "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82",
]
for i, url in enumerate(urls):
    result = conv.convert_url(url)
    if result:
        result.save(f"legge_{i+1}.md")


```

--------------------------------

### Force Full Conversion for Article URL

Source: https://pypi.org/project/normattiva2md

Forces a complete conversion of the document even when a specific article URL is provided. This ensures the entire law is converted, not just the specified article.

```bash
# Forza conversione completa anche con URL articolo-specifico
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto-legge:2018-07-12;87~art3" legge_completa.md
normattiva2md -c "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53~art16bis" legge_completa.md
```

--------------------------------

### Natural Language Search with Exa AI

Source: https://pypi.org/project/normattiva2md/2.1.5

Perform natural language searches using Exa AI. Always use the -s or --search flag. You can optionally provide your Exa API key. Results can be output to a file or stdout.

```bash
# Automatic search (automatically selects the best result)
normattiva2md -s "legge stanca accessibilità" output.md
normattiva2md --search "decreto dignità" --exa-api-key "your-key" > decreto.md

# Output to stdout
normattiva2md -s "codice della strada"
normattiva2md -s "legge stanca accessibilità" --exa-api-key "your-key" > legge_stanca.md
```

--------------------------------

### Combine --art with --with-urls

Source: https://pypi.org/project/normattiva2md

Combines the --art flag for filtering a specific article with the --with-urls flag to automatically generate links within the output.

```bash
# Combinare con --with-urls per link automatici
normattiva2md --art 4 --with-urls input.xml output.md
```

--------------------------------

### Export Implementing Provisions to CSV

Source: https://pypi.org/project/normattiva2md/2.1.5

Exports implementing provisions for a given law to a CSV file, in addition to the main Markdown output file.

```bash
# Export implementing provisions to CSV
normattiva2md --provvedimenti "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2024;207" legge.md
# Generates: legge.md + 2024_207_provvedimenti.csv
```

--------------------------------

### Natural Language Search with Exa AI

Source: https://pypi.org/project/normattiva2md

Perform natural language searches using Exa AI. Always use the -s or --search flag. The --auto-select flag can be used to avoid interactive prompts and use the first suggested result. You can also provide your Exa API key directly using --exa-api-key.

```bash
# Automatic search (automatically selects the best result)
# Use --auto-select to avoid interactive prompts and use the first suggested result.
normattiva2md -s "legge stanca accessibilità" output.md
normattiva2md -s "codice amministrazione digitale" --auto-select > cad.md
normattiva2md --search "decreto dignità" --exa-api-key "your-key" > decreto.md

# Output to stdout
normattiva2md -s "codice della strada"
normattiva2md -s "legge stanca accessibilità" --exa-api-key "your-key" > legge_stanca.md
```

--------------------------------

### Convert Article with Extension (e.g., Art. 16-bis)

Source: https://pypi.org/project/normattiva2md

Converts a specific article that includes an extension in its numbering, like '16bis'.

```bash
# Conversione articolo con estensione (art. 16-bis)
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53~art16bis" art16bis.md
```

--------------------------------

### Force OpenData Download

Source: https://pypi.org/project/normattiva2md

Forces the download via OpenData when the Akoma export is missing. Useful for URLs that might not have direct Akoma export available.

```bash
# 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
```

--------------------------------

### Error Handling with Normattiva2md

Source: https://pypi.org/project/normattiva2md/2.1.5

Shows how to handle potential errors during URL conversion, including invalid URLs, conversion failures, and API key issues. Also demonstrates soft error handling where functions return None for non-critical issues.

```python
from normattiva2md import (
    convert_url,
    InvalidURLError,
    ConversionError,
    APIKeyError,
    Normattiva2MDError,
)

try:
    result = convert_url("https://www.normattiva.it/...")
except InvalidURLError as e:
    print(f"URL non valido: {e}")
except ConversionError as e:
    print(f"Errore conversione: {e}")
except Normattiva2MDError as e:
    print(f"Errore: {e}")

# Gestione errori soft (ritornano None)
result = convert_url(url, article="999")
if result is None:
    print("Articolo non trovato")


```

--------------------------------

### Direct Conversion with stdout Output

Source: https://pypi.org/project/normattiva2md

Performs a direct conversion with the output sent to standard output, which is useful for piping the result to other commands.

```bash
# 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"
```

--------------------------------

### Preserve Downloaded XML

Source: https://pypi.org/project/normattiva2md

Converts a Normattiva URL to Markdown while also keeping the original downloaded XML file. Useful for archival or further processing.

```bash
# Conservare l'XML scaricato
normattiva2md "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" legge.md --keep-xml
```

--------------------------------

### Basic normattiva2md usage

Source: https://pypi.org/project/normattiva2md/2.1.5

Perform a basic conversion from an XML input file to a Markdown output file.

```bash
normattiva2md input.xml output.md
```

--------------------------------

### Error Handling

Source: https://pypi.org/project/normattiva2md

Details how to handle potential errors during URL validation, conversion, and API key issues using specific exceptions.

```APIDOC
## Error Handling

Proper error handling is crucial for robust applications. The library provides specific exceptions for different error scenarios.

### Exceptions

- `InvalidURLError`: Raised for invalid URL formats.
- `ConversionError`: Raised during the document conversion process.
- `APIKeyError`: Raised if the Exa API key is missing or invalid.
- `Normattiva2MDError`: A base exception for other library-specific errors.

### Usage Examples

```python
from normattiva2md import (
    convert_url,
    InvalidURLError,
    ConversionError,
    APIKeyError,
    Normattiva2MDError,
)

try:
    result = convert_url("https://www.normattiva.it/...")
except InvalidURLError as e:
    print(f"Invalid URL: {e}")
except ConversionError as e:
    print(f"Conversion error: {e}")
except Normattiva2MDError as e:
    print(f"Error: {e}")

# Handling soft errors (return None)
result = convert_url(url, article="999")
if result is None:
    print("Article not found")
```
```

--------------------------------

### Filter Article with Automatic URLs

Source: https://pypi.org/project/normattiva2md/2.1.5

Combine the --art flag with --with-urls to automatically generate links within the extracted article.

```bash
normattiva2md --art 4 --with-urls input.xml output.md
```

--------------------------------

### Convert Local XML File

Source: https://pypi.org/project/normattiva2md/2.1.5

Converts a local XML file to a Markdown file. This is a basic file conversion operation.

```bash
# Convert a local XML file
normattiva2md decreto_82_2005.xml codice_amministrazione_digitale.md
```

--------------------------------

### Filter Single Article from URL

Source: https://pypi.org/project/normattiva2md/2.1.5

Extract a single article from a Normattiva URL using the --art flag. This is simpler than constructing URLs with '~artN'.

```bash
normattiva2md --art 16bis "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2022;53" art16bis.md
```

--------------------------------

### Interactive Debug Search Mode

Source: https://pypi.org/project/normattiva2md

Enables interactive debugging for natural language searches. This mode displays all found results, allowing manual selection. It also prompts for download confirmation and suggests a filename based on the document title.

```bash
# Interactive debug mode (--debug-search)
# Allows you to see all results and choose manually
normattiva2md -s "legge stanca accessibilità" --debug-search
```

```bash
$ normattiva2md -s "legge stanca accessibilità" --debug-search

🔍 Risultati trovati per: legge stanca
Seleziona il numero del risultato desiderato (1-5), o 0 per annullare:
  [1] DECRETO-LEGGE 7 giugno 2024, n. 73...
      URL: https://www.normattiva.it/...
      Preferenza: -30

  [2] LEGGE 24 maggio 1970, n. 336...
      URL: https://www.normattiva.it/uri-res/N2Ls?...
      Preferenza: 24

  [3] LEGGE 9 gennaio 2004, n. 4...
      URL: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig
      Preferenza: 24

Scelta: 3
✅ URL selezionato manualmente: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig

📥 Vuoi scaricare questo documento? (s/N): s
📝 Nome file [legge_9_gennaio_2004_n_4.md]:
✅ URL selezionato: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig
Rilevato URL normattiva.it: https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4!vig
... 
✅ Conversione completata: legge_9_gennaio_2004_n_4.md
```

--------------------------------

### Filter Article with Priority over URL

Source: https://pypi.org/project/normattiva2md/2.1.5

Demonstrates that the --art flag takes precedence over '~artN' specified in the URL when filtering articles.

```bash
normattiva2md --art 3 "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82~art5" art3.md
```

--------------------------------

### Interactive Debug Search Mode

Source: https://pypi.org/project/normattiva2md/2.1.5

Enables interactive debug search mode (--debug-search) which displays all found results, allowing manual selection. This mode also prompts for download confirmation and suggests a filename based on the result's title.

```bash
# Interactive debug mode
normattiva2md -s "legge stanca accessibilità" --debug-search
```

--------------------------------

### Returned Objects

Source: https://pypi.org/project/normattiva2md

Information about the objects returned by the library functions, detailing their attributes and helper methods.

```APIDOC
## Returned Objects

The library returns specific objects that encapsulate conversion and search results.

### `ConversionResult` Object

Contains the following attributes and helpers:
- `markdown`: The converted document in Markdown format.
- `metadata`: Metadata associated with the document.
- `url`: The original URL of the document.
- `url_xml`: The URL of the XML source.
- `title`: The title of the document.
- `data_gu`: The publication date in the Official Gazette.
- `save(file_path)`: A helper method to save the converted Markdown to a file.

### `SearchResult` Object

Contains the following attributes for search results:
- `url`: The URL of the found law.
- `title`: The title of the found law.
- `score`: A relevance score for the search result.
```

--------------------------------

### Filter Single Article from Local XML

Source: https://pypi.org/project/normattiva2md

Filters and converts a single article from a local XML file using the --art flag. The article number is specified directly.

```bash
# Filtrare articolo da file XML locale
normattiva2md --art 4 input.xml output.md
normattiva2md --art 3bis input.xml articolo.md
```

--------------------------------

### Normattiva2md Search Mode - Interactive Debug

Source: https://pypi.org/project/normattiva2md/2.1.5

Uses the -s or --search option along with --debug-search to enable interactive selection and download of search results.

```bash
normattiva2md -s "query" --debug-search
```

--------------------------------

### Advanced Usage: Converter Class

Source: https://pypi.org/project/normattiva2md

Utilize the `Converter` class for persistent configurations and advanced batch processing of legal document conversions.

```APIDOC
## Advanced Usage: Converter Class

The `Converter` class allows for persistent configurations and more complex workflows.

### Initialization

- `Converter(exa_api_key=None, quiet=False)`: Initializes the converter. `exa_api_key` can be provided directly or via the `EXA_API_KEY` environment variable. `quiet` suppresses logging.

### Methods

- `search_and_convert(query)`: Performs a search and converts the result in a single step.
- `convert_url(url)`: Converts a document from a URL using the converter's configuration.

### Usage Examples

```python
from normattiva2md import Converter

# Initialize Converter with API key
conv = Converter(exa_api_key="your-key", quiet=True)

# Search and convert in one step
result = conv.search_and_convert("decreto dignità")
result.save("decreto_dignita.md")

# Batch processing of URLs
urls = [
    "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:legge:2004-01-09;4",
    "https://www.normattiva.it/uri-res/N2Ls?urn:nir:stato:decreto.legislativo:2005-03-07;82",
]
for i, url in enumerate(urls):
    result = conv.convert_url(url)
    if result:
        result.save(f"legge_{i+1}.md")
```
```

--------------------------------

### Filter Single Article from Local XML

Source: https://pypi.org/project/normattiva2md/2.1.5

Extract a single article from a local XML file using the --art flag. Supports numeric and alphanumeric article identifiers.

```bash
normattiva2md --art 4 input.xml output.md
```

```bash
normattiva2md --art 3bis input.xml articolo.md
```

--------------------------------

### Normattiva2md Search Mode - Automatic

Source: https://pypi.org/project/normattiva2md/2.1.5

Uses the -s or --search option with a query to automatically select the best search result.

```bash
normattiva2md -s "query"
```

--------------------------------

### Output Filtered Article to stdout

Source: https://pypi.org/project/normattiva2md

Outputs the content of a filtered article directly to standard output using redirection. Useful for piping the article content to other processes.

```bash
# Output su stdout
normattiva2md --art 3 input.xml > articolo.md
```
Tokens:
Raw