525 lines
14 KiB
Markdown
525 lines
14 KiB
Markdown
# 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+
|