Introduction

Pour la petite histoire, l’année dernière je lisais l’article de deblan sur la création d’un modèle de script Shell sur le journalduhacker. Cela m’a rappelé que tôt ou tard dans la quête de l’automatisation on arrive toujours à faire nos propres modèles de scripts.

La plupart de mes projets utilisent le modèle de script Trognon.

Comment, en partant de ce modèle, pourrais-je automatiser la création de nouvelles commandes ? C’est là qu’entre en jeu cookiecutter, une commande et une méthode permettant de transformer n’importe lequel de vos projet en template pour les suivants !

Nous commencerons par voir le résultat de l’adaptation d’un script avec cookiecutter. Ensuite nous verrons ce qu’est cookiecutter. Finalement nous expliquerons comment adapter son projet avec cookiecutter en présentant le cas pratique de cookiecutter-trognon.

Des lapins de Pâques en chocolat, industrialisés et dupliqués à l’infini

Photo trouvée sur le profil de Alan Levine sur Flickr sous Domaine public.

Le résultat : cookiecutter-trognon

Pour une fois nous commencerons par la fin, c’est à dire le résultat ! L’automatisation de Trognon a donné un dépôt : cookiecutter-trognon.

Grâce à lui, créer un nouveau script Bash suivant le modèle de Trognon revient à taper les commandes suivantes :

# Installe cookiecutter sur notre machine (à ne faire que la première fois)
pipx install cookiecutter
# Utilise mon dépôt Github de cookiecutter-trognon comme modèle
cookiecutter gh:blankoworld/cookiecutter-trognon

Ensuite 2 questions sont posées pour définir :

  • le nom du dossier dans lequel ma commande se trouvera
  • le nom souhaité pour la commande

Évidemment j’ai défini les questions à poser et ce que je faisais des réponses dans le résultat. C’est là tout l’intérêt de cookiecutter : vous définissez les questions à poser, les réponses possibles s’il en est, quoi faire des réponses et où les utiliser dans vos templates.

Voyons donc cookiecutter.

Présentation de cookiecutter

cookiecutter est un outil Python qui duplique un répertoire, vous pose des questions et modifie le duplicat en remplaçant certaines chaînes de caractères par les réponses données aux questions.

Il sait agir de manière conditionnelle : c’est-à-dire qu’il peut aussi ajouter/enlever des pans de code/texte en fonction de la valeur d’une variable. Ceci grâce au moteur de template Jinja.

Autrement dit : vous définissez les fichiers dont vous avez besoin (parfois un copier/coller suffit), puis vous insérez dans vos fichiers des chaînes de caractères que vous souhaitez remplacer dans le projet. Vous pouvez également définir des valeurs conditionnelles. Par exemple : si je souhaite avoir une licence MIT, alors le fichier LICENSE contiendra un certain texte. Si je choisis la licence LPRÀB/WTFPL, alors j’aurais un autre texte.

Un exemple concret serait plus parlant, essayons avec cookiecutter-trognon !

Comment transformer Trognon en cookiecutter-trognon ?

En rapide

Pour rendre un projet compatible avec cookiecutter, il va falloir suivre quelques étapes clés :

  1. Créer un nouveau répertoire pour votre projet,
  2. Y créer un fichier nommé cookiecutter.json,
  3. Créer un répertoire nommé {{ cookiecutter.project_slug }} (oui oui, AVEC les accolades),
  4. Déposer les fichiers nécessaires au projet dans le répertoire {{ cookiecutter.project_slug }},
  5. Remplacer dans les fichiers tous les mots à adapter à chaque nouveau projet : pour cela utiliser les mots clés fournis dans le fichier cookiecutter.json (variables).

Dans le cas de Trognon, j’ai déposé les fichiers du projet dans le répertoire {{ cookiecutter.project_slug }}.

cookiecutter.json, la configuration du projet

J’ai ensuite rempli le fichier cookiecutter.json tel que montré ici :

{
  "project_name": "Mon projet",
  "__project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '_').replace('-', '_') }}",
  "command_shortname": "CommandePrincipale",
  "__command_slug": "{{ cookiecutter.command_shortname.lower().replace(' ', '_').replace('-', '_') }}",
  "__prompts__": {
    "project_name": "Choisissez un nom de projet court",
    "command_shortname": "Que voudriez-vous comme nom court de commande ?"
  }
}

Je défini des variables comme :

  • project_name : le nom du projet, avec comme valeur par défaut Mon projet,
  • command_shortname : le nom de la commande Bash que nous utiliserons.

D’autres variables ne demanderont rien à l’utilisateur car elles commencent par deux espaces soulignes __. Je parle bien entendu de __project_slug, __command_slug et __prompts__.

Cependant __prompts__ a une particularité : il permet de personnaliser la question posée pour chaque variable.

Ainsi pour définir project_name, l’utilisateur verra la question suivante : Choisissez un nom de projet court.

Remplacer des mots par des variables

Maintenant que le fichier cookiecutter.json possède des mots clés spécifiques (des variables), nous allons pouvoir modifier les fichiers de notre projet pour contenir des « mots-clés ». Par exemple voici le début du fichier README.md de Trognon (AVANT modifications) :

# Trognon

Un lanceur de commandes personnalisées pour votre projet de développement.

Exemple : 

# Affiche l'aide
./agnes help

# Installe votre projet (vous devez définir ce que `install` fait)
./agnes install

# créé un dump de la base de données
./agnes dump

Ce qui donne le fichier README.md suivant dans notre projet cookiecutter-trognon (APRÈS modifications) :

# {{ cookiecutter.project_name }}

Un lanceur de commandes personnalisées pour votre projet de développement.

Exemple : 

# Affiche l'aide
./{{ cookiecutter.__command_slug }} help

# Installe votre projet (vous devez définir ce que `install` fait)
./{{ cookiecutter.__command_slug }} install

# créé un dump de la base de données
./{{ cookiecutter.__command_slug }} dump

Nous avons ainsi remplacé respectivement le titre du fichier et les commandes d’exemple en {{ cookiecutter.project_name }} et {{ cookiecutter.__command_slug }}.

Vous pouvez en savoir plus sur la documentation officielle de cookiecutter.

Conclusion

J’espère qu’à travers cet article vous aurez compris l’avantage d’utiliser cookiecutter et que vous envisagerez à l’avenir de l’intégrer dans votre processus d’automatisation de la génération initiale de vos projets et de vos scripts.

L’informatique énonce souvent d’éviter de réinventer la roue ; je pense que cookiecutter est l’outil indispensable pour favoriser ce concept.

Une fois ce processus de création automatisé, vous vous rendrez compte que vous générerez plus souvent des scripts/projets, que vous vous concentrerez uniquement sur le contenu du projet et pas sur tout l’environnement autour : c’est un gain de temps et de qualité ! Une belle valeur ajoutée en somme.