Comment faire tourner une structure de projet avec Cookiecutter

vous êtes comme moi, « procrastination » pourrait tout aussi bien être votre deuxième prénom. Il y a toujours cette hésitation lancinante avant de démarrer un nouveau projet. Il suffit de penser à mettre en place la structure du projet, à créer de la documentation ou à rédiger un README décent pour déclencher des bâillements. C’est comme regarder une page blanche pour un devoir scolaire redouté. Mais rappelez-vous à quel point cela devient plus facile une fois qu’un LLM utile (comme ChatGPT) fournit un modèle de départ ? La même magie peut s’appliquer à vos projets de codage. C’est là qu’intervient Cookiecutter.

Qu’est-ce que l’emporte-pièce ?

Emporte-pièce est un outil open source qui vous aide à créer des modèles de projet. Il est indépendant du langage et fonctionne avec pratiquement n’importe quel langage de programmation (ou même en dehors du codage, si vous avez besoin d’une structure de dossiers et de fichiers standardisée). Avec Cookiecutter, vous pouvez configurer tous les fichiers passe-partout (comme les README, les Dockerfiles, les répertoires de projets ou tout autre élément), puis générer rapidement de nouveaux projets basés sur cette structure.

Le flux de travail Cookiecutter comprend trois étapes principales :

1. Vous définissez votre modèle de projet.
2. L’utilisateur saisit les valeurs des variables que vous spécifiez.
3. Cookiecutter génère un nouveau projet, remplissant automatiquement les fichiers, dossiers et valeurs de variables en fonction de la saisie de l’utilisateur.

L’image suivante illustre ce processus :

1. Configuration de base de l’ordinateur

Vous avez besoin de compétences minimales en programmation pour installer et utiliser Cookiecutter. Si vous pouvez ouvrir une fenêtre de ligne de commande, vous êtes prêt à partir.

• Sous Windows, tapez « cmd » dans la barre de recherche et ouvrez « l’invite de commande ».

• Si ce n’est pas déjà fait, installez pipx avec :

pip install pipx

Testez votre installation en exécutant :

pipx --version

Si vous obtenez une erreur « commande introuvable », ajoutez pipx à votre PATH. Tout d’abord, recherchez où pipx a été installé : python -m site –user-base.

Cela pourrait renvoyer quelque chose comme /home/username/.local. Recherchez le dossier contenant pipx.exe (sous Windows) ou pipx (sous macOS ou Linux). Si vous n’avez aucun droit d’administrateur, le répertoire peut être C:\Users\username\AppData\Roaming\Python\Pythonxxx\Scripts.

J’ai dû ajouter pipx à mon chemin et si vous n’avez pas de droits d’administrateur, vous devrez le faire à chaque fois que vous démarrez une nouvelle fenêtre de terminal. Il est donc recommandé d’ajouter l’emplacement de manière permanente à vos paramètres de variables d’environnement. Cependant, si ce paramètre est derrière les privilèges d’administrateur, vous pouvez toujours ajouter

set PATH=C:\Users\username\AppData\Roaming\Python\Pythonxxx\Scripts;%PATH%

Ou

set PATH=/home/username/.local/bin;%PATH%

J’espère que vous obtiendrez une réponse significative pour pipx --version maintenant.

2. Installation et configuration de Cookiecutter

Cookiecutter est distribué sous forme de package Python, vous pouvez donc l’installer avec pipx :

pipx install cookiecutter

Ou exécutez-le simplement à la volée avec :

pipx run cookiecutter ...

Passons en revue la création d’un modèle de projet. Dans cet exemple, nous allons configurer un modèle pour les applications Streamlit (cookiecutter_streamlit_ml).

3. Création de la structure du modèle

Dans votre dossier cookiecutter_streamlit_ml, vous avez besoin de ces deux composants clés :

• cookiecutter.json – un fichier JSON qui définit les variables que vous souhaitez que les utilisateurs remplissent (nom du projet, auteur, version Python, etc.).

• {{ cookiecutter.directory_name }} – Un nom de dossier réservé défini à l’aide d’accolades. Ce répertoire contiendra la structure et les fichiers de votre projet. Lorsque l’utilisateur crée un nouveau projet à partir de votre modèle, Cookiecutter remplacera cet espace réservé par le nom qu’il a fourni. Attention à conserver les accolades !

Votre cookiecutter.json pourrait ressembler à ceci :

Tout d’abord, vous définissez les variables dans cookiecutter.json qui sont utilisées tout au long du projet généré. Au minimum, vous aurez besoin d’une variable pour le nom du projet.

Par exemple, je fais souvent référence à mon référentiel GitHub dans la documentation. Plutôt que de la saisir à plusieurs reprises, je définis une variable une fois et laisse Cookiecutter remplir automatiquement chaque instance. De même, je ne souhaite pas écrire mon nom dans chaque fichier Lisez-moi ou fichier de documentation, je le définis donc au début.

Pour éviter les problèmes avec Docker et m’assurer que la version correcte de Python est spécifiée, je demande la version de Python lors de la création du projet, en m’assurant qu’elle est utilisée dans le fichier Docker généré.

Vous pouvez définir des valeurs par défaut pour chaque champ dans cookiecutter.json. Cookiecutter remplacera automatiquement chaque instance de {{ cookiecutter.variable }} dans vos fichiers de modèle par la saisie de l’utilisateur. Vous pouvez également utiliser des transformations comme lower() ou replace(‘ ‘, ‘_’) pour éviter les problèmes avec les espaces dans les noms de répertoires.

Dans mon modèle, je préfère fournir des instructions détaillées aux utilisateurs plutôt que de définir des valeurs par défaut. Cela aide à guider ceux qui pourraient sauter la lecture du README et passer directement à la création de projet.

4. Créer votre modèle

Commence maintenant la partie amusante, à savoir définir votre modèle. Vous le faites une fois pour toutes, cela vaut donc la peine d’y consacrer du temps, ce qui réduira considérablement le temps de configuration de votre projet à long terme.

Tout d’abord, créez la structure des dossiers de votre projet. Cela inclut la création de tous les dossiers que vous comptez utiliser dans votre projet. Ne vous inquiétez pas, tout ce qui manque ou s’avère superflu peut être modifié dans le projet lui-même. Pour l’instant, vous créez simplement le plan ; les sifflets et les cloches seront spécifiques au projet.

Une fois vos dossiers prêts, vous pouvez les remplir avec des fichiers. Ceux-ci peuvent être vides ou même contenir du contenu que vous pourriez autrement copier-coller constamment à partir d’autres documents. Dans ces fichiers, faites référence à vos variables cookiecutter partout où quelque chose doit être défini dynamiquement (par exemple, le nom du projet ou le dépôt GitHub). Cookiecutter remplacera automatiquement ces espaces réservés par les entrées de l’utilisateur, qui seront demandées lors de la configuration du projet. Cela vous épargne de nombreux copier-coller fastidieux, notamment dans vos fichiers de documentation.

Enfin, déposez l’intégralité du dossier cookiecutter_py_streamlit dans votre compte GitHub, compressez-le ou laissez-le tel quel. Quoi qu’il en soit, vous pouvez désormais…

5. Utilisez votre modèle

Une fois votre modèle prêt, créer un nouveau projet devient un jeu d’enfant :

1. Ouvrez votre terminal et accédez à l’endroit où vous souhaitez créer le projet.

2. Exécutez l’une des commandes suivantes :

• Depuis GitHub :

pipx run cookiecutter gh:ElenJ/cookiecutter_streamlit_ml  (replace with your repo)

• Depuis un dossier local :

pipx run cookiecutter /path/to/template_folder

• À partir d’un zip :

pipx run cookiecutter /path/to/template.zip

3. Cookiecutter vous posera les questions définies dans cookiecutter.json. Fournissez des réponses ou appuyez simplement sur Entrée si vous avez défini des valeurs par défaut.

4. Voilà 🎉 votre nouveau dossier de projet est généré, complet avec des dossiers, des fichiers et des références personnalisés en fonction de vos entrées.

Vous pouvez synchroniser votre nouveau projet avec GitHub soit en le poussant directement à partir de la fonctionnalité Git intégrée de votre IDE, soit en créant un nouveau dépôt sur GitHub (en vous assurant qu’il est vide et n’inclut pas de fichier Readme), puis en y déplaçant votre dossier de projet généré.

Et c’est tout ! Vous avez transformé ce qui était autrefois une corvée d’une journée en un processus rapide et avez généré instantanément de nombreux fichiers attendant d’être remplis avec vos idées. En regardant le nouveau projet, vous devriez certainement avoir le sentiment d’une journée productive. Si vous cherchez toujours des conseils sur les meilleures pratiques, consultez le site officiel Modèles de coupe-biscuits ici.

Et comme toujours : Bon codage !