colloscope/models.py

@@ -24,18 +24,17 @@ class Classe(models.Model):
     annee = models.IntegerField()
     jour_zero = models.DateField()
 
-class Periode(models.Model):
-    classe = models.ForeignKey(Classe, on_delete=models.CASCADE)
-    #critere_colle = models.ForeignKey(Critere, on_delete=models.SET_NULL, null=True)
-    libelle = models.CharField(max_length=100)
-    debut = models.DateField()
-    fin = models.DateField()
-
-    class Meta:
-        ordering = ["debut"]
-
-
     def no_semaine(self, jour):
+        """
+        Entrées :
+        - self
+        - jour (datetime.date)
+
+        Sortie :
+        - Le numéro de la semaine contenant jour, sans compter les vacances.
+        Renvoie un numéro non spécifiée si le jour est pendant une période de vacances
+        """
+
         zone = self.classe.lycee.vacances
         vacances = calendrier[zone]
         jour0 = self.classe.jour_zero
@@ -46,10 +45,28 @@ class Periode(models.Model):
                 n -= 2
         return n
 
-    def range_semaines(self):
+    def no_aujourdhui(self):
-        return range(self.no_semaine(self.debut), self.no_semaine(self.fin)+1)
+        """
+        Entrée:
+        - self
+
+        Sortie:
+        - Le numéro de la semaine courante
+        """
+
+        return self.no_semaine(date.today())
+
 
     def date_debut_sem(self, n):
+        """
+        Entrée:
+        - self
+        - n (int) <-> numéro de semaine
+
+        Sortie:
+        - Le date du lundi de la semaine n
+        """
+        
         zone = self.classe.lycee.vacances
         vacances = calendrier[zone]
         jour0 = self.classe.jour_zero
@@ -62,6 +79,41 @@ class Periode(models.Model):
 
         return jour
 
+    def periode(self, jour):
+        """
+        Entrées :
+        - self
+        - jour (datetime.date)
+
+        Sortie :
+        - La période (si elle existe et est unique) contenant jour
+
+        Exceptions:
+        - Le jour n'est pas dans une période
+        - Le jour est au chevauchement de deux périodes
+        """
+        return Periode.objects.get(classe=self, debut__lte=jour, fin__gte=jour)
+
+
+class Periode(models.Model):
+    classe = models.ForeignKey(Classe, on_delete=models.CASCADE)
+    #critere_colle = models.ForeignKey(Critere, on_delete=models.SET_NULL, null=True)
+    libelle = models.CharField(max_length=100)
+    debut = models.DateField()
+    fin = models.DateField()
+
+    class Meta:
+        ordering = ["debut"]
+
+    def range_semaines(self):
+        """
+        Entrée:
+        - self
+
+        Sortie:
+        - Un range des numéros de semaine
+        """
+        return range(self.classe.no_semaine(self.debut), self.classe.no_semaine(self.fin)+1)
 
 class Matiere(models.Model):
     classe = models.ForeignKey(Classe, on_delete=models.CASCADE)
@@ -94,15 +146,24 @@ class Etudiant(models.Model):
     #lv2 = models.ForeignKey(Matiere, on_delete=models.CASCADE)
 
     def appartient(self, groupe):
+        """
+        Renvoie si self appartient au groupe.
+        """
         return Appartenance.objects.filter(etudiant=self, groupe=groupe).exists()
 
     def groupe_du_critere(self, periode, critere):
+        """
+        Renvoie le groupe du critère auquel self appartient.
+        """
         if isinstance(critere, str):
             critere = Critere.objects.get(periode=periode, libelle=critere)
 
         return Appartenance.objects.get(groupe__periode=periode, etudiant=self, groupe__critere=critere).groupe
 
     def groupe_de_colle(self, periode):
+        """
+        Renvoie le groupe de colle de self pendant periode.
+        """
         return self.groupe_du_critere(periode, "colle")
 
 class Appartenance(models.Model):
@@ -130,9 +191,15 @@ class Rotation(models.Model):
     semaine = models.IntegerField()
 
     def groupe_initial(self):
+        """
+        Renvoie les étudiants inscrits à la colle sans prendre en compte les amendements.
+        """
         return Etudiant.objects.filter(id__in=Appartenance.objects.filter(groupe__in=self.groupes.all()))
 
     def groupe_effectif(self):
+        """
+        Renvoie les étudiants inscrits à la colle en tenant compte des amendements.
+        """
         amendements=Amendement.objects.filter(rotation=self)
 
         return Etudiant.objects.filter(
@@ -142,6 +209,9 @@ class Rotation(models.Model):
         )
 
     def effectif(self):
+        """
+        Renvoie le nombre d'étudiants inscrits à la colle en tenant compte des amendements.
+        """
         n_base = sum(len(groupe.membres()) for groupe in self.groupes.all())
         n_plus = len(Amendement.objects.filter(est_positif=True, rotation=self))
         n_moins = len(Amendement.objects.filter(est_positif=False, rotation=self))
@@ -149,27 +219,36 @@ class Rotation(models.Model):
         return n_base + n_plus - n_moins
 
     def est_pleine(self):
+        """
+        Renvoie si la colle est pleine.
+        """
         eff = self.effectif()
         return eff>=self.creneau.capacite
 
     def est_modifiee(self):
+        """
+        Renvoie si la colle a été amendée.
+        """
         return Amendement.objects.filter(rotation=self).exists()
 
     def amender(self, etudiant, est_positif):
-        # check annulation
+        """
+        Amende la colle en (des)inscrivant etudiant à la colle self, selon est_positif.
+        """
 
         if Amendement.objects.filter(rotation=self, etudiant=etudiant, est_positif=est_positif).exists():
             raise Exception("Duplication")
         elif Amendement.objects.filter(rotation=self, etudiant=etudiant, est_positif=not est_positif).exists():
+            # les amendements complémentaires s'annulent
             Amendement.objects.get(rotation=self, etudiant=etudiant, est_positif=not est_positif).delete()
         elif est_positif and any(etudiant.appartient(groupe) for groupe in self.groupes.all()):
+            # on ne peut pas s'ajouter si on est dans le groupe de base
             raise Exception("Vous êtes déjà dans le groupe")
         elif not est_positif and all(not etudiant.appartient(groupe) for groupe in self.groupes.all()):
             raise Exception("Vous n'êtes pas dans le groupe")
         elif est_positif and self.est_pleine():
             raise Exception("Capacité dépassée")
         else:
-            # on ne peut pas s'ajouter si on est dans le groupe de base
             amendement = Amendement(rotation=self, etudiant=etudiant, est_positif=est_positif)
             amendement.save()