Activité pratique

Consignes globales

Cette activité pratique a pour but de vous préparer au projet PyRat. Elle consiste en trois grandes parties :

• Vous allez installer le logiciel.
• Vous allez mettre en place un dépôt Git, afin de travailler efficacement en groupe.
• Enfin, vous serez guidé(e)s dans l’écriture de votre premier programme PyRat.

Cette mise en place peut être assez longue, mais elle est essentielle pour bien attaquer le projet. Si vous ne parvenez pas à tout faire dans la séance, terminez en dehors avant la prochaine.

N’oubliez pas que nous pouvons vous aider entre les séances via le serveur Discord du cours. Vous devriez dès à présent le rejoindre si ça n’est pas déjà fait.

Contenu de l’activité

Où trouver PyRat ?

Le plus important à connaître est le site principal du logiciel PyRat, qui centralise tous les éléments de prise en main :

• Documentation : Cette page regroupe les éléments de documentation sur comment installer et utiliser PyRat. La documentation présente aussi l’API PyRat, c’est à dire les classes et fonctions fournies par la bibliothèque. Nous y avons également ajouté quelques tutoriels, qui constituent la base de cette activité pratique.

  Important

  Comme pour la plupart des logiciels que vous rencontrerez dans votre vie, le code et la documentation de PyRat sont rédigés en anglais. Dans ce projet, nous vous demandons de produire vos codes, commentaires et documentations en anglais également. C’est une pratique essentielle dans le métier d’ingénieur(e), où vous serez amené(e)s à travailler dans des contextes internationaux.

Voici également quelques liens secondaires, qui pourront vous être utiles plus tard :

• PyPI : La page de référence du paquet pyrat-game, c’est-à-dire la bibliothèque PyRat telle qu’elle sera téléchargée et installée dans votre workspace.

• GitHub : Ce dépôt GitHub contient les codes sources du logiciel PyRat. Quand nous travaillons à une nouvelle version du logiciel, c’est là que nos modifications sont publiées.

• GitHub issues : Les issues GitHub sont une sorte de forum, où sont discutés les possibles problèmes rencontrés par les utilisateurs lors de l’installation ou l’utilisation du logiciel. C’est une bonne pratique de consulter cette page si vous rencontrez des difficultés.

Préparer l’environnement du projet

Dans cette section, nous allons préparer l’environnement de travail pour le projet PyRat. PyRat automatise une grande partie de l’installation via uv.

Dans ce projet, nous allons travailler avec l’IDE VSCode. Vous pouvez en utiliser un autre si vous préférez, il vous suffira d’adapter les instructions.

Vérifier que uv est installé

Télécharger et installer PyRat

PyRat s’installe facilement grâce à uvx, un outil fourni avec uv qui permet d’exécuter des programmes distribués via PyPI, sans avoir besoin de créer un environnement virtuel au préalable.

La commande d’installation devrait créer un dossier pyrat_workspace, contenant vos dossiers players et games. Ce pyrat_workspace est un projet uv muni d’un environnement virtuel (.venv) dans lequel la bibliothèque pyrat-game est installée.

Lors de son installation, PyRat configure également le PATH de l’environnement virtuel pour que les programmes des dossiers players et games soient trouvés par l’interpréteur python. Ainsi, les scripts qui lancent les parties (dans games) peuvent importer les classes des joueurs (dans players) via from players.random1 import Random1.

Vérifier l’installation de PyRat

Une fois PyRat installé, démarrez VSCode, et ouvrez le dossier pyrat_workspace (celui qui contient pyproject.toml).

Via l’arborescence à gauche, ouvrez le fichier games/sample_game.py, et exécutez le. Vous devriez constater que VSCode utilise bien l’environnement virtuel du projet, et que la partie se lance.

Préparer le travail en groupe

Avant de démarrer cette activité pratique, vous avez dû former un trinôme. Si ça n’est pas le cas, faites le maintenant.

À ce stade, chacun(e) d’entre vous a installé PyRat sur sa propre machine et a son propre pyrat_workspace qui fonctionne. À présent, nous allons créer un projet collaboratif, via un dépôt Git sur le GitLab de l’école.

On suppose que vous avez déjà toutes et tous un compte sur ce GitLab, et que vous y avez déposé une clé SSH, comme demandé à l’issue de la séance sur le travail à plusieurs avec Git et GitLab.

Nous allons à présent créer un dépôt Git sur lequel vous pourrez travailler à plusieurs. Bonne nouvelle : votre workspace est déjà dans un dépôt Git, car uv en a créé un au moment de l’installation. Il contient également un fichier .gitignore, fourni par PyRat, qui exclut d’office les fichiers qui ne doivent pas être versionnés, comme l’environnement virtuel .venv, les dossiers temporaires __pycache__, ou les fichiers créés par votre éditeur et votre système d’exploitation.

Vérifiez tout de même qu’un dossier .git existe bien à la racine de pyrat_workspace (par exemple en lançant git status depuis ce dossier). Si ce n’est pas le cas, par exemple parce que votre dossier projet est lui-même déjà dans un dépôt Git, lancez d’abord git init dans pyrat_workspace.

Créer le projet

Qui ? Le/La boss seulement.

Sur https://gitlab-df.imt-atlantique.fr, créez un projet privé du nom de votre choix. Pensez à décocher la case “Initialize repository with a README”.

Copiez ensuite le lien de clonage du projet (en SSH ou en HTTPS). Il vous sera demandé à l’étape suivante.

Publier le workspace

Qui ? Le/La boss seulement.

Placez-vous dans votre dossier pyrat_workspace avec un terminal, puis effectuez les commandes suivantes (remplacer url_de_clonage_du_projet par le lien copié à l’étape précédente) :

# Préparez l'envoi des fichiers du workspace
git add .
git commit -m "Initialisation du dépôt avec le workspace"
git branch -M main

# Liez le dossier local au repo GitLab
git remote add origin url_de_clonage_du_projet

# Seulement si vous avez oublié de décocher "Initialize repository with a README"
# Nettoie le repository distant
git fetch origin
git reset --soft origin/main
git commit -m "Remplacement du contenu existant"

# Envoyez
git push -u origin main

Rechargez la page du projet sur GitLab : vos fichiers doivent y être. Vérifiez au passage que le dossier .venv n’y est pas, mais que pyproject.toml et uv.lock y sont bien.

Inviter les autres membres et l’enseignant(e)

Qui ? Le/La boss seulement.

Cliquez sur “Members” dans le menu, puis ajoutez les autres membres du groupe et l’enseignant(e) avec le rôle Maintainer.

Récupérer le dépôt

Qui ? Les autres membres du groupe.

Supprimez le dossier pyrat_workspace que vous aviez créé à l’installation. Puis, depuis le dossier projet (ou autre, selon ce que vous avez choisi), clonez celui du groupe (cela créera un dossier du nom de votre projet, nom_du_depot dans les commandes ci-dessous) et préparez-le :

# Récupérer le dépôt
git clone url_de_clonage_du_projet

# Recréer l'environnement PyRat
cd nom_du_depot
uv sync

Le dépôt que vous venez de cloner ne contient pas d’environnement virtuel (car il n’était pas sur GitLab grâce au .gitignore). uv sync le crée sur la vôtre, tel que décrit par pyproject.toml et uv.lock, et y installe les dépendances du projet (ici, notamment pyrat-game, ainsi que votre workspace lui-même).

Vérifier que tout marche

Qui ? Tout le monde.

Depuis votre dossier nom_du_depot, lancez :

uv run games/sample_game.py

Une partie de PyRat doit se lancer. Si c’est le cas, votre workspace est correctement installé et connecté au dépôt du groupe.

Ouvrez également le menu Source control de VSCode : votre dépôt Git doit être détecté, et VSCode vous propose de gérer vos add, commit, push et pull directement via son interface.

# Récupérer le travail des autres avant de commencer à travailler
git pull

# Enregistrer votre travail et le partager avec le groupe
git add .
git commit -m "message décrivant vos changements"
git push

Un premier exemple de travail collaboratif

Dans tout projet informatique, il est important d’avoir un petit fichier qui explique succinctement (ou pas) à quoi sert le projet. On appelle ce fichier un “README”, et on y trouve généralement les adresses de contact des auteur(e)s, les instructions d’utilisation du projet, etc.

Sur les dépôts Git, ce fichier s’appelle classiquement README.md, car on rédige son contenu en Markdown, un langage permettant de formater du texte. Si vous avez déjà utilisé des outils comme Discord, (ou Mattermost, Slack, etc.), c’est généralement ce langage qui est utilisé pour mettre du texte en gras, italique, etc.

Par défaut, le README de votre projet contient des informations de base sur ce qu’est un workspace PyRat. Nous allons y ajouter la liste du groupe pour l’exemple.

Compléter le README

Qui ? Le/la Big Boss seulement.

Le/la Big Boss ajoute les noms de ses coéquipiers dans le fichier README.md, par exemple dans une nouvelle section Students au début de celui-ci :

# Students

- <First name> <Name> <mail@imt-atlantique.fr>
- <First name> <Name> <mail@imt-atlantique.fr>
- <First name> <Name> <mail@imt-atlantique.fr>

Il/elle s’arrange pour que le fichier README.md modifié apparaisse sur le dépôt.

Récupérer le fichier modifié

Qui ? Les autres membres du groupe.

Le but est de manipuler Git (via l’interface VSCode ou la ligne de commande) pour que chaque étudiant(e) du groupe ait une vue locale à jour du dépôt dans son workspace.

C’est parti !

Se familiariser avec PyRat

A ce stade, tout est prêt pour commencer le projet ! Découvrons à présent en quoi consiste le logiciel PyRat. Avant d’attaquer la création de programmes PyRat, jetez un oeil aux liens suivants.

• Découverte de PyRat : Ce lien présente PyRat dans les grandes lignes, à savoir le contenu de votre workspace et de la bibliothèque Python pyrat-game, les éléments de jeu, etc.

• Tutoriels de base : Sur cette page, nous vous proposons quelques tutoriels à suivre, qui détaillent les programmes PyRat fournis par défaut dans votre workspace, et vous expliquent comment customiser les éléments de jeu.

Votre premier programme PyRat

L’objectif de cette activité pratique est d’écrire vos premiers codes PyRat, c’est à dire :

• Un joueur, sous la forme d’une classe héritant de Player. On stockera les fichiers décrivant les joueurs dans le dossier players.
• Un script, qui lance une partie avec votre joueur. On stockera les fichiers décrivant les scripts dans le dossier games.

Description de la stratégie

Le programme que nous allons écrire (Random5) est une amélioration de Random4, décrit dans le tutoriel sur les programmes RandomX.

En bref, Random4 est un programme qui :

• Au début de la partie, raye les culs de sac de la carte pour ne pas s’y diriger.
• Puis, à chaque tour de jeu :
  • Détermine les cases adjacentes au personnage qui n’ont pas encore été visitées dans la partie. Il en choisit une aléatoirement, et s’y déplace.
  • Si toutes les cases adjacentes ont déjà été visitées, le personnage choisit une case adjacente au hasard, et s’y déplace.

L’un des problèmes de Random4 est que, si le rat arrive dans une zone du labyrinthe où il a visité toutes les cases voisines, sa stratégie pour en sortir n’est pas optimisée. En effet, le rat choisit une case adjacente au hasard, et s’y déplace, en espérant atteindre une case du labyrinthe voisine de cases pas encore visitées pour améliorer le tour suivant.

On pourrait améliorer cet aspect du programme en gardant en mémoire notre trajectoire, c’est à dire la suite de cases parcourues jusqu’au tour en cours. Ainsi, en arrivant sur une case dont on a déjà visité toutes les cases voisines, il suffirait de revenir en arrière le long de la trajectoire parcourue. Si on arrive sur une case dont on a déjà visité tous les voisins, on recommence, etc. À un moment, à force de revenir sur ses pas, le rat finira par arriver sur une case ayant au moins une case voisine inexplorée, et pourra reprendre sa quête de fromage.

Création du joueur

Création de la partie

1. Importer la classe Random5 que vous venez de créer.

2. Créer une partie de PyRat (une instance de la classe Game), contenant 1 morceau de fromage. Pensez aussi à mettre une valeur élevée à l’argument trace_length pour vérifier plus tard que le rat revient bien sur ses traces.

3. Instancier un joueur de la classe Random5, et l’ajouter à la partie.

4. Démarrer la partie.

Implémentez la stratégie

N’hésitez pas à lancer régulièrement votre script visualize_random5.py, par exemple pour afficher la trajectoire parcourue, ou pour vérifier que votre code ne crashe pas.

Vous devriez obtenir un rat qui se comporte comme suit. En particulier, il ne devrait pas aller dans des culs de sac (amélioration apportée par Random4), et devrait revenir sur ses pas quand toutes les cases voisines sont déjà visitées.

Évaluez la stratégie

Maintenant que vous avez une nouvelle stratégie, il faut se poser la question de si elle est vraiment efficace. Pour cela, une approche possible est de la comparer à d’autres méthodes.

Pour aller plus loin

Le joueur Random6

Description de la stratégie

Quand Random5 arrive à un croisement amenant à plusieurs cases voisines non visitées, le rat choisit une case aléatoirement parmi celles-ci et s’y dirige.

Imaginons le cas trivial où il n’y a aucun mur, on se dit alors que les directions se rapprochant le plus du fromage (à vol d’oiseau) sont les plus intéressantes. Comme en PyRat on bouge sur une grille, mieux vaut aller vers le nord ou l’est si le fromage est au nord-est. Une stratégie intéressante serait alors de trier les cases voisines non visitées par ordre croissant de distance au fromage, et de privilégier la première.

Implémentez et évaluez la stratégie

Vous devriez observer quelque chose comme ça :

Les cas limites

On se posait précédemment la question de si le nombre de murs pouvait poser problème.

On avait déjà parlé de significativité dans le tutoriel, n’hésitez pas à relire cette partie.

Remarques

Si vous avez suivi toutes les étapes, vous devriez vous rendre compte que votre programme ne comporte plus d’aléatoire du tout !

Une autre remarque est que la distance Euclidéenne utilisée pour trier les voisins non visités ne prend pas en compte la topologie du labyrinthe, ni la boue. Cela s’observe dans la vidéo plus haut, où on voit bien que la portion de chemin 82 -> 95 -> 94 aurait été plus courte que 82 -> 81 -> 94. Il faudra donc passer à des stratégies plus intelligentes pour trouver des chemins plus courts.

Pour aller encore plus loin

Le joueur Random7

La plupart du temps, le fromage va se trouver en diagonale par rapport au rat (par exemple au nord-ouest). Conceptuellement, dans un labyrinthe sans murs, ça ne change pas grand chose d’aller au nord puis à l’ouest, ou d’aller à l’ouest puis au nord. La boue dans le labyrinthe change toutefois cette équivalence. C’est un phénomène que nous avons décrit dans les remarques sur Random6 plus haut.

On pourrait donc améliorer Random6 comme suit : si deux actions réduisent la distance au fromage, on privilégie celle qui amène à la case suivante en un minimum de tours.

Vous devriez observer quelque chose comme ça :

Suivre le mur

On dit parfois que quand on est perdu dans un labyrinthe, il suffit de poser une main sur un mur, et d’avancer sans jamais décoller sa main. On teste ?

Factoriser tout ça

Maintenant que vous avez codé 7 programmes aléatoires, vous devez vous apercevoir qu’il y a un certain nombre de redondances dans vos codes. En particulier, la fonction remove_dead_ends(...) introduite à partir de Random4 apparaît probablement dans tous les fichiers développés par la suite, vu que ce pré-traitement est relativement indépendant de la stratégie de déplacement.

Maintenant, imaginons que vous découvriez une erreur dans le code de cette fonction. Pour la corriger, il va falloir fouiller dans tous vos fichiers pour changer toutes les copies de remove_dead_ends(...). C’est problématique, car vous allez perdre du temps, et peut-être introduire de nouvelles erreurs sans faire exprès…