Argo Famiglia API - Python Library

Una libreria Python completa per accedere programmaticamente all'API di Argo Scuola Famiglia, permettendo di ottenere voti, compiti, assenze e comunicazioni per più figli.

✨ Caratteristiche

• 🔐 Autenticazione OAuth2 PKCE sicura
• 👨‍👩‍👧‍👦 Supporto multi-figlio - Gestisce automaticamente più figli
• � Supporto multi-account - Consente più account genitore (multi-utente) e iterazione su tutti i figli
• �📊 Dati strutturati - Classi Python per tutti i tipi di dati
• 🛡️ Gestione errori robusta con logging dettagliato
• 📱 API moderna - Interfaccia semplice e intuitiva
• 🧪 Test-ready - Struttura modulare per testing

🚀 Installazione

Da PyPI (consigliato)

pip install argo-famiglia-api

Da sorgente

git clone https://github.com/yourusername/argo-famiglia-api.git
cd argo-famiglia-api
pip install -e .

Dipendenze

• requests >= 2.25.0
• python-dotenv >= 0.19.0 (opzionale, per supporto .env files)

📖 Utilizzo Rapido

from argo_famiglia_api import ArgoFamiglia

# Metodo 1: Prompt interattivo (raccomandato)
argo = ArgoFamiglia()
children = argo.authenticate()  # Chiede credenziali in modo sicuro

# Metodo 2: Variabili d'ambiente
import os
os.environ['ARGO_SCHOOL_CODE'] = 'SCxxxxx'  # Replace with your school code
os.environ['ARGO_USERNAME'] = 'genitore'
os.environ['ARGO_PASSWORD'] = 'password'
argo = ArgoFamiglia()
children = argo.authenticate()  # Usa env vars

# Metodo 3: Passaggio diretto (usa solo per test)
argo = ArgoFamiglia('SCxxxxx', 'genitore', 'password')  # Replace SCxxxxx with your school code
children = argo.get_children()

# Usa i dati
for child in children:
    grades = argo.get_grades(child.token)
    assignments = argo.get_assignments(child.token)
    absences = argo.get_absences(child.token)

for child in children: print(f"Elaborando dati per {child.full_name}")

# Voti
grades = argo.get_grades(child.token)

# Compiti
assignments = argo.get_assignments(child.token)

# Assenze
absences = argo.get_absences(child.token)

## � Multi-account (multi-utente)

La libreria supporta più account genitore / multipli set di credenziali.
Questo è utile quando più persone (es. mamma e papà) vogliono accedere agli stessi figli.

```python
from argo_famiglia_api import ArgoFamiglia

accounts = [
    {"school_code": "SCxxxxx", "username": "parent1", "password": "secret1"},
    {"school_code": "SCxxxxx", "username": "parent2", "password": "secret2"},
]

all_children = ArgoFamiglia.authenticate_multiple(accounts)
print(f"Trovati {len(all_children)} figli in totale")

�📚 Documentazione API

Classe ArgoFamiglia

Classe principale per l'interazione con l'API.

Metodi

• get_children() - Restituisce lista di oggetti Child
• get_grades(token) - Restituisce lista di oggetti Grade
• get_assignments(token) - Restituisce lista di oggetti Assignment
• get_absences(token) - Restituisce lista di oggetti Absence

Modelli Dati

Child

@dataclass
class Child:
    id: str
    name: str
    surname: str
    class_name: str
    token: str

    @property
    def full_name(self) -> str: ...

Grade

@dataclass
class Grade:
    subject: str
    grade: str
    date: str
    type: str
    teacher: str
    notes: Optional[str] = None

Assignment

@dataclass
class Assignment:
    subject: str
    description: str
    date: str
    teacher: str

Absence

@dataclass
class Absence:
    date: str
    type: str
    justified: bool
    hours: int

🎯 Esempio Completo

from argo_famiglia_api import ArgoFamiglia
from argo_famiglia_api.utils import format_grades_table

# Credenziali (sostituisci con le tue!)
SCHOOL_CODE = "SCxxxxx"  # Replace with your school code
USERNAME = "genitore"
PASSWORD = "password"

def main():
    argo = ArgoFamiglia(SCHOOL_CODE, USERNAME, PASSWORD)

    try:
        # Autenticazione e ottenimento figli
        children = argo.get_children()
        print(f"Trovati {len(children)} figli")

        # Elabora ogni figlio
        for child in children:
            print(f"\n=== {child.full_name} ({child.class_name}) ===")

            # Voti
            grades = argo.get_grades(child.token)
            if grades:
                print("\n📊 ULTIMI VOTI:")
                print(format_grades_table(grades))

            # Compiti
            assignments = argo.get_assignments(child.token)
            if assignments:
                print(f"\n📝 COMPITI: {len(assignments)} totali")
                for assignment in assignments[:3]:
                    print(f"  • {assignment}")

            # Assenze
            absences = argo.get_absences(child.token)
            if absences:
                print(f"\n🏫 ASSENZE: {len(absences)} totali")
                unjustified = [a for a in absences if not a.justified]
                if unjustified:
                    print(f"  ⚠️  Da giustificare: {len(unjustified)}")

    except Exception as e:
        print(f"Errore: {e}")

if __name__ == "__main__":
    main()

🔧 Configurazione Sicura

Variabili d'Ambiente

export ARGO_SCHOOL_CODE="SCxxxxx"  # Replace with your school code
export ARGO_USERNAME="genitore"
export ARGO_PASSWORD="password"

import os
argo = ArgoFamiglia(
    school_code=os.getenv("ARGO_SCHOOL_CODE"),
    username=os.getenv("ARGO_USERNAME"),
    password=os.getenv("ARGO_PASSWORD")
)

File di Configurazione

# config.py
ARGO_CONFIG = {
    "school_code": "SCxxxxx",
    "username": "genitore",
    "password": "password"
}

🧪 Testing

# Installa dipendenze di sviluppo
pip install -e ".[dev]"

# Esegui test
pytest

# Con coverage
pytest --cov=argo_famiglia_api

📋 Endpoints Supportati

• ✅ votigiornalieri - Voti giornalieri
• ✅ compiti - Compiti assegnati
• ✅ assenze - Registro assenze
• ✅ comunicazioni - Comunicazioni scuola
• ✅ note - Note disciplinari
• ✅ orario - Orario scolastico

🔒 Sicurezza

IMPORTANTE: Questa libreria non memorizza mai le credenziali nel codice sorgente.

Metodi di Autenticazione (in ordine di sicurezza)

1. � File segreto JSON (Raccomandato)

   • Crea un file .argo_credentials.json (o imposta ARGO_CREDENTIALS_FILE) con:

     {
       "school_code": "SCxxxxx",
       "username": "genitore",
       "password": "password"
     }
     

   • Assicurati che il file sia ignorato da Git (.gitignore include ".env" per default, aggiungi anche .argo_credentials.json se serve).

2. 🌍 Variabili d'Ambiente

   export ARGO_SCHOOL_CODE="SCxxxxx"
   export ARGO_USERNAME="genitore"
   export ARGO_PASSWORD="password"
   

3. 🔐 Prompt Interattivo (se non trovi credenziali altrove)

   argo = ArgoFamiglia()
   children = argo.authenticate()  # Chiede credenziali al momento
   

4. ⚠️ Passaggio Diretto (Solo per test locali)

   argo = ArgoFamiglia('SCxxxxx', 'user', 'pass')  # Replace SCxxxxx with your school code
   

Best Practices di Sicurezza

• ✅ Mai hardcodare credenziali nel codice
• ✅ Usare env vars per deployment
• ✅ Prompt interattivo per uso manuale
• ✅ Non committare file con credenziali
• ✅ Usare .env files locali (ignorati da git)

🤝 Contributi

Contributi benvenuti! Per favore:

1. Fork il repository
2. Crea un branch per la tua feature (git checkout -b feature/AmazingFeature)
3. Commit le tue modifiche (git commit -m 'Add some AmazingFeature')
4. Push al branch (git push origin feature/AmazingFeature)
5. Apri una Pull Request

📄 Licenza

Questo progetto è distribuito sotto licenza MIT. Vedi il file LICENSE per dettagli.

⚠️ Disclaimer

Questa libreria è un progetto indipendente e non è affiliata con Argo Software o istituti scolastici. Utilizzala responsabilmente e in conformità con i termini di servizio di Argo Scuola Famiglia.

📞 Supporto

• 🐛 Issues
• 💬 Discussions
• 📧 Email

---

Sviluppato con ❤️ per la comunità educativa