Concevoir un outil en ligne de commande Python : argparse, main() et codes de sortie

Objectif

Construire un outil en ligne de commande que des scripts shell, des tâches d'intégration continue et des agents peuvent piloter : des arguments prévisibles, un texte d'aide qui tient lieu de documentation, des codes de sortie structurés et des flux de sortie bien séparés.

Prérequis

Un paquet doté d'un pyproject.toml (voir l'article sur l'empaquetage), dont la logique réside dans des fonctions importables, distinctes du traitement des arguments.

Étapes

1. Écrire une fonction def main(argv: list[str] | None = None) -> int qui construit l'analyseur, analyse argv (en utilisant sys.argv[1:] si aucun argument n'est fourni) et renvoie un code de sortie. L'enregistrer via [project.scripts] tool = "pkg.cli:main" et ajouter if __name__ == "__main__": sys.exit(main()). Les tests appellent alors main(["--flag", "x"]) et vérifient la valeur renvoyée ainsi que la sortie capturée.
2. Construire l'analyseur avec prog, description et un epilog contenant des exemples. Utiliser des convertisseurs type= (int, pathlib.Path, ou une fonction levant ArgumentTypeError) pour que les valeurs incorrectes soient signalées comme des erreurs d'utilisation, choices= pour les ensembles fermés, et add_subparsers(dest="command", required=True) pour les outils à plusieurs commandes.
3. Suivre la convention décrite dans la documentation de sys.exit : les programmes Unix utilisent généralement 2 pour les erreurs de syntaxe en ligne de commande et 1 pour toutes les autres erreurs, 0 indiquant le succès. argparse se termine déjà avec le code 2 en cas d'arguments invalides. N'adopter d'autres codes issus de sysexits.h (EX_USAGE 64, EX_NOINPUT 66, EX_UNAVAILABLE 69, EX_TEMPFAIL 75) que si --help les documente.
4. Écrire les résultats sur stdout et les diagnostics sur stderr. Proposer --json lorsque d'autres programmes exploitent la sortie, ainsi que --verbose/--quiet pour régler le niveau de journalisation plutôt que de multiplier les appels à print.
5. Intercepter dans main les échecs attendus (FileNotFoundError, erreurs de connexion, exceptions métier), afficher une seule ligne sur stderr et renvoyer le code documenté ; laisser les exceptions inattendues se propager afin de conserver la trace d'appel et le code de sortie 1.
6. Gérer KeyboardInterrupt en effectuant le nettoyage puis en renvoyant 130, conformément à la convention du shell de 128 plus le numéro du signal, et intercepter BrokenPipeError sur stdout sans afficher d'erreur pour que tool | head se termine silencieusement.
7. Veiller à ce que l'aide reflète le fonctionnement réel de l'outil : utiliser metavar pour des noms de paramètres lisibles, ArgumentDefaultsHelpFormatter pour afficher les valeurs par défaut, et un test vérifiant que --help se termine avec le code 0.

Résultat attendu

tool --help documente l'intégralité de l'interface ; tool --bad; echo $? affiche 2 ; un problème d'entrée produit une seule ligne sur stderr et un code de sortie documenté ; un appelant peut choisir le traitement à effectuer selon ce code sans avoir à analyser du texte.

Limites et base de vérification

La documentation de sys.exit indique que la plupart des systèmes exigent des codes de sortie compris entre 0 et 127 ; les valeurs supérieures entrent en conflit avec l'encodage des signaux par le shell. exit_on_error=False conduit l'analyseur à lever ArgumentError au lieu de terminer le programme, ce qui convient à une intégration dans un autre programme mais nécessite une gestion spécifique des erreurs. Les conventions suivent la documentation citée ; aucune mesure de facilité d'utilisation n'est revendiquée.

Terminer le processus après Ctrl-C

Un shell décide si une interruption doit aussi arrêter le script englobant en vérifiant si le processus enfant s'est terminé à cause de SIGINT, et non en lisant le code de sortie. Un outil qui intercepte KeyboardInterrupt et renvoie 130 est donc considéré comme s'étant terminé normalement, et for f in *; do tool "$f"; done passe au fichier suivant après chaque Ctrl-C. Effectuer le nettoyage, puis terminer le processus comme le ferait une interruption non interceptée (Python le fait de lui-même depuis la version 3.8) :

except KeyboardInterrupt:
    cleanup()
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    os.kill(os.getpid(), signal.SIGINT)

$? vaut toujours 130, et un processus parent qui attend la fin du processus constate une terminaison par signal. Réserver return 130 aux appelants dont on sait qu'ils consultent uniquement les codes de sortie.