Utiliser la note dans un shell Django

Django, keskecé ?

Django est un framework puissant écrit en Python qui permet de concevoir un site Internet modulaire avec une vision abstraite d'une base de données. Django offre l'avantage de manipuler directement des objets Python plutôt que de gérer des requêtes SQL manuellement. C'est un confort de développement en plus d'assurer un code lisible et puissant.

Un autre intérêt de Django est le fait qu'il soit codé en Python : cela permet d'ouvrir facilement un terminal et d'effectuer des requêtes et des modifications à la base de données.

Ouvrir un terminal Django

La première étape est de se connecter au serveur de la note, accès réservé aux respos info et trésoriers. Trésoriers, si vous n'avez pas de compte sur le serveur (je dis bien sur le serveur, pas sur la note en elle-même, j'espère bien qu'en tant que trésorier vous ayez un compte), adressez-vous à un respo info pour qu'il vous en crée un et qu'il vous explique comment vous connecter.

Dans un terminal (qui peut s'ouvrir sur Windows en tapant Windows+R, cmd puis Entrée, sur Linux vous savez), connectez-vous au serveur de la note en tapant ssh pseudo@note.crans.org. Sauf configuration de votre part, vous serez invités à taper votre mot de passe du serveur (encore une fois, les identifiants n'ont aucune raison d'être liés à ceux du site de la note). Une fois cela fait, vous serez connectés à la note. La ligne suivante devrait s'afficher :

pseudo@bde-note:~$ 

Déplacez-vous ensuite dans le dossier dans lequel se trouve le code de la note : cd /var/www/note_kfet/

pseudo@bde-note:~$ cd /var/www/note_kfet/
pseudo@bde-note:/var/www/note_kfet$ 

Il vous faut désormais charger l'environnement virtuel Python, qui contient l'ensemble des modules externes chargés, en plus de définir votre Python sur Python 3. Pour cela, tapez . env/bin/activate, un (env) devrait maintenant préfixer la dernière ligne de votre terminal :

pseudo@bde-note:/var/www/note_kfet$ . env/bin/activate
(env) pseudo@bde-note:/var/www/note_kfet$ 

Voilà ! Vous êtes entrés dans la note N'hésitez pas à faire un python --version pour vous assurer que vous utilisez bien Python 3.

Même si ce ne sont que deux commandes, il peut être assez pénible de les taper à chaque fois. Il est possible de les exécuter automatiquement en les insérant dans votre fichier .bashrc :

cat >> ~/.bashrc
cd /var/www/note_kfet
source /var/www/note_kfet/env/bin/activate

Il vous suffira de taper simultanément Ctrl+D, et au prochain redémarrage de votre terminal, vous serez directement dans le bon dossier et dans le bon environnement. Ah au fait, pour quitter la connexion, exécutez exit ou tapez Ctrl+D. Si pour une raison ou une autre vous souhaitez quitter l'environnement python, exécutez deactivate.

Pénétrer dans la note

Je vous ai menti. Vous n'êtes pas encore dans la note, seulement dans son environnement. Il est cependant possible d'intéragir directement avec la note en exécutant dans le bon dossier ./manage.py shell. Cela a pour effet d'ouvrir un terminal Python connecté avec la note. Cependant, il peut être assez pénible d'avoir à importer à chaque fois les bons modules, alors retenez-le, le script à exécuter en permanence est :

./manage.py shell_plus

Cette fois vous êtes vraiment dans la note, prêts à tout casser

La structure de la Note

Comme dit précédemment, tout ce qui est en base de données est représenté par des objets Python. À l'heure actuelle, voici l'ensemble des modèles (type d'objet) existant, regroupés par module :

• auth

  • User : Utilisateur inscrit sur la note

• activity

  • Activity : Activité organisée par un club BDE

  • ActivityType : Type d'activité (pot, soirée, ...)

  • Entry : Entrée à une activité (adhérent ou invité)

  • Guest : Personne invitée par un adhérent à une activité

• api

  • aucun modèle enregistré

• logs

  • Changelog : Modification effectuée dans la base de donnée à un certain instant

• member

  • Profile : Informations complémentaires liées à un utilisateur (adresse, numéro de téléphone, payé, ...)

  • Club : Détails d'un club

  • Membership : Informations sur une adhésion à un club

• note

  • Note : Objet Note générique qui contient le solde, date de dernier négatif, ...

    • NoteUser : Type de note lié à un utilisateur

    • NoteClub : Type de note lié à un club

    • NoteSpecial : Type de note utilisé lors d'un crédit/retrait

  • Alias : Champ de texte permettant de désigner une note

  • TemplateCategory : Catégorie de boutons de consommations (alcool, bouffe, ...)

  • TransactionTemplate : Boutons de consommation rapide

  • Transaction : Détails génériques d'une transaction

    • RecurrentTransaction : Transaction liée à un bouton

    • SpecialTransaction : Transaction liée à un crédit/retrait (avec nom, prénom, banque en plus)

    • MembershipTransaction : Transaction liée à une adhésion

• permission

  • Permission : Abstraction d'une permission, qui contient une requête pour déterminer si un objet à le droit de voir/ajouter/modifier/supprimer un objet, avec quel masque de permissions

  • PermissionMask : Définition des masques de permission

  • Role : Rôle d'une adhésion dans un club, définissant l'ensemble des permissions octroyées

• registration

  • Aucun modèle enregistré

• treasury

  • Invoice : Facture générée en TeX puis PDF

  • Product : Produit lié à une facture

  • RemittanceType : Type de remise, pour savoir ce qui est utile à remiser (les chèques)

  • Remittance : Remise (de chèques)

  • SpecialTransactionProxy : Afin de ne pas casser des flèches en base de données et d'éviter une dépendance trop forte du module de trésorerie, ce modèle vient juste rajouter des flèches

  • SogeCredit : Crédit de la société générale lié à un utilisateur

• wei

  • WEIClub : Surcouche du modèle Club, avec des infos en plus qui concerne le WEI (dates, ...)

  • Bus : Bus partant au WEI (nom + membres)

  • BusTeam : Équipe d'un bus WEI

  • WEIRole : Surcouche du modèle Role, n'inquant que ... le rôle est pour un WEI seulement

  • WEIRegistration : Pré-inscription d'un utilisateur à un WEI, non payée, contient les infos importantes

  • WEIMembership : Surcouche du modèle Membership ajoutant en plus les liens à l'inscription, au bus et à l'équipe

L'ensemble des classes est donc automatiquement importé lorsque vous exécutez ./manage.py shell_plus. Au besoin, chaque classe se trouve dans le module app.models en remplaçant app par le nom de l'application (note, member, ...)

How to casser la Note

J'ai une bonne et une mauvaise nouvelle. La bonne c'est qu'on en a fini avec le bash, la mauvaise c'est qu'on va pas casser la note, je tiens à son bon fonctionnement On va simplement voir comment intéragir avec elle.

Comme déjà dit, on ne va pas utiliser de SQL et utiliser la puissance de Django pour effectuer nos requêtes simplement et efficacement. On désignera dans la suite par Model le nom du modèle qui nous intéresse, la liste des modèles ayant été donnée ci-dessus.

La documentation complète de ce qui suit est disponible ici : https://docs.djangoproject.com/fr/3.1/topics/db/queries/

Le champ qui nous permet d'intéragir avec la base de données est objects. C'est le point de départ de toutes nos requêtes.

Pour récupérer l'ensemble des objets d'un modèle, on peut appeler la fonction all(). Ainsi, ActivityType.objects.all() listera l'ensemble des types d'activité enregistrés :

   1 In [1]: ActivityType.objects.all()
   2 Out[1]: <QuerySet [<ActivityType: Pot>, <ActivityType: Soirée de club>, <ActivityType: Autre>]>

Dans le fond, cela exécute la requête SELECT * FROM activity_activitytype; et transforme les résultats en objets Python (à quelque chose près).

Il est possible de compter le nombre d'objets trouvés en remplaçant all() par count() :

   1 In [2]: PermissionMask.objects.count()
   2 Out[2]: 3

Vous suivez jusqu'ici ? Tant mieux. Maintenant on va aborder la partie la plus complexe mais aussi la plus puissante : les filtres. Une requête se filtre en utilisant la fonction filter, qui prend des paramètres. Son utilisation est intuitive et se comprend par l'exemple. Pour filtrer l'ensemble des boutons qui valent 1 €, on peut exécuter par exemple TransactionTemplate.objects.filter(amount=100).all(), sans oublier le .all() à la fin pour récupérer les résultats (sans cela la requête est construite mais pas exécutée). La requête exécutée derrière est SELECT * FROM note_transactiontemplate WHERE amount = 100;.

Il est possible d'appliquer un ET simplement en rentrant plusieurs paramètres : TransactionTemplate.objects.filter(amount=100, display=True).all() récupère l'ensemble des boutons de valeur 1 € qui sont visibles (requête générée : SELECT * FROM note_transactiontemplate WHERE amount = 100 AND display = true;).

Il est important de bien comprendre cette étape. Même si j'ai un peu menti : la fonction filter attend en réalité des objets de type Q, et non pas seulement vos paramètres de filtres. L'objet Q (du module django.db.models, déjà importé) permet de filtrer vos requêtes de façon très puissante. La requête précédente se réécrit TransactionTemplate.objects.filter(Q(amount=100, display=True)).all(). Jusqu'ici, rien d'incroyable, et on comprend pourquoi il est possible d'alléger la notation en se dispensant de l'enveloppe Q. Mais tout ceci n'est pas assez pythonesque. Il est en effet possible d'utiliser les opérateurs unaires &, | et ~ pour générer vos filtres, qui se comportent comme des ET, des OU et des NON. On aurait pu écrire la même requête TransactionTemplate.objects.filter(Q(amount=100) & Q(display=True)).all(). Certes, c'est plus lourd qu'avant, mais désormais, il est possible d'utiliser des OU et des NON dans vos filtres

Bon, on arrive à faire des OU, des ET et des NON. C'est déjà bien, mais on peut faire mieux. Il est possible d'appliquer une recherche plus complexe que juste champ = valeur ! On peut par exemple chercher en ignorant la casse, ou juste chercher dans une partie du champ. Pour cela, il suffit d'ajouter __ après le nom du champ et d'ajouter l'une de ces fonctions, dont la plupart ne s'applique qu'aux chaînes de caractères, d'autres qu'à des nombres/dates :

Un petit exemple, illustrant la récupération de clubs dont le nom finit par BDE :

   1 In [3]: Club.objects.filter(name__iendswith="BDE").all()
   2 Out[3]: <QuerySet [<Club: PR2013 - BDE>, <Club: 1a - BDE>, '...(remaining elements truncated)...']>

Exemples de requêtes utiles pour les trésoriers