Metadata-Version: 2.1
Name: comuniitaliani
Version: 0.22.1
Summary: Libreria Python per ottenere informazioni sui comuni italiani con dati ISTAT e CAP
Home-page: https://github.com/cvrboni/comuniitaliani
Author: Andrea Carboni
Author-email: andreacarboni@stepservizi.net
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests >=2.0.0

# Comuni Italiani

Libreria Python per cercare informazioni sui comuni italiani usando i dati ISTAT, con arricchimento automatico dei CAP tramite il dataset di Garda Informatica.

## Caratteristiche

- Ricerca di un comune per nome, case-insensitive e robusta agli accenti
- Ricerca per codice catastale
- Elenco dei comuni per provincia
- Ricerca inversa per `CAP`
- Download automatico e aggiornamento del dataset ISTAT
- Download automatico dell'ultimo dataset CAP disponibile da Garda Informatica

## Installazione

```bash
pip install comuniitaliani
```

## Utilizzo

```python
from comuniitaliani import Comuni

comuni = Comuni()
```

### Cercare un comune per nome

```python
info = comuni.cerca_comune("Agliè")
print(info)
```

Output di esempio:

```json
{
  "nome": "Agliè",
  "provincia": "Torino",
  "sigla_provincia": "TO",
  "regione": "Piemonte",
  "codice_catastale": "A074",
  "cap": ["10080"]
}
```

### Cercare un comune per codice catastale

```python
info = comuni.cerca_per_codice_catastale("A074")
print(info)
```

### Elencare i comuni di una provincia

```python
torino = comuni.comuni_per_provincia("TO")
print(torino[:3])
```

### Cercare i comuni associati a un CAP

```python
risultati = comuni.cerca_per_cap("10080")
print(risultati)
```

Output di esempio:

```json
[
  {
    "nome": "Agliè",
    "provincia": "Torino",
    "sigla_provincia": "TO",
    "regione": "Piemonte",
    "codice_catastale": "A074",
    "cap": ["10080"]
  }
]
```

## Note sui CAP

Il campo `cap` viene restituito sempre come lista:

- un comune può avere più CAP
- uno stesso CAP può essere associato a più comuni

Per questo `cerca_per_cap()` restituisce una lista di comuni.

L'associazione dei `CAP` privilegia chiavi affidabili nell'ordine:

- codice ISTAT alfanumerico
- codice ISTAT numerico
- codice catastale
- nome comune + sigla provincia

Non viene usato il solo nome comune, per evitare match ambigui.

## Aggiornamento automatico dei dati

Per default la libreria:

- verifica se il CSV ISTAT locale è aggiornato
- include nel pacchetto uno snapshot locale del dataset CAP, utile anche offline
- risolve l'ultimo ZIP disponibile dalla pagina di Garda Informatica
- scarica il dataset CAP solo se la versione remota è cambiata

Se vuoi lavorare solo con file già presenti in locale:

```python
comuni = Comuni(allow_download=False)
```

Se vuoi disabilitare completamente il layer `CAP`:

```python
comuni = Comuni(load_cap=False)
```

Se vuoi indicare esplicitamente un file CAP locale:

```python
comuni = Comuni(cap_csv_file="/percorso/garda_cap.csv", allow_download=False)
```

## Fonti dati

- ISTAT per anagrafica comuni
- Garda Informatica per l'associazione CAP

## Compatibilita API

Dalla versione `0.22.1` le funzioni che restituiscono dati di comune includono anche il campo `cap`.
Il campo e sempre una lista, anche quando esiste un solo CAP.

## Sviluppo

Installazione dipendenze di sviluppo:

```bash
pip install -e . -r requirements-dev.txt
```

Esecuzione test:

```bash
pytest
```

## Licenza

Il progetto è distribuito con licenza MIT. Vedi [LICENSE](./LICENSE).

## Link utili

- [Repository GitHub](https://github.com/cvrboni/comuniitaliani)
- [PyPI Package](https://pypi.org/project/comuniitaliani)
- [Dataset ISTAT](https://www.istat.it/it/archivio/6789)
- [Dataset Garda Informatica](https://www.gardainformatica.it/database-comuni-italiani)
