VALLONGOL/SXXXXXXX_PyUCC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e5f8673078
SXXXXXXX_PyUCC/doc/GUIDA_SUBMODULES.md

14 KiB
Raw Blame History

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
  2. Setup del Progetto per Usare i Submodules
  3. Workflow Quotidiano
  4. Aggiornare i Submodules
  5. Clonare un Progetto con Submodules
  6. Contribuire ai Moduli Condivisi
  7. Troubleshooting

1. Aggiungere Submodules a un Nuovo Progetto

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

# 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

Passo 1: Creare il File _setup_paths.py

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

"""
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:

"""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:

# 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:

# 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

Sviluppo Normale

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

# 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:

    cd external/python-resource-monitor

  2. Lavora normalmente:

    # 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:

    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

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

# 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

# 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

Prima Clonazione

# 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

cd YourProject

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

# Ora i submodules sono presenti

Dopo un Pull che Aggiorna i Submodules

# 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:

# In PowerShell profile
function git-pull-all {
    git pull
    git submodule update --init --recursive
}

6. Contribuire ai Moduli Condivisi

Workflow per Migliorare un Modulo

  1. Crea un branch nel submodule:

    cd external/python-resource-monitor
git checkout -b feature/add-disk-monitoring

  2. Sviluppa e testa:

    # Modifica resource_monitor.py
# Aggiungi test in tests/
pytest tests/

  3. Commit e push del branch:

    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:

    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

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: 
    ls external/
# Dovresti vedere python-resource-monitor/ e python-tkinter-logger/
  3. Se mancano, inizializzali: 
    git submodule update --init --recursive

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

Causa: Il file .gitmodules è danneggiato o mancante.

Soluzione:

# 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):

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:

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:

# 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

💡 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

# 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

# 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

# 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
  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+