Modulo Utils

Il modulo Utils raccoglie una serie di funzioni di utilità per la gestione e la conversione di file, la creazione di directory e l'estrazione di contenuti da archivi compressi. Queste funzioni sono fondamentali per supportare i processi di gestione dei dati censuari e geografici.

census_folder(output_data_folder, year)

Crea una cartella per i dati e geodati del censimento dell'anno selezionato.

La funzione crea una cartella specifica per il censimento relativo all'anno indicato all'interno della directory specificata. Se la cartella esiste già, non verrà creata nuovamente, grazie al parametro exist_ok=True.

PARAMETER	DESCRIPTION
output_data_folder	Il percorso della cartella principale in cui creare la cartella del censimento. TYPE: Path
year	L'anno del censimento. Il valore predefinito è il 2011. TYPE: int

RETURNS	DESCRIPTION
Path	Il percorso della cartella creata o esistente. TYPE: Path

RAISES	DESCRIPTION
Exception	In caso di problemi con la creazione della cartella.

check_encoding(data)

Determina la codifica di un file.

Questa funzione apre il file specificato, legge i primi 100.000 byte e tenta di determinare la codifica utilizzando la libreria chardet. Se la codifica rilevata è 'ascii', viene convertita in 'latin1' per evitare problemi di compatibilità con file testuali.

PARAMETER	DESCRIPTION
data	Il percorso del file di cui si vuole determinare la codifica. TYPE: Path

RETURNS	DESCRIPTION
str	La codifica rilevata del file. Se 'ascii' viene rilevato, restituisce 'latin1'. TYPE: str

csv_from_excel(data, output_path, metadata=False)

Converte un file Excel (.xls) in CSV.

La funzione legge un file Excel e converte i dati presenti in un foglio specificato in formato CSV. Se metadata=True, converte il foglio chiamato "Metadati", altrimenti converte il primo foglio disponibile, escluso "Metadati" se esistente.

PARAMETER	DESCRIPTION
data	Il percorso del file Excel da convertire. TYPE: Path
output_path	Il percorso dove salvare il file CSV generato. TYPE: Path
metadata	Se True, converte il foglio "Metadati", altrimenti converte il primo foglio escluso "Metadati" (default: False). TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Path	Il percorso del file CSV creato. TYPE: Path

RAISES	DESCRIPTION
FileNotFoundError	Se il file Excel specificato non viene trovato.
XLRDError	Se non è possibile leggere il file Excel.
Exception	Per eventuali altri errori durante la conversione.

get_census_dictionary(census_year, region_list=[])

Genera i link per il download dei dati censuari, geodati e confini amministrativi in base all'anno del censimento fornito.

PARAMETER	DESCRIPTION
census_year	L'anno del censimento per cui generare i link. TYPE: int

RETURNS	DESCRIPTION
dict	Un dizionario contenente i link per il download dei dati, TYPE: dict
dict	geodati e confini amministrativi.

RAISES	DESCRIPTION
ValueError	Se l'anno del censimento non è supportato.

unzip_data(input_data, output_folder)

Decomprime un file ZIP nella cartella di destinazione specificata.

La funzione apre un file ZIP e ne estrae tutto il contenuto nella cartella specificata. Se la cartella di destinazione non esiste, viene creata automaticamente.

PARAMETER	DESCRIPTION
input_data	Il percorso del file ZIP da decomprimere. TYPE: Path
output_folder	Il percorso della cartella dove estrarre i file. TYPE: Path

RETURNS	DESCRIPTION
Path	Il percorso della cartella in cui sono stati estratti i file. TYPE: Path

RAISES	DESCRIPTION
FileNotFoundError	Se il file ZIP non viene trovato.
BadZipFile	Se il file fornito non è un file ZIP valido.
Exception	Per eventuali errori generici durante la decompressione.

census_trace(file_path, year, output_path=None)

Estrae i metadati da un file Excel e restituisce un DataFrame o salva i dati in CSV.

Questa funzione legge il foglio "Metadati" da un file Excel, estrae i dati pertinenti e restituisce un DataFrame pandas. Se viene fornito un percorso di output, i dati vengono anche salvati in un file CSV.

PARAMETER	DESCRIPTION
file_path	Il percorso del file Excel da leggere. TYPE: Path
output_path	Il percorso in cui salvare il file CSV. Se None, la funzione restituisce il DataFrame (default: None). TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
Path	Il percorso del file CSV salvato, o il DataFrame pandas se output_path è None. TYPE: Path

RAISES	DESCRIPTION
FileNotFoundError	Se il file Excel non viene trovato.
XLRDError	Se si verifica un errore durante la lettura del file Excel.
Exception	Per altri errori durante il processo di lettura o salvataggio.

read_xls(file_path, census_code, output_path=None)

Legge un file Excel (.xls) e restituisce un DataFrame pandas o salva i dati in CSV.

La funzione legge i dati da un file Excel e restituisce un DataFrame pandas contenente i dati. Se viene fornito un percorso di output, i dati vengono salvati anche in un file CSV.

PARAMETER	DESCRIPTION
file_path	Il percorso del file Excel da leggere. TYPE: Path
output_path	Il percorso in cui salvare il file CSV. Se None, la funzione restituisce il DataFrame (default: None). TYPE: Path DEFAULT: None

RETURNS	DESCRIPTION
Union[DataFrame, Path]	Union[pd.DataFrame, Path]: Un DataFrame pandas contenente i dati letti, o il percorso del file CSV salvato.

RAISES	DESCRIPTION
FileNotFoundError	Se il file Excel non viene trovato.
XLRDError	Se si verifica un errore durante la lettura del file Excel.
Exception	Per altri errori durante il processo di lettura o salvataggio.

read_xlsx(file_path, output_path=None)

Legge un file Excel (formato .xlsx) e lo converte in un DataFrame Pandas. Se specificato, salva i dati in formato CSV.

PARAMETER	DESCRIPTION
file_path	Il percorso del file Excel da leggere. TYPE: Path
output_path	Il percorso in cui salvare il file CSV generato. Se non viene specificato, restituisce il DataFrame. TYPE: (Path, opzionale) DEFAULT: None

RETURNS	DESCRIPTION
Union[DataFrame, Path]	Union[pd.DataFrame, Path]: Restituisce un DataFrame se output_path è None,
Union[DataFrame, Path]	altrimenti restituisce il percorso del file CSV salvato.

RAISES	DESCRIPTION
FileNotFoundError	Se il file Excel specificato non viene trovato.
ValueError	Se il file Excel non può essere letto correttamente.