From 8847e088f60931548f18f50212c613ba9cf8ccd0 Mon Sep 17 00:00:00 2001
From: Andrey Antukh <niwi@niwi.be>
Date: Wed, 9 Oct 2013 13:21:34 +0200
Subject: [PATCH] Document some method related to create role points relations.

---
 .../management/commands/sample_data.py        |  2 +-
 greenmine/projects/models.py                  | 37 ++++++++++---------
 greenmine/projects/userstories/serializers.py |  3 +-
 3 files changed, 22 insertions(+), 20 deletions(-)

diff --git a/greenmine/projects/management/commands/sample_data.py b/greenmine/projects/management/commands/sample_data.py
index 2d6db45b..cc3e3f56 100644
--- a/greenmine/projects/management/commands/sample_data.py
+++ b/greenmine/projects/management/commands/sample_data.py
@@ -158,7 +158,7 @@ class Command(BaseCommand):
 
         us.save()
 
-        for role in project.list_roles:
+        for role in project.get_roles():
             if milestone:
                 points=self.sd.db_object_from_queryset(Points.objects.filter(project=project).exclude(order=0))
             else:
diff --git a/greenmine/projects/models.py b/greenmine/projects/models.py
index a7d0d49f..23f94b0e 100644
--- a/greenmine/projects/models.py
+++ b/greenmine/projects/models.py
@@ -120,47 +120,50 @@ class Project(models.Model):
             "team_increment_points": milestone.team_increment_points
         } for milestone in self.milestones.all().order_by("estimated_start")]
 
-    @property
-    def list_roles(self):
+    def get_roles(self):
         role_model = get_model("users", "Role")
         return role_model.objects.filter(id__in=list(self.memberships.values_list(
                                                                  "role", flat=True)))
-    @property
-    def list_users(self):
+    def get_users(self):
         user_model = get_user_model()
         return user_model.objects.filter(id__in=list(self.memberships.values_list(
                                                                  "user", flat=True)))
     def update_role_points(self):
         rolepoints_model = get_model("userstories", "RolePoints")
-        roles = self.list_roles
-        role_ids = roles.values_list("id", flat=True)
-        null_points = self.points.get(value=None)
+
+        # Get all available roles on this project
+        roles = self.get_roles()
+
+        # Get point instance that represent a null/undefined
+        null_points_value = self.points.get(value=None)
+
+        # Iter over all project user stories and create
+        # role point instance for new created roles.
         for us in self.user_stories.all():
             for role in roles:
-                try:
-                    sp = us.role_points.get(role=role, user_story=us)
-                except rolepoints_model.DoesNotExist:
-                    sp = rolepoints_model.objects.create(role=role,
-                                                   user_story=us,
-                                                   points=null_points)
+                if not us.role_points.filter(role=role).exists():
+                    sp = rolepoints_model.objects.create(role=role, user_story=us,
+                                                         points=null_points_value)
 
-        #Remove unnecesary Role points
+        # Now remove rolepoints associated with not existing roles.
         rp_query = rolepoints_model.objects.filter(user_story__in=self.user_stories.all())
-        rp_query = rp_query.exclude(role__id__in=role_ids)
+        rp_query = rp_query.exclude(role__id__in=roles.values_list("id", flat=True))
         rp_query.delete()
 
 
 # Reversion registration (usufull for base.notification and for meke a historical)
 reversion.register(Project)
 
-# Signals dispatches
+# On membership object is created/changed, update
+# role-points relation.
 @receiver(models.signals.post_save, sender=Membership,
           dispatch_uid='membership_post_save')
 def membership_post_save(sender, instance, created, **kwargs):
     instance.project.update_role_points()
 
 
-@receiver(models.signals.post_delete, sender=Membership,
+# On membership object is deleted, update role-points relation.
+@receiver(models.signals.pre_delete, sender=Membership,
           dispatch_uid='membership_pre_delete')
 def membership_post_delete(sender, instance, using, **kwargs):
     instance.project.update_role_points()
diff --git a/greenmine/projects/userstories/serializers.py b/greenmine/projects/userstories/serializers.py
index 70213296..b1e89427 100644
--- a/greenmine/projects/userstories/serializers.py
+++ b/greenmine/projects/userstories/serializers.py
@@ -1,12 +1,11 @@
 # -*- coding: utf-8 -*-
 
+import json, reversion
 from rest_framework import serializers
 
 from greenmine.base.serializers import PickleField
-
 from . import models
 
-import json, reversion
 
 
 class PointsSerializer(serializers.ModelSerializer):