1. Programmation modulaire

sept. 10, 2018

Objectifs

  • établir la méthodologie à suivre pour l’ensemble des travaux d’AP2
  • manipuler le module complex vu en cours
  • concevoir un nouveau module sur les cartes

1.1. Méthodologie

Le but de cette partie est de vous familiariser avec la méthodologie que vous suivrez pour chacune des séances de TP, ainsi que pour le projet que vous réaliserez en fin de semestre.

En deux mots cette méthodologie vise à vous indiquer

  • comment seront organisés les fichiers de vos TP et projets,
  • comment vous documenterez vos TP et projets,
  • et comment vous réaliserez les archives de vos travaux pour remise à votre enseignant.

Pour l’ensemble des travaux que vous réaliserez, il est supposé que votre poste de travail est équipé

  • d’un interpréteur Python version 3.x,
  • d’un éditeur de textes pour les fichiers de programmes ainsi que les fichiers de documentation,
  • du logiciel sphinx permettant de produire dans différents format la documentation de vos programmes Python,
  • d’un navigateur Web,
  • de la commande make permettant de construire automatiquement des fichiers

ce qui est le cas des postes des salles de TP du SUP ou du M5.

1.2. Le module complex

1.2.1. Description de l’arborescence de fichiers des projets

  1. Récupérez l’archive complex.zip et décompressez la dans un dossier Complex. Celui-ci contient alors :

    • un fichier conf.py : c’est un fichier de configuration (écrit en Python) pour le logiciel sphinx. Vous n’aurez pas à l’éditer explicitement.
    • un dossier images contenant le fichier logo_FIL.png : c’est le logo du FIL qui figurera dans la documentation de vos projets.
    • un dossier _templates contenant le fichier layout.html : c’est un squelette décrivant le format des pages HTML que vous produirez pour la documentation. Vous n’aurez pas à l’éditer explicitement.
    • un fichier Makefile qui décrit les commandes à exécuter à l’aide de make. Vous l’utiliserez pour produire la documentation au format HTML ainsi que les archives de remise de TP. Vous aurez à l’éditer au début de chaque projet.
    • un dossier sourcedoc contenant les quatre fichiers complex1.rst, complex2.rst, index.rst et main.rst. Ce sont des fichiers textes rédigés au format rst (reStructuredText) qui peuvent être transformés à l’aide de sphinx en différents formats dont le HTML. Vous découvrirez petit à petit ce format.
    • un dossier src contenant les six fichiers complex1.py, complex2.py, complex3.py, main1.py, main2.py et main3.py. Ce sont les fichiers de programmes Python.

    C’est l’arborescence de fichiers que vous aurez pour l’ensemble des projets du cours d’AP2.

1.2.2. Auteurs d’un projet

Chaque projet devra mentionner le nom de ses auteurs. Ces noms figureront bien entendu dans chaque fichier de code Python. Mais ils figureront aussi en bas de chaque page HTML de la documentation.

  1. Pour cela éditez le fichier Makefile. Les premières lignes de ce fichier définissent quelques variables utilisées dans les commandes qui suivent. La première de ces variables définit le nom du projet (dans le cas présent c’est Complex) et la seconde variable définit le nom des auteurs (dans le cas présent aucun auteur n’est mentionné).

    Complétez la seconde ligne de ce fichier en indiquant les noms des auteurs. Par exemple :

    AUTHOR=Raymond Calbuth, Achille Talon
    

    Sauvegardez ce fichier. Vous n’aurez plus à l’éditer pour la suite du travail sur ce projet.

  2. Dans un terminal de commandes, et dans le dossier Complex, tapez maintenant la commande :

    $ make author
    

    Cette commande modifie le fichier conf.py de façon à ce que la documentation contienne le nom des auteurs.

1.2.3. Documentation

Toute la documentation de ce projet est rédigée :

  • dans les docstrings contenues dans les différents fichiers de programmes Python contenus dans le dossier src ;
  • et dans les fichiers au format rst contenus dans le dossier sourcedoc.

Pour ce projet vous n’avez donc aucun travail de rédaction de la documentation. Vous allez uniquement produire une version HTML de cette documentation.

  1. Pour cela, dans un terminal de commandes, placez vous dans le dossier Complex contenant tous les fichiers du projet (et en particulier le fichier Makefile), et tapez la commande

    $ make doc
    

    Une fois cette commande exécutée vous devez découvrir un nouveau dossier nommé doc contenant un certain nombre de fichiers.

  2. Consultez la documentation ainsi produite avec votre navigateur web favori.

    Prenez le temps de comparer ce que vous pouvez lire sur ces pages de documentation et les fichiers source au format rst ainsi que les docstrings des fichiers Python. Vous vous familiariserez ainsi avec le format rst et le format des docstrings.

    Remarquez aussi le nom figurant en bas de chacune des pages HTML.

1.2.4. Utilisation du module Complex

  1. Les programmes mainX.py ne peuvent pas être exécutés avec un environnement de programmation intégré tel que``Idle`` ou Thonny puisque leur fonctionnement normal exige que leur soient communiqués quatre nombres sur la ligne de commande (liste sys.argv).

    Placez-vous donc dans le dossier src et tapez la commande

    $ python3 main1.py 1 2 3 4
    
  2. Recommencez la même manipulation avec main2.py et main2.py.

1.2.5. Création d’une archive

Pour rendre vos TP ou projets, vous aurez à créer une archive. Pour cela vous utiliserez la commande make.

  1. Dans un terminal de commandes, et après vous être placés dans le dossier Complex, tapez la commande

    $ make archive
    

    Une fois cette commande achevée, vous constaterez la présence dans le dossier courant d’un nouveau fichier nommé Complex.zip. C’est l’archive que vous rendrez.

    Vous pourrez aussi remarquer que le dossier doc qui avait été créé lors de la production de la documentation au format HTML a disparu. Il a été détruit avant de faire l’archive. Il est en effet inutile de mettre la documentation au format HTML dans l’archive étant donné qu’elle peut être produite très aisément avec la commande make doc.

1.3. Le module card

Dans cette partie vous allez créer un nouveau module pour représenter des cartes à jouer.

1.3.1. Préparation

  1. Créez un dossier nommé Card.
  2. Récupérez l’archive Card.zip et décompressez-la dans le dossier que vous venez de créer.
  3. Complétez la variable AUTHOR dans le fichier Makefile.

Note

Le dossier sourcedoc contient deux fichiers au format rst que vous n’aurez pas à éditer. Le dossier quant à lui src contient un seul fichier card_api.py que vous renommerez en card.py et que vous serez amené à compléter.

  1. Renommez donc le fichier card_api.py du dossier src en card.py, puis produisez la documentation du module card (commande ̀̀make doc`` depuis le dossier Card).

1.3.2. Interface du module

  1. Lisez attentivement l’interface du module card.

1.3.3. Implantation du module

  1. Réalisez l’implantation du module card.
  2. Réalisez les méthodes spéciales qui rendent possible l’utilisation des opérateurs de comparaison de Python (==, !=, <=, …), ainsi que celle permettant l’affichage d’une valeur telle que montrée dans la documentation.

1.3.4. Utilisation du module

  1. En utilisant le module card, réalisez un programme qui permet de jouer à une version simplifiée du « jeu de la bataille » (sans carte masquée en cas de « bataille »).

Dans cette version, les joueurs ont initialement un nombre égal de cartes produites au hasard (il peut y avoir plusieurs cartes identiques). À chaque tour, les joueurs jouent chacun la première de leur carte en la déposant sur la table. Celui qui a déposé la carte de plus haute valeur remporte toutes les cartes sur la table et les range à la fin de son tas de cartes. Si les hauteurs des deux cartes jouées sont égales, il y a alors « bataille » et ces cartes sont laissées sur la table. Le tour suivant peut alors commencer.

Le jeu s’arrête dès que l’un des joueurs n’a plus de carte, dans ce cas il a perdu la partie (NB : des parties infinies sont possibles, on ne cherchera pas à détecter ces situations).

Écrivez votre programme de manière qu’il puisse prendre en paramètre sur la ligne de commande le nombre de cartes que possède chaque joueur au début de la partie. Ce nombre devra être inférieur ou égal à 16 qui sera aussi la valeur par défaut.

Voici un exemple de partie de bataille avec trois cartes initialement pour chaque joueur :

  $ python3 war.py 3

  ---------------------
  first plays
  Card("King", "club")
  second plays
  Card("3", "spade")
  first player wins the round
  ---------------------
  first plays
  Card("4", "heart")
  second plays
  Card("5", "heart")
  second player wins the round
  ---------------------
  first plays
  Card("9", "diamond")
  second plays
  Card("5", "spade")
  first player wins the round
  ---------------------
  first plays
  Card("King", "club")
  second plays
  Card("4", "heart")
  first player wins the round
  ---------------------
  first plays
  Card("3", "spade")
  second plays
  Card("5", "heart")
  second player wins the round
  ---------------------
  first plays
  Card("9", "diamond")
  second plays
  Card("3", "spade")
  first player wins the round
  ---------------------
  first plays
  Card("5", "spade")
  second plays
  Card("5", "heart")
  **** war !

***** first player wins the game