utilities/README.md

Fix Gaia Excel - Script Python

Script per processare file Excel contenenti dati di titoli e qualifiche.

Lo script cerca la colonna "Titoli - Operativita - Data ottenimento - Data scadenza", estrae le qualifiche e le date, e aggiunge due nuove colonne al file Excel con dati puliti e normalizzati.

Autore: Luigi D'Acunto
Data: 25 novembre 2025

Requisiti

• Python 3.6 o superiore
• pip (gestore pacchetti Python)

Installazione

1. Creare l'ambiente virtuale

# Crea l'ambiente virtuale nella cartella venv
python -m venv venv

2. Attivare l'ambiente virtuale

Su Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Su Windows (CMD):

.\venv\Scripts\activate.bat

Su Linux/macOS:

source venv/bin/activate

Nota: Se ricevi un errore di policy su PowerShell, esegui:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. Installare le dipendenze

pip install -r requirements.txt

Se il file requirements.txt non esiste, installa manualmente:

pip install openpyxl

4. Generare il file requirements.txt (opzionale)

Se vuoi aggiornare il file delle dipendenze:

pip freeze > requirements.txt

Utilizzo

Eseguire lo script

IMPORTANTE: Lo script deve essere eseguito con python esplicitamente, non direttamente come .\fixgaiaexcel.py:

python fixgaiaexcel.py <percorso_file_excel> [opzioni]

Opzioni disponibili

Modalità data più vecchia (default)

python fixgaiaexcel.py "data\report.xlsx"

Modalità data più recente

python fixgaiaexcel.py "data\report.xlsx" --data-recente

oppure (forma breve):

python fixgaiaexcel.py "data\report.xlsx" --recente

Visualizzare l'help completo

python fixgaiaexcel.py --help

Cosa fa lo script

1. Apre il file Excel specificato
2. Cerca la colonna "Titoli - Operativita - Data ottenimento - Data scadenza"
3. Per ogni riga con dati:
   • Estrae la qualifica (testo senza date dalla prima riga della cella)
   • Estrae tutte le date in formato aaaa-mm-gg
   • Seleziona la data più vecchia (o più recente se specificato)
4. Aggiunge due nuove colonne:
   • "Qualifica": testo pulito della qualifica
   • "Data": data selezionata secondo il criterio
5. Salva un nuovo file con suffisso "_modificato"

File di output

Il file originale non viene modificato.
Viene creato un nuovo file: nomefile_modificato.xlsx

Esempio:

• Input: data\Elenco_Soci_BLSD.xlsx
• Output: data\Elenco_Soci_BLSD_modificato.xlsx

Reinstallazione su nuovo PC

Passaggi completi

1. Clona o copia il progetto sul nuovo PC

2. Verifica che Python sia installato:

   python --version
   

   Se Python non è installato, scaricalo da python.org

3. Crea l'ambiente virtuale:

   python -m venv venv
   

4. Attiva l'ambiente virtuale:

   .\venv\Scripts\Activate.ps1
   

5. Installa le dipendenze:

   pip install -r requirements.txt
   

6. Verifica l'installazione:

   pip list
   

   Dovresti vedere openpyxl nella lista dei pacchetti installati.

7. Testa lo script:

   python fixgaiaexcel.py --help
   

Struttura del progetto

Troubleshooting

Errore: "ModuleNotFoundError: No module named 'openpyxl'"

Causa: Lo script viene eseguito con il Python di sistema invece che con quello del venv.

Soluzione: Usa sempre python esplicitamente:

# ✓ CORRETTO
python fixgaiaexcel.py file.xlsx

# ✗ SBAGLIATO (usa l'interprete di sistema)
.\fixgaiaexcel.py file.xlsx

Verifica che il venv sia attivo (dovresti vedere (venv) nel prompt):

# Se non è attivo, attivalo
.\venv\Scripts\Activate.ps1

Errore: "Il file non esiste"

Verifica che il percorso del file Excel sia corretto e che il file esista.

Errore: "Colonna non trovata"

Lo script cerca l'intestazione nella prima riga. Verifica che il file Excel contenga la colonna "Titoli - Operativita - Data ottenimento - Data scadenza" nella prima riga.

Errore di policy PowerShell

Se ricevi un errore durante l'attivazione del venv:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
## Note

- **Esecuzione dello script:** Usa sempre `python fixgaiaexcel.py` invece di `.\fixgaiaexcel.py` per assicurarti di usare l'interprete Python del venv.

- L'ambiente virtuale (`venv/`) non dovrebbe essere committato in git. È già escluso dal `.gitignore`.

- Il file `requirements.txt` è committato per facilitare l'installazione su altri PC.

- I file Excel in `data/` sono esclusi dal git per proteggere dati sensibili.

## Esempi completi

### Workflow tipico

```powershell
# 1. Attiva l'ambiente virtuale
.\venv\Scripts\Activate.ps1

# 2. Processa un file (data più vecchia)
python fixgaiaexcel.py ".\data\Elenco_Soci_BLSD.xlsx"

# 3. Processa un file (data più recente)
python fixgaiaexcel.py ".\data\Elenco_Soci_OPEM.xlsx" --data-recente

# 4. Visualizza l'help
python fixgaiaexcel.py --help

# 5. Quando hai finito
deactivate

Disattivare l'ambiente virtuale

Quando hai finito di lavorare:

deactivate

Note

• L'ambiente virtuale (venv/) non dovrebbe essere committato in git. Aggiungi al .gitignore:

  venv/
  __pycache__/
  *.pyc
  

• Il file requirements.txt dovrebbe essere committato per facilitare l'installazione su altri PC.