Première vague de questions sur la gestion des personnes.

src/people/admin.py

@@ -1,4 +1,14 @@
+"""Administration des gymnastes et des personnes.
+
+Remarks:
+    * Je ne pense pas qu'il faille encore passer par `ForeignKeyAutocompleteAdmin`.
+      https://docs.djangoproject.com/fr/3.1/ref/contrib/admin/#django.contrib.admin.ModelAdmin.autocomplete_fields
+"""
+
 from django.contrib import admin
+
+from django_extensions.admin import ForeignKeyAutocompleteAdmin
+
 from .models import (
     Gymnast,
     Accident,
@@ -7,10 +17,6 @@ from .models import (
     GymnastHasRoutine,
 )
 
-# from objective.models import Educative
-from django_extensions.admin import ForeignKeyAutocompleteAdmin
-
-
 class CanDoRelationAdmin(ForeignKeyAutocompleteAdmin):
     model = CanDoRelation
 

src/people/forms.py

@@ -1,4 +1,4 @@
-# coding=UTF-8
+"""Formulaires de gestion des données entrantes pour les gymnastes et accidents."""
 
 from django import forms
 

src/people/models.py

@@ -1,18 +1,64 @@
-# coding=UTF-8
+"""Modélisation des gymnastes, accidents et relations à faire/faites.
+
+Notes:
+    Est-ce qu'il ne faudrait pas refactoriser les GSM père/mère ?
+    Avec une table d'association, et un champ qui indique la qualité du contact ?
+    Du coup, cela permettrait se débarasser des champs phone, gsm, gsm_father et gsm_mother.
+
+    Comment sont gérées les évolutions ? Changement de clubs, de fédération,
+
+    A quoi correspond le champ `year_of_practice` ?
+    Comment se comportera-t-il dans un an ? Dans deux ans ?
+    Est-ce qu'il ne faudrait pas une date de début, plutôt ?
+
+    Idem pour la méthode `actual_year_of_pratice`.
+    Comme elle se base sur le champ `created_at`, il suffit que l'enregistrement ne soit pas
+    réalisé correctement pour que la méthode retourne une mauvaise information.
+
+    Que signifie qu'un gymnaste soit actif ou inactif ? Est-ce que cela ne devrait pas plutôt
+    être géré au niveau des utilisateurs ?
+
+    Au niveau des utilisateurs, comme un User Django a déjà les champs lastname/firstname
+    pourquoi ne pas les réutiliser ? On garde la clé OneToOne, mais on déplace dans l'autre
+    classe les champs qui peuvent l'être. `Email` s'y retrouve également.
+
+    Les relations `cando`, `haveToDo` et `have_routine` ne sont pas correctement nommées.
+    Si tu as une instance de `Gymnast`, tu devrais faire ceci :
+
+    >>> gregg = Gymnast.objects.first()
+    >>> gregg.have_routine <-- pas bien
+    >>> gregg.routines <-- ok
+
+    Idéalement, cela pourrait même être une indirection.
+
+    >>> gregg.routines <-- retourne la relation de type `have_routine`
+    >>> gregg.educatives.can_do <-- retourne les éducatifs qu'il **peut** faire
+    >>> gregg.educatives.must_do <-- retourne les éducatifs qu'il **doit** faire
+    (j'avoue ne pas tout à fait comprendre la nuance entre les deux)
+
+    <!> Tu as des fonctions qui ne sont pas du tout utilisées et qui pourrissent un peu le fichier.
+    >>> next_age() ? N'est appelé nulle part ailleurs.
+    >>> known_skills() <-- peut être récupéré directement via l'attribut `cando`
+        (du coup, tu as sans doute une piste de renommage ;-))
+"""
 
-from django.db import models
-from django.contrib.auth.models import User
 from datetime import date
-from base.models import Markdownizable
+
+from django.contrib.auth.models import User
 from django.db import models
+
 import pendulum
 
-# from location.models import Club
+from base.models import Markdownizable
 
 
 class Gymnast(Markdownizable):
-    """
-    Représente un gymnaste. En plus des données personnels (nom, prénom, date de naissance, …) un gymnaste aura une photo et une orientation (de vrille). Un gymnaste peut être actif ou inactif.
+    """Représente un gymnaste.
+
+    En plus de sa signalétique (nom, prénom, date de naissance, ...),
+    un gymnaste aura une photo et une orientation (de vrille).
+
+    Un gymnaste peut être actif ou inactif.
     """
 
     class Meta:
@@ -90,16 +136,16 @@ class Gymnast(Markdownizable):
     @property
     def next_birthday(self):
         """Définit la prochaine date (de fête) d'anniversaire pour cette personne.
-        
+
         Returns:
             Soit le jour/mois pour cette année
             Soit le jour/mois pour l'année prochaine.
-            
+
         Examples: en supposant qu'on soit le 23/05/2019
             >>> from datetime import date
             >>> gregg = People(name='Tru', firstname='Gregg', birthdate=date(1982, 2, 5)
             >>> gregg.next_birthday()
-            Date(2020, 2, 5)            
+            Date(2020, 2, 5)
         """
 
         now = pendulum.now()
@@ -149,8 +195,7 @@ class Gymnast(Markdownizable):
 
 
 class Accident(Markdownizable):
-    """
-    Classe représentant un accident. Un accident lie un saut à un gymnaste pour une date donnée.
+    """La classe `Accident` permet d'indiquer qu'un gymnaste est tombé durant un saut.
     """
 
     class Meta: