Add comments

api/arconnectmanagerapp/api.py

@@ -4,17 +4,21 @@
 import re
 from datetime import datetime
 
-
+#This class interacts with the Challonge API to create and manage tournaments
 class ChallongeAPI():
     def __init__(self):
         env = environ.Env()
         CHALLONGE_API_USERNAME = env('CHALLONGE_API_USERNAME')
         CHALLONGE_API_KEY = env('CHALLONGE_API_KEY')
-        self.match_desired_attr = ['id', 'round', 'scores_csv', 'state', 'player1_id', 'player2_id', 'winner_id']
+        self.match_desired_attr = ['id', 'round', 'scores_csv', 'state', 'player1_id', 'player2_id', 'winner_id'] #Filter the attributes wanted in the match object
 
         challonge.set_credentials(CHALLONGE_API_USERNAME, CHALLONGE_API_KEY)
 
     def create_tournament(self, name : str, participants : list):
+        """_summary_ : Create a tournament with the given name and participants
+        _param_ : name : str : The name of the tournament
+        _param_ : participants : list : The list of participants
+        """
         unique_url = re.sub(r'[^a-zA-Z0-9_]', '', name) + "_" + str(random.randint(0, 1000)) #Generate an unique URL for the tournament (only letters, numbers and _ are allowed)
         tournament = challonge.tournaments.create(name, unique_url, private=True)
 
@@ -26,9 +30,22 @@ def create_tournament(self, name : str, participants : list):
         return {"id": tournament['id'], "image_url": tournament['live_image_url']}
 
     def finalize_tournament(self, tournamentID : str):
+        """_summary_ : Finalize the tournament with the given ID
+        Args:
+            tournamentID (str): the ID of the tournament to finalize
+
+        """
         return challonge.tournaments.finalize(tournamentID)
 
     def get_matches(self, tournamentID: str):
+        """_summary_ : Get the list of matches in the tournament with the given ID
+
+        Args:
+            tournamentID (str): the ID of the tournament to get the matches from
+
+        Returns:
+            list: the list of matches in the tournament
+        """
         filtered_matches = []
 
         matches = challonge.matches.index(tournamentID)
@@ -40,6 +57,16 @@ def get_matches(self, tournamentID: str):
         return filtered_matches
 
     def match_update_score(self, tournamentID : str, matchID : str, p1_ID : str, score_p1 : int, p2_ID : str, score_p2 : int):
+        """_summary_ : Update the score of the match with the given ID
+
+        Args:
+            tournamentID (str): the ID of the tournament
+            matchID (str): the ID of the match to update
+            p1_ID (str): the challonge ID of the first player
+            score_p1 (int): the score of the first player
+            p2_ID (str): the challonge ID of the second player
+            score_p2 (int): the score of the second player
+        """
         final_score = str(score_p1) + "-" + str(score_p2)
 
         winner_id = p1_ID
@@ -51,6 +78,15 @@ def match_update_score(self, tournamentID : str, matchID : str, p1_ID : str, sco
         return self.__get_match_filtered_info(updated_match, challonge.participants.index(tournamentID))
 
     def is_matchID_valid(self, tournamentID : str, matchID : str):
+        """_summary_ : Check if the match with the given ID exists and is valid
+
+        Args:
+            tournamentID (str): the ID of the tournament
+            matchID (str): the ID of the match to check
+
+        Returns:
+            boolean: true if the match exists and is valid, false otherwise
+        """
         matches = challonge.matches.index(tournamentID)
         for match in matches:
             if str(match['id']) == matchID:
@@ -59,25 +95,61 @@ def is_matchID_valid(self, tournamentID : str, matchID : str):
         return False
 
     def are_matches_finished(self, tournamentID : str):
+        """_summary_ : Check if all the matches in the tournament are finished
+
+        Args:
+            tournamentID (str): the ID of the tournament
+
+        Returns:
+            boolean: true if all the matches are finished, false otherwise
+        """
         matches = challonge.matches.index(tournamentID)
         for match in matches:
             if match['state'] != 'complete':
                 return False
         return True
 
     def are_players_in_match(self, tournamentID : str, matchID : str, players_ID : list):
+        """_summary_ : Check if the players with the given ID are in the match
+
+        Args:
+            tournamentID (str): the ID of the tournament
+            matchID (str): the ID of the match
+            players_ID (list): the list of players ID to check
+
+        Returns:
+            boolean: true if the players are in the match, false otherwise
+        """
         match = challonge.matches.show(tournamentID, matchID)
         return str(match['player1_id']) in players_ID and str(match['player2_id']) in players_ID
 
     #Tools functions
 
     def __get_match_filtered_info(self, match, participants):
+        """_summary_ : Get the filtered information of the match
+
+        Args:
+            match : the match object
+            participants : the list of participants in the tournament
+
+        Returns:
+            dict : the filtered information of the match
+        """
         filtered_match = {attr: match[attr] for attr in self.match_desired_attr if attr in match}
         filtered_match['player1_name'] = self.__get_participant_name_from_ID(participants, match['player1_id'])
         filtered_match['player2_name'] = self.__get_participant_name_from_ID(participants, match['player2_id'])
         return filtered_match
 
     def __get_participant_name_from_ID(self, participants, id):
+        """_summary_ : Get the name of the participant with the given ID
+
+        Args:
+            participants : the list of all participants in the tournament
+            id : the ID of the participant to get the name from
+
+        Returns:
+            string: the name of the participant
+        """
         for participant in participants:
             if participant["id"] == id:
                 return participant["name"]

api/arconnectmanagerapp/models.py

@@ -10,10 +10,10 @@ class TournamentItem(models.Model):
             default=0,
             validators=[MinValueValidator(0), MaxValueValidator(3)]
         )                       
-    players = models.ManyToManyField(User, related_name='players')
+    players = models.ManyToManyField(User, related_name='players')  #N-N relationship with the players
 
     challonge_id = models.CharField(max_length=100, blank=True)     #ID of the tournament on Challonge
-    challonge_image_url = models.URLField(blank=True)                         #URL of the image of the tournament
+    challonge_image_url = models.URLField(blank=True)               #URL of the image of the tournament
 
-    created = models.DateTimeField(auto_now_add=True)
-    updated = models.DateTimeField(auto_now=True)
+    created = models.DateTimeField(auto_now_add=True)               #Date of creation
+    updated = models.DateTimeField(auto_now=True)                   #Date of last update

api/arconnectmanagerapp/permissions.py

@@ -1,13 +1,18 @@
 from rest_framework import permissions
 
+#Manage permissions for the TournamentItem model
 class TournamentPermission(permissions.BasePermission):
     '''Permissions for the TournamentItem model'''
     def has_permission(self, request, view):
-        if view.action in ['list', 'retrieve']:
+        if view.action in ['list', 'retrieve']: 
+            #Allow everyone
             return True
-        elif view.action in ['register', 'unregister']:
+        elif view.action in ['register', 'unregister']: 
+            #Allow only authenticated users
             return request.user.is_authenticated
         elif view.action in ['create', 'update', 'partial_update', 'destroy', 'open_registration', 'api_start', 'api_finish', 'api_get_matches', 'api_submit_scores']:
+            #Allow only admin users
             return request.user.is_authenticated and request.user.is_staff
         else:
+            #Otherwise, deny permission
             return False

api/arconnectmanagerapp/views.py

@@ -151,11 +151,12 @@ class UserView(APIView):
     authentication_classes = [authentication.TokenAuthentication]
     permission_classes = [permissions.IsAuthenticated]
 
+    #Get the user information
     def get(self, request):
         user = request.user
         user_info = {
             'username': user.username,
-            'isAdmin': user.is_staff,
+            'isAdmin': user.is_staff, #flag indicating if the user is an admin
             'tournaments': user.players.all().values_list('pk', flat=True)
         }