# Guida Pratica: Uso dei Submodules Git nei Progetti Python

## Panoramica

Questa guida spiega come utilizzare i moduli riutilizzabili (`python-resource-monitor` e `python-tkinter-logger`) nei tuoi progetti Python attraverso Git submodules.

## 📚 Indice

1. [Aggiungere Submodules a un Nuovo Progetto](#aggiungere-submodules)
2. [Setup del Progetto per Usare i Submodules](#setup-progetto)
3. [Workflow Quotidiano](#workflow-quotidiano)
4. [Aggiornare i Submodules](#aggiornare-submodules)
5. [Clonare un Progetto con Submodules](#clonare-progetto)
6. [Contribuire ai Moduli Condivisi](#contribuire)
7. [Troubleshooting](#troubleshooting)

---

## 1. Aggiungere Submodules a un Nuovo Progetto {#aggiungere-submodules}

### Opzione A: Usando GitUtility Tool (Raccomandato)

1. Apri **GitUtility**
2. Carica il profilo del tuo progetto
3. Vai al tab **"Submodules"**
4. Click su **"Add Submodule"**
5. Inserisci i dettagli:
   ```
   URL: http://your-gitea.com/youruser/python-resource-monitor.git
   Local Path: external/python-resource-monitor
   Branch: master
   ```
6. Ripeti per `python-tkinter-logger` se necessario
7. Il tool automaticamente:
   - Aggiunge il submodule
   - Crea il commit
   - Configura il tracking del branch

### Opzione B: Usando Git Manualmente

```powershell
# Vai nella root del tuo progetto
cd C:\src\YourProject\

# Crea la cartella external se non esiste
mkdir external -ErrorAction SilentlyContinue

# Aggiungi i submodules
git submodule add -b master http://your-gitea.com/you/python-resource-monitor.git external/python-resource-monitor
git submodule add -b master http://your-gitea.com/you/python-tkinter-logger.git external/python-tkinter-logger

# Commit delle modifiche
git add .gitmodules external/
git commit -m "Feat: Add reusable Python modules as submodules"
```

---

## 2. Setup del Progetto per Usare i Submodules {#setup-progetto}

### Passo 1: Creare il File `_setup_paths.py`

Nel package principale del tuo progetto (es. `your_app/_setup_paths.py`):

```python
"""
Setup Python paths for external submodules.

This module ensures that external submodules are added to sys.path
before any other imports. It should be imported at the very beginning
of __init__.py.
"""
import sys
import os


def setup_external_paths():
    """Add external submodules to Python path if they exist."""
    # Get the project root (parent of your_app/)
    current_file = os.path.abspath(__file__)
    your_app_dir = os.path.dirname(current_file)
    project_root = os.path.dirname(your_app_dir)
    
    # Add external submodules
    external_base = os.path.join(project_root, "external")
    external_modules = [
        os.path.join(external_base, "python-resource-monitor"),
        os.path.join(external_base, "python-tkinter-logger"),
    ]
    
    for module_path in external_modules:
        if os.path.isdir(module_path) and module_path not in sys.path:
            sys.path.insert(0, module_path)


# Auto-execute when imported
setup_external_paths()
```

### Passo 2: Importare nel `__init__.py`

Nel file `your_app/__init__.py`:

```python
"""Your Application Package."""

# Setup external submodule paths before any other imports
from . import _setup_paths

# Resto delle tue importazioni...
```

### Passo 3: Usare i Moduli nel Codice

Ora puoi importare direttamente dai submodules:

```python
# In any file in your project
from resource_monitor import TkinterResourceMonitor, ResourceMonitor
from tkinter_logger import TkinterLogger, get_logger

# Use them
class MyApp:
    def __init__(self, root):
        self.logger = TkinterLogger(root)
        self.monitor = TkinterResourceMonitor(root, update_interval_ms=1000)
```

### Passo 4: Setup nei Test

Per i test, aggiungi il path setup all'inizio dei file di test:

```python
# tests/test_my_feature.py
import sys
import os

# Add external modules to path for tests
external_base = os.path.join(os.path.dirname(os.path.dirname(__file__)), "external")
for module in ["python-resource-monitor", "python-tkinter-logger"]:
    module_path = os.path.join(external_base, module)
    if os.path.isdir(module_path) and module_path not in sys.path:
        sys.path.insert(0, module_path)

# Now you can import
from resource_monitor import ResourceMonitor
from tkinter_logger import TkinterLogger
```

---

## 3. Workflow Quotidiano {#workflow-quotidiano}

### Sviluppo Normale

Durante lo sviluppo normale, **non devi fare nulla di speciale** con i submodules. Lavorano come normali cartelle:

```powershell
# Sviluppo normale
cd C:\src\YourProject\
python -m your_app  # Funziona normalmente

# Commit delle tue modifiche (NON dei submodules)
git add your_app/
git commit -m "Feat: Add new feature"
git push
```

### Quando Modifichi un Submodule

Se devi modificare `resource_monitor.py` o `tkinter_logger.py`:

1. **Entra nel submodule**:
   ```powershell
   cd external/python-resource-monitor
   ```

2. **Lavora normalmente**:
   ```powershell
   # Modifica i file
   code resource_monitor.py
   
   # Commit nel submodule
   git add .
   git commit -m "Fix: Risolto bug nel monitoring CPU"
   git push origin master
   ```

3. **Aggiorna il puntatore nel progetto principale**:
   ```powershell
   cd ..\..  # Torna alla root del progetto
   git add external/python-resource-monitor
   git commit -m "Update: Sync resource-monitor to latest version"
   git push
   ```

---

## 4. Aggiornare i Submodules {#aggiornare-submodules}

### Opzione A: GitUtility Tool (Raccomandato)

1. Apri **GitUtility**
2. Carica il profilo del progetto
3. Tab **"Submodules"**
4. Click **"Sync All Submodules"**
5. Il tool:
   - Fa `git pull` in ogni submodule
   - Aggiorna i puntatori nel repo principale
   - Crea un commit automatico se ci sono cambiamenti

### Opzione B: Manualmente

```powershell
# Aggiorna tutti i submodules all'ultima versione
git submodule update --remote --merge

# Verifica cosa è cambiato
git status

# Se ci sono modifiche, committa i nuovi puntatori
git add external/
git commit -m "Update: Sync submodules to latest versions"
git push
```

### Aggiornare un Singolo Submodule

```powershell
# Entra nel submodule
cd external/python-tkinter-logger

# Pull delle modifiche
git pull origin master

# Torna alla root
cd ..\..

# Commit del nuovo puntatore
git add external/python-tkinter-logger
git commit -m "Update: Sync tkinter-logger to v1.2.0"
git push
```

---

## 5. Clonare un Progetto con Submodules {#clonare-progetto}

### Prima Clonazione

```powershell
# Clona il progetto principale E i submodules in un comando
git clone --recurse-submodules http://your-gitea.com/you/YourProject.git

cd YourProject
# Tutto pronto! I submodules sono già presenti in external/
```

### Se Hai Già Clonato Senza --recurse-submodules

```powershell
cd YourProject

# Inizializza e clona i submodules
git submodule update --init --recursive

# Ora i submodules sono presenti
```

### Dopo un Pull che Aggiorna i Submodules

```powershell
# Qualcun altro ha aggiornato i submodules
git pull

# Aggiorna i submodules alle nuove versioni
git submodule update --init --recursive
```

**Tip**: Crea un alias per semplificare:
```powershell
# In PowerShell profile
function git-pull-all {
    git pull
    git submodule update --init --recursive
}
```

---

## 6. Contribuire ai Moduli Condivisi {#contribuire}

### Workflow per Migliorare un Modulo

1. **Crea un branch nel submodule**:
   ```powershell
   cd external/python-resource-monitor
   git checkout -b feature/add-disk-monitoring
   ```

2. **Sviluppa e testa**:
   ```powershell
   # Modifica resource_monitor.py
   # Aggiungi test in tests/
   pytest tests/
   ```

3. **Commit e push del branch**:
   ```powershell
   git add .
   git commit -m "Feat: Add disk usage monitoring"
   git push origin feature/add-disk-monitoring
   ```

4. **Crea Pull Request** su Gitea/GitHub

5. **Dopo il merge**, aggiorna nel progetto principale:
   ```powershell
   cd ../..
   git submodule update --remote --merge
   git add external/python-resource-monitor
   git commit -m "Update: Use latest resource-monitor with disk monitoring"
   ```

---

## 7. Troubleshooting {#troubleshooting}

### Problema: "ModuleNotFoundError: No module named 'resource_monitor'"

**Causa**: I path non sono configurati correttamente.

**Soluzione**:
1. Verifica che `_setup_paths.py` esista e sia importato in `__init__.py`
2. Verifica che i submodules siano presenti:
   ```powershell
   ls external/
   # Dovresti vedere python-resource-monitor/ e python-tkinter-logger/
   ```
3. Se mancano, inizializzali:
   ```powershell
   git submodule update --init --recursive
   ```

### Problema: "fatal: No url found for submodule path 'external/...'"

**Causa**: Il file `.gitmodules` è danneggiato o mancante.

**Soluzione**:
```powershell
# Rimuovi e ri-aggiungi il submodule
git submodule deinit external/python-resource-monitor
git rm external/python-resource-monitor
git submodule add -b master http://your-gitea.com/you/python-resource-monitor.git external/python-resource-monitor
```

### Problema: Submodule in "Detached HEAD" State

**Causa**: Normale quando usi `git submodule update`.

**Soluzione** (se vuoi lavorare nel submodule):
```powershell
cd external/python-resource-monitor
git checkout master
git pull
```

### Problema: Modifiche Non Commesse nel Submodule Bloccano Update

**Causa**: Hai modifiche locali non committate.

**Soluzione**:
```powershell
cd external/python-resource-monitor

# Opzione 1: Committa le modifiche
git add .
git commit -m "WIP: Changes in progress"

# Opzione 2: Stash le modifiche
git stash

# Opzione 3: Scarta le modifiche (ATTENZIONE!)
git reset --hard HEAD
```

### Problema: Test Falliscono con Import Error

**Causa**: Il path setup nei test non è corretto.

**Soluzione**: Verifica che il path setup nei test usi il percorso relativo corretto:
```python
# tests/test_something.py
external_base = os.path.join(os.path.dirname(os.path.dirname(__file__)), "external")
# os.path.dirname(__file__) = tests/
# os.path.dirname(os.path.dirname(__file__)) = project_root/
```

---

## 📋 Checklist per Nuovi Progetti

Quando inizi un nuovo progetto che usa i submodules:

- [ ] Aggiungi i submodules nella cartella `external/`
- [ ] Crea `your_app/_setup_paths.py`
- [ ] Importa `_setup_paths` in `your_app/__init__.py`
- [ ] Aggiungi path setup nei file di test
- [ ] Verifica gli import: `python -c "from resource_monitor import ResourceMonitor"`
- [ ] Testa l'applicazione: `python -m your_app`
- [ ] Esegui i test: `pytest`
- [ ] Documenta nel README quali submodules usi
- [ ] Aggiungi istruzioni clone: `git clone --recurse-submodules ...`

---

## 🔗 Link Utili

### Moduli Disponibili

- **python-resource-monitor**: Monitor CPU/RAM/Thread per applicazioni Tkinter
  - Repository: `http://your-gitea.com/you/python-resource-monitor`
  - Docs: `external/python-resource-monitor/RESOURCE_MONITOR_README.md`
  
- **python-tkinter-logger**: Sistema di logging con integrazione Tkinter
  - Repository: `http://your-gitea.com/you/python-tkinter-logger`
  - Docs: `external/python-tkinter-logger/TKINTER_LOGGER_README.md`

### Git Submodules Reference

- [Git Submodules Official Docs](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
- [GitUtility Tool Documentation](../gitutility/README.md)

---

## 💡 Best Practices

### DO ✅

- **Usa branch tracking** (`-b master`) quando aggiungi submodules
- **Committa i puntatori** dopo ogni update di submodule
- **Testa sempre** dopo aver aggiornato i submodules
- **Documenta** quali versioni dei moduli usi nel README
- **Usa GitUtility** per gestire i submodules (più semplice e sicuro)

### DON'T ❌

- **Non modificare** i submodules direttamente senza fare commit/push
- **Non fare** modifiche nei submodules se non necessario (usa il modulo così com'è)
- **Non dimenticare** di aggiornare i puntatori dopo modifiche nei submodules
- **Non ignorare** i conflitti nei submodules durante merge/pull
- **Non committare** `.git` delle cartelle dei submodules (Git lo gestisce automaticamente)

---

## 🎓 Esempi Pratici

### Esempio 1: Nuovo Progetto di Monitoraggio

```powershell
# 1. Crea il progetto
mkdir C:\src\MonitoringApp
cd C:\src\MonitoringApp
git init

# 2. Aggiungi solo resource-monitor (non serve logger)
git submodule add -b master http://gitea.local/shared/python-resource-monitor.git external/python-resource-monitor

# 3. Setup del progetto
mkdir monitoring_app
# Copia _setup_paths.py da target_simulator
# Crea __init__.py che importa _setup_paths

# 4. Usa il modulo
# In monitoring_app/main.py:
from resource_monitor import ResourceMonitor
monitor = ResourceMonitor()
```

### Esempio 2: Applicazione con GUI Completa

```powershell
# Aggiungi entrambi i moduli
git submodule add -b master http://gitea.local/shared/python-resource-monitor.git external/python-resource-monitor
git submodule add -b master http://gitea.local/shared/python-tkinter-logger.git external/python-tkinter-logger

# In gui_app/main_window.py:
from tkinter_logger import TkinterLogger
from resource_monitor import TkinterResourceMonitor

class MainWindow:
    def __init__(self, root):
        self.logger = TkinterLogger(root)
        self.logger.setup(enable_console=True, enable_tkinter=True)
        self.monitor = TkinterResourceMonitor(root)
```

### Esempio 3: Aggiornamento Coordinato

```powershell
# GitUtility workflow
# 1. Apri GitUtility
# 2. Tab "Submodules" → "Check for Updates"
#    Output: "python-resource-monitor: 2 commits behind"
# 3. Click "Sync All Submodules"
#    → Automatic pull and commit
# 4. Tab "Remote" → "Push" per condividere gli aggiornamenti
```

---

## 📞 Supporto

Per problemi o domande:
1. Controlla questa guida e il [Troubleshooting](#troubleshooting)
2. Verifica la documentazione dei moduli in `external/*/README.md`
3. Consulta i test di esempio in `external/*/tests/`
4. Usa GitUtility Tool per gestione automatica

---

**Ultimo aggiornamento**: 26 Novembre 2025  
**Versione guida**: 1.0  
**Compatibile con**: Python 3.9+, Git 2.30+