Another Step in the Quest to clean up the code base.

src/maistar_ranking/models.py

@@ -1,4 +1,4 @@
-# -*- encoding: utf-8 -*-
+"""ORM Models for the Mai-Star ranking"""
 
 import logging
 
@@ -7,15 +7,13 @@ from django.db import models
 from django.utils.translation import ugettext as _
 
 from events.models import Event
-from membership.models import Membership
 from . import settings, managers
 
 
 class Game(models.Model):
-    """
-    Ein kompettes Spiel Mai-Star bestehend aus 6 Spielern
-    """
+    """to record a complete game with 6 different players."""
 
+    _player_list = list()
     event = models.ForeignKey(Event, related_name='maistargame_set')
     comment = models.TextField(_('Comment'), blank=True)
     player1 = models.ForeignKey(
@@ -71,34 +69,29 @@ class Game(models.Model):
         )
 
     def get_absolute_url(self):
-        """
-        URL zur Hanchanliste des Events wo diese Hanchan gelistet wurde.
-        """
+        """URL to the event subpage that lists the Mai-Star games."""
         url = reverse('maistar-game-list',
                       kwargs={'event': self.event.pk})
         return u'%(url)s#%(pk)d' % {'url': url, 'pk': self.pk}
 
     @property
     def player_list(self):
-        try:
-            return self._player_list
-        except AttributeError:
-            self._player_list = list()
-            for nr in range(1, 7):
-                self._player_list.append({
-                    'user': getattr(self, 'player%d' % nr),
-                    'score': getattr(self, 'player%d_score' % nr),
-                    'placement': getattr(self, 'player%d_placement' % nr),
-                })
+        """return a dict() with all 6 player names, scores and placements.
+        It will be cached and reused for more perfomance."""
+        if self._player_list:
             return self._player_list
+        for player_no in range(1, 7):
+            self._player_list.append(dict(
+                user=getattr(self, 'player%d' % player_no),
+                score=getattr(self, 'player%d_score' % player_no),
+                placement=getattr(self, 'player%d_placement' % player_no)
+            ))
+        return self._player_list
 
-    def save(self, force_insert=False, force_update=False, using=None,
-             update_fields=None):
-        u"""
-        Bestimmt die Platzierung eines jeden Spielers noch vor dem speichern.
-        Außerdem wird eine Kommasperierte Liste der Spiele mitgespeichert.
-        """
-        logging.debug("Berechne die Platzierungen neu...")
+    def save(self, **kwargs):
+        """recalculate the rankings before saving.
+         Also self.player_names will be filled with an comma sperated list of
+         all 6 player names."""
         game_date = self.event.start.date()
         player_tuples = [
             (self.player1.id, self.player1.username, self.player1_score),
@@ -138,12 +131,11 @@ class Game(models.Model):
             self.season = season_start.year
         else:
             self.season = season_start.year - 1
-        super(Game, self).save(force_insert=force_insert,
-                               force_update=force_update, using=using,
-                               update_fields=update_fields)
+            super(Game, self).save(**kwargs)
 
 
 class Ranking(models.Model):
+    """the player scores in the ladder for one season. """
     user = models.ForeignKey(settings.AUTH_USER_MODEL)
     season = models.PositiveSmallIntegerField(_("Season"))
     placement = models.PositiveIntegerField(blank=True, null=True)
@@ -155,22 +147,24 @@ class Ranking(models.Model):
     objects = managers.LadderManager()
 
     class Meta(object):
+        """Display rankings by placement, best players first."""
         ordering = ('-season', 'placement', 'avg_placement', '-avg_score',)
 
     def __str__(self):
-        return "Mai-Star Ranking: %s, Season: %d" % (self.user, self.season)
+        return "Mai-Star Ranking: {user!s}, Season: {season!d}".format(
+            user=self.user,
+            season=int(self.season)
+        )
 
     def get_absolute_url(self):
+        """URL to the subpage of the user profile, listing all Games."""
         return reverse('maistar-player-games', kwargs={
             'username': self.user.username,
             'season': self.season
         })
 
     def recalculate(self):
-        logging.info(
-            u'Recalculate Mai-Star Ranking for Player %s in Season %s',
-            self.user, self.season
-        )
+        """Recalculate the Mai-Star Ranking for this Player in this Season."""
         self.placement = None
         self.avg_placement = None
         self.avg_score = None
@@ -199,6 +193,8 @@ class Ranking(models.Model):
 
 
 def update_maistar_ranking(sender, instance, **kwargs):
+    """A Django signal hook to trigger a recalculation of the rankings as soon
+    as a Mai-Star game has been added, deleted, or modified."""
     for player in instance.player_list:
         ranking, created = Ranking.objects.get_or_create(
             user=player['user'],