README.md

Django Comuni Italiani

Applicazione Django per gestire comuni, province e regioni

---

Questa applicazione django contiene lo stretto necessario per gestire le entità topografiche italiane (regioni, province, città metropolitane, comuni) importate dai dati pubblici dell'istat reperibili al link http://www.istat.it/it/archivio/6789

---

Requisiti e installazione

I requiti sono i seguenti:

• Python 3+
• Django 1.7+

Per l'installazione potete utilizzare pip:

pip install django-comuni-italiani

Oppure prendere l'ultima versione da github https://github.com/kbytesys/django_comuni_italiani ed eseguire il classico:

./setup.py install

Nella configurazione di django aggiungi l'applicazione dove ti è più conveniente:

INSTALLED_APPS = (
    ...
    'comuni_italiani',
    ...
)

L'app dispone di alcune viste per chiamate ajax e alto, dovrete dunque aggiungere gli url a quelli del vostro progetto:

urlpatterns = [
    ...
    url(r'^comuni_italiani/', include('comuni_italiani.urls', namespace='comuni_italiani')),
    ...
]

In Django 2:

from django.urls import path, include

urlpatterns = [
    ...
    path('comuni_italiani/', include('comuni_italiani.urls', namespace='comuni_italiani')),
    ...
]

Un dump dei dati più aggiornati al momento del rilascio è distribuito sotto forma di fixture. Esso può essere caricato con il seguente comando:

./manage.py loaddata --app comuni_italiani comuni_italiani.json

Chiamate ajax/json

L'app vi fornisce alcune chiamate per l'elenco e la ricerca delle diverse entità attraverso json/ajax.

Troverete la documentazione completa nel wiki.

Supporto django-autocomplete-light

Se utilizzate django-autocomplete-light potete facilmente aggiungere le definizioni per il completamento automatico aggiungendo la seguente app tra quelle installate:

INSTALLED_APPS = (
    ...
    'comuni_italiani',
    'comuni_italiani.autocomplete',
    ...
)

Ovviamente dovete aver aggiunto autocomplete light seguendo la documentazione che troverete qui.

Gli URL a disposizione per l'autocompletamento sono i seguenti:

• regione-autocomplete
• provincia-autocomplete
• cittametropolitana-autocomplete
• comune-autocomplete

Supportano il forward (filtro selezionando oggetto padre, es. regione => provincia) tutti tranne regione-autocomplete.

Un esempio

Model con ForeignKey ad un comune e un form con django-autocomplete-light:

# models.py

class Anagrafica(models.Model):
    nome = models.CharField(max_length=32)
    email = models.EmailField()
    citta = models.ForeignKey(
        'comuni_italiani.Comune', on_delete=models.PROTECT
    )

# urls.py

from django.urls import path, include

urlpatterns = [
	# i tuoi url, es. admin
	path('admin/', admin.site.urls),
	# includi gli URLs per l'autocompletamento
	path('ac/comuni/', include('comuni_italiani.autocomplete.urls')),
]

# forms.py

from dal import autocomplete
from django import forms
from . import models


class AnagraficaForm(forms.ModelForm):

    class Meta:
        model = models.Anagrafica
        fields = ('__all__')
        widgets = {
            'comune': autocomplete.ModelSelect2Multiple(
                url='comune-autocomplete'
            )
        }

Potete verificarne il funzionamento nell'admin:

# admin.py

from django.contrib import admin
from . import models
from . import forms


@admin.register(models.Anagrafica)
class AnagraficaAdmin(admin.ModelAdmin):
    form = forms.AnagraficaForm

Aggiornamento dei dati

Purtroppo l'aggiornamento dei dati non è un'operazione semplice, soprattutto perché i tuoi dati contenuti nelle applicazioni che svilupperai potrebbero essere legati a dati soggetti a cambiamenti (hanno abrogato una provincia? maledetti!)

./manage.py import_regioni_prov
./manage.py import_comuni

Entrambi i comandi possono accettare i file csv aggiornati presi dal sito dell'istat. Tuttavia se la loro struttura (o anche semplicemente il nome della colonna) cambia, l'importazione potrebbe fallire.

Per l'aggiornamento delle province e regioni attualmente non viene eseguito alcun particolare controllo nel caso di rimozione, in quanto è un'operazione delicata che deve essere gestita manualmente in base alle vostre basi dati.

L'aggiornamento dei comuni è più intelligente.

• Durante l'aggiornamento se viene rilevato un comune con lo stesso codice istat, ma con diverso nome, verrà richiesto di confermare l'aggiornamento o saltare il record. Ciò evita probabili inconvenienti durante le (rare) rinumerazioni dei comuni in una provincia.

• Al termine dell'aggiornamento vengono elencati i comuni presenti del db, ma assenti nel csv. Ciò vi aiuterà a rilevare i comuni eliminati/abrogati/accorpati

• Al termine dell'aggiornamento verranno elencati i comuni omonimi. Attualmente sono presenti 8 nomi di comune uguali per un totale di 16 comuni

In ogni caso sarà vostro compito fare i dovuti aggiustamenti.

FAQ

A quando risale l'ultimo aggiornamento dei dati?
L'applicazione ha già inclusi i dati istat aggiornati al 30 gennaio 2015

Perchè documentazione e codice sorgente sono in Italiano?
Questa appliazione ha uno scopo intimamente riservato al "mercato" italiano. In genere se si ha la necessità di utilizzare luoghi e lingue diverse consiglio l'uso di django-cities-light oppure di django-cities

Posso aggiornare i comuni eliminandoli e reimportando i dati da zero?
Assumento che tu possa farlo sbloccando temporaneamente le foreign keys, non è una buona idea. Mentre province e regioni hanno sempre lo stesso codice istat, il codice istat di un comune può cambiare. Per questo motivo i comuni hanno una chiave numerica autogenerata che potrebbe non essere coerente tra un'importazione e l'altra.

Nei nuovi dati non trovo più la superfice e l'altitudine dei comuni!
Nei dati del 2016 l'Istat ha deciso di non includere quelle informazioni nelle loro esportazioni.

TODO

• Form temizzabili per selezionare una provincia da regione e un comune da provincia (se si usa django-autocomplete-light non c'è bisogno).