Documentation de Pyromaths 18.6-2

4. Interface en ligne de commande

«  3.3. API par l’exemple   ::   Contenu

4. Interface en ligne de commande

Pyromaths dispose d’une interface en ligne de commande : pyromaths-cli. Elle peut-être utilisées dans des scripts, ou pour l’écriture de nouveaux exercices, pour controler le rendu au fur et à mesure du développement.

4.1. Exécution

Il y a deux manières d’appeler ce programme, qui sont équivalentes.

  • En laissant Python rechercher le module correspondant. Ceci suppose que le module pyromaths est dans le PYTHONPATH.

    python -m pyromaths.cli
    
  • En exécutant un fichier situé dans le répertoire utils. Le PYTHONPATH est automatiquement géré ; c’est utile si vous n’arrivez pas à le faire vous-même, ou si vous n’avez pas compris la phrase précédente.

    python utils/pyromaths-cli.py
    

4.2. Commandes disponibles

  • Compilation d’un exercice (python -m pyromaths.cli compile) : Compile un exercice, et crée le PDF correspondant (énoncé et solution) dans le dossier courant. Cette commande est utile pour tester un exercice en cours de rédaction, plutôt que de passer par l’interface graphique.

    Il est également possible de fournir des commandes à exécuter sur les fichiers LaTeX avant leur compilation. Ceci est utile pour déceler des erreurs de code LaTeX. Par exemple, la commande python -m pyromaths.cli compile -p more EXERCICE affiche le code LaTeX dans more avant compilation; la commande python -m pyromaths.cli compile -p vim EXERCICE édite le fichier avec vim avant compilation. Ceci peut aussi être utilisé (en attendant une solution plus propre) pour garder une copie du fichier LaTeX en cas d’erreur de compilation, pour pouvoir l’analyser, ainsi que le log : python -m pyromaths.cli compile -p 'cp {} exercices.tex' EXERCICE.

  • Liste des identifiants des exercices disponibles (python -m pyromaths.cli ls) : Affiche la liste des identifiants des exercices, pour retrouver facilement l’exercice en cours de travail. Plus d’informations sont données dans la partie Description des exercices.

  • Test des exercices (python -m pyromaths.cli test) : Voir la partie python -m pyromaths.cli test.

4.3. Description des exercices

Les exercices sur lesquels s’appliquent les commandes de pyromaths-cli sont décrits comme exo_pythagore:4,6, où :

  • exo_pythagore est l’identifiant de l’exercice (le nom de la fonction ou de la classe qui le définit) ;
  • 4,6 sont les graines du générateur aléatoire qui nous intéressent. Si les graines sont omises, suivant le cas, soit tous les tests enregistrés sont considérés, soit la graine 0 est utilisée.

La liste des exercices disponibles peut être obtenue avec la commande python -m pyromaths.cli ls.

4.4. python -m pyromaths.cli test

Cet outil permet de mettre en œuvre des tests de non régression pour les exercices.

4.4.1. Principe

Les exercices de Pyromaths sont générés aléatoirement. Néanmoins, en fixant la graine (random.seed()) du générateur aléatoire, il est possible de générer deux fois de suite exactement le même exercice.

Le principe de ces tests est le suivant : la personne concevant un exercice peut en valider un énoncé particulier. Plus tard, il sera possible de vérifier que l’exercice produit toujours exactement la même sortie.

Cet outil est conçu de telle manière à ce que l’appel au module unittest de Python (par exemple avec python -m unittest discover) effectue tous ces tests.

4.4.2. Commandes

4.4.2.1. Description rapide

Les commandes détaillées sont décrites ci-après. En voici une version simplifiée.

  • Création (python -m pyromaths.cli test create), suppression des tests (python -m pyromaths.cli test remove)
  • Mise à jour des tests (python -m pyromaths.cli test update) : Effectue les tests, et propose de mettre à jour les tests qui ont changé. Utile si le code LaTeX généré a changé, mais l’exercice reste valide pour autant.
  • Exécution des tests (python -m pyromaths.cli test check) : Effectue les tests. Les tests sont aussi exécutés lorsqu”unittest est appelé.

4.4.2.2. Description complète

usage: pyromaths-cli test [-h] [-v] {create,missing,remove,update,check} ...
Options:
-v, --version show program’s version number and exit
Sub-commands:
create

Create test given in argument.

usage: pyromaths-cli test create [-h]
                                 EXERCISE[:SEED[,SEED]]
                                 [EXERCISE[:SEED[,SEED]] ...]
Positional arguments:
exercise Exercises to test.
missing

Create missing tests.

usage: pyromaths-cli test missing [-h]
remove

Remove a test

usage: pyromaths-cli test remove [-h]
                                 EXERCISE[:SEED[,SEED]]
                                 [EXERCISE[:SEED[,SEED]] ...]
Positional arguments:
exercise Exercises to remove.
update

Perform tests given in argument. Update tests that have changed.

usage: pyromaths-cli test update [-h]
                                 [EXERCISE[:SEED[,SEED]]
                                 [EXERCISE[:SEED[,SEED]] ...]]
Positional arguments:
exercise Exercises to test. If empty, all exercises are tested.
check

Test exercises (equivalent to `python -m unittest discover`, for exercises only).

usage: pyromaths-cli test check [-h]
                                [EXERCISE[:SEED[,SEED]]
                                [EXERCISE[:SEED[,SEED]] ...]]
Positional arguments:
exercise Exercises to check. If empty, all exercises are checked.

«  3.3. API par l’exemple   ::   Contenu