Metadata-Version: 2.4
Name: argo-famiglia-api
Version: 1.0.0
Summary: Python library for accessing Argo Scuola Famiglia API
Author-email: Roberto Galati <your.email@example.com>
Maintainer-email: Roberto Galati <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/argo-famiglia-api
Project-URL: Documentation, https://github.com/yourusername/argo-famiglia-api#readme
Project-URL: Repository, https://github.com/yourusername/argo-famiglia-api.git
Project-URL: Issues, https://github.com/yourusername/argo-famiglia-api/issues
Project-URL: Changelog, https://github.com/yourusername/argo-famiglia-api/blob/main/CHANGELOG.md
Keywords: argo,scuola,famiglia,api,education,grades,assignments,absences,students
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: dotenv
Requires-Dist: python-dotenv>=0.19.0; extra == "dotenv"

# Argo Famiglia API - Python Library

[![Python Version](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/argo-famiglia-api.svg)](https://pypi.org/project/argo-famiglia-api/)

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)
```bash
pip install argo-famiglia-api
```

### Da sorgente
```bash
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

```python
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`
```python
@dataclass
class Child:
    id: str
    name: str
    surname: str
    class_name: str
    token: str

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

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

#### `Assignment`
```python
@dataclass
class Assignment:
    subject: str
    description: str
    date: str
    teacher: str
```

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

## 🎯 Esempio Completo

```python
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
```bash
export ARGO_SCHOOL_CODE="SCxxxxx"  # Replace with your school code
export ARGO_USERNAME="genitore"
export ARGO_PASSWORD="password"
```

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

### File di Configurazione
```python
# config.py
ARGO_CONFIG = {
    "school_code": "SCxxxxx",
    "username": "genitore",
    "password": "password"
}
```

## 🧪 Testing

```bash
# 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:
     ```json
     {
       "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**
   ```bash
   export ARGO_SCHOOL_CODE="SCxxxxx"
   export ARGO_USERNAME="genitore"
   export ARGO_PASSWORD="password"
   ```

3. **🔐 Prompt Interattivo** (se non trovi credenziali altrove)
   ```python
   argo = ArgoFamiglia()
   children = argo.authenticate()  # Chiede credenziali al momento
   ```

4. **⚠️ Passaggio Diretto** (Solo per test locali)
   ```python
   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](https://github.com/yourusername/argo-famiglia-api/issues)
- 💬 [Discussions](https://github.com/yourusername/argo-famiglia-api/discussions)
- 📧 [Email](mailto:your.email@example.com)

---

**Sviluppato con ❤️ per la comunità educativa**
