# --- argparse : le module stdlib, verbeux mais complet et sans dependance ---
import argparse
import sys

def construire_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="monoutil",
        description="Synchronise des fichiers vers un serveur distant",
        epilog="Exemple : monoutil sync --source ./data --dest s3://bucket -v",
    )
    parser.add_argument(
        "--version", action="version", version="%(prog)s 2.1.0"
    )

    # Sous-commandes (pattern git-like : monoutil sync, monoutil clean, ...)
    sous_commandes = parser.add_subparsers(dest="commande", required=True)

    parser_sync = sous_commandes.add_parser("sync", help="Synchronise des fichiers")
    parser_sync.add_argument(
        "--source", type=str, required=True, help="Dossier source"
    )
    parser_sync.add_argument(
        "--dest", type=str, required=True, help="Destination (chemin ou URI)"
    )
    parser_sync.add_argument(
        "--retries", type=int, default=3, help="Nombre de tentatives (defaut : 3)"
    )
    parser_sync.add_argument(
        "-v", "--verbose", action="count", default=0,
        help="Augmente la verbosite (-v, -vv, -vvv)"
    )

    # Arguments mutuellement exclusifs : impossible de combiner --quiet et --verbose
    groupe_bruit = parser_sync.add_mutually_exclusive_group()
    groupe_bruit.add_argument("--quiet", action="store_true")
    groupe_bruit.add_argument("--dry-run", action="store_true", help="Simule sans agir")

    # Type personnalise : valider/transformer une valeur des le parsing
    def taille_positive(valeur: str) -> int:
        n = int(valeur)
        if n <= 0:
            raise argparse.ArgumentTypeError(f"{valeur} doit etre un entier positif")
        return n

    parser_sync.add_argument("--chunk-size", type=taille_positive, default=1024)

    # choices : restreint les valeurs acceptees, message d'erreur automatique
    parser_sync.add_argument(
        "--strategie", choices=["miroir", "additif", "differentiel"], default="miroir"
    )

    parser_clean = sous_commandes.add_parser("clean", help="Nettoie les fichiers temporaires")
    parser_clean.add_argument("--force", action="store_true")

    return parser

def main(argv: list[str] | None = None) -> int:
    parser = construire_parser()
    args = parser.parse_args(argv)

    if args.commande == "sync":
        niveau = "DEBUG" if args.verbose >= 2 else "INFO" if args.verbose == 1 else "WARNING"
        print(f"Sync {args.source} -> {args.dest} (niveau log : {niveau})")
        if args.dry_run:
            print("Mode simulation : aucune modification reelle")
            return 0
        # ... logique reelle ...
        return 0
    elif args.commande == "clean":
        print(f"Nettoyage (force={args.force})")
        return 0

    parser.print_help()
    return 1

if __name__ == "__main__":
    sys.exit(main())

# Usage :
# python cli.py sync --source ./data --dest ./backup -vv --dry-run
# python cli.py sync --chunk-size -5     -> erreur claire via argparse.ArgumentTypeError

# --- Fallback sur des variables d'environnement pour les valeurs par defaut ---
import os

parser_env = argparse.ArgumentParser()
parser_env.add_argument(
    "--api-key",
    default=os.environ.get("API_KEY"),
    required="API_KEY" not in os.environ,     # requis seulement si pas dans l'environnement
)

# --- Codes de sortie conventionnels : 0 = succes, non-zero = categorie d'erreur ---
CODE_SUCCES = 0
CODE_ERREUR_UTILISATEUR = 1
CODE_ERREUR_RESEAU = 2
CODE_ERREUR_INTERNE = 3

def main_avec_codes(argv=None) -> int:
    try:
        # ... logique ...
        return CODE_SUCCES
    except ValueError:
        print("Argument invalide", file=sys.stderr)
        return CODE_ERREUR_UTILISATEUR
    except ConnectionError:
        print("Erreur reseau", file=sys.stderr)
        return CODE_ERREUR_RESEAU
    except Exception:
        print("Erreur interne inattendue", file=sys.stderr)
        return CODE_ERREUR_INTERNE

# --- Typer : CLI moderne basee sur les type hints, au-dessus de Click ---
# pip install typer
'''
import typer
from pathlib import Path
from typing_extensions import Annotated

app = typer.Typer(help="Synchronise des fichiers vers un serveur distant")

@app.command()
def sync(
    source: Annotated[Path, typer.Option(help="Dossier source", exists=True)],
    dest: Annotated[str, typer.Option(help="Destination")],
    retries: Annotated[int, typer.Option(help="Nombre de tentatives")] = 3,
    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
):
    """Synchronise SOURCE vers DEST."""
    if verbose:
        typer.echo(f"Sync verbeux : {source} -> {dest}")
    with typer.progressbar(range(100)) as barre:
        for _ in barre:
            pass  # traitement reel ici
    typer.secho("Termine !", fg=typer.colors.GREEN)

@app.command()
def clean(force: bool = False):
    """Nettoie les fichiers temporaires."""
    if not force and not typer.confirm("Confirmer le nettoyage ?"):
        raise typer.Abort()
    typer.echo("Nettoyage effectue")

if __name__ == "__main__":
    app()
'''
# Typer genere automatiquement : --help, la completion shell (bash/zsh/fish),
# la validation de type depuis les annotations, et les messages d'erreur formattes.