Adding doc strings

Author: fnscoder

core/services.py

@@ -10,14 +10,31 @@
 
 
 class GameService:
+    """Service class to handle game logic."""
+
     @staticmethod
     def initialize_cells(game):
+        """
+        Create the cells of the game, place the mines, and calculate adjacencies.
+
+        Args:
+            game (Game): The game instance for which cells are being initialized.
+        """
         cells = GameService._create_cells(game)
         GameService._place_mines(game, cells)
         GameService._calculate_adjacencies(cells)
 
     @staticmethod
     def _create_cells(game):
+        """
+        Create game cells using bulk_create to optimize database access.
+
+        Args:
+            game (Game): The game instance for which cells are being created.
+
+        Returns:
+            QuerySet: A queryset of the created cells.
+        """
         cells = [
             Cell(game=game, row=row, column=col)
             for row in range(game.rows)
@@ -28,13 +45,26 @@ def _create_cells(game):
 
     @staticmethod
     def _place_mines(game, cells):
+        """
+        Randomly place mines in the game cells.
+
+        Args:
+            game (Game): The game instance for which mines are being placed.
+            cells (QuerySet): The queryset of cells in the game.
+        """
         mine_cells = sample(list(cells), game.mines)
         for mine in mine_cells:
             mine.is_mine = True
         Cell.objects.bulk_update(mine_cells, ["is_mine"])
 
     @staticmethod
     def _calculate_adjacencies(cells):
+        """
+        Calculate the number of adjacent mines for each cell.
+
+        Args:
+            cells (QuerySet): The queryset of cells in the game.
+        """
         updates = []
         for cell in cells:
             if not cell.is_mine:
@@ -44,18 +74,49 @@ def _calculate_adjacencies(cells):
 
     @staticmethod
     def _calculate_adjacent_mines(cell):
+        """
+        Calculate the number of mines adjacent to a given cell.
+
+        Args:
+            cell (Cell): The cell for which adjacent mines are being calculated.
+
+        Returns:
+            int: The number of adjacent mines.
+        """
         neighbors = Cell.objects.get_neighbors(cell)
         return sum(1 for neighbor in neighbors if neighbor.is_mine)
 
     @staticmethod
     def _get_cell(game, row, column):
+        """
+        Retrieve a cell by its row and column in a given game.
+
+        Args:
+            game (Game): The game instance.
+            row (int): The row number of the cell.
+            column (int): The column number of the cell.
+
+        Returns:
+            Cell or None: The cell if found, otherwise None.
+        """
         try:
             return Cell.objects.get(game=game, row=row, column=column)
         except Cell.DoesNotExist:
             return None
 
     @staticmethod
     def reveal_cell(game, row, column):
+        """
+        Reveal a cell and handle game logic for revealing cells.
+
+        Args:
+            game (Game): The game instance.
+            row (int): The row number of the cell to reveal.
+            column (int): The column number of the cell to reveal.
+
+        Returns:
+            tuple: A tuple containing the response data and HTTP status code.
+        """
         cell = GameService._get_cell(game, row, column)
         if not cell:
             return CELL_NOT_FOUND, HTTP_404_NOT_FOUND
@@ -77,6 +138,12 @@ def reveal_cell(game, row, column):
 
     @staticmethod
     def _reveal_cells(cell):
+        """
+        Recursively reveal cells starting from the given cell.
+
+        Args:
+            cell (Cell): The cell to start revealing from.
+        """
         if cell.is_revealed:
             return
         cell.is_revealed = True
@@ -89,13 +156,26 @@ def _reveal_cells(cell):
 
     @staticmethod
     def _end_game(game, status):
+        """
+        End the game with a given status and reveal all cells.
+
+        Args:
+            game (Game): The game instance.
+            status (GameStatus): The status to set for the game.
+        """
         game.status = status
         game.finished_at = now()
         game.save()
         GameService._reveal_all_cells(game)
 
     @staticmethod
     def _reveal_all_cells(game):
+        """
+        Reveal all cells in the game.
+
+        Args:
+            game (Game): The game instance.
+        """
         cells = Cell.objects.filter(game=game)
         with transaction.atomic():
             for cell in cells:
@@ -104,12 +184,32 @@ def _reveal_all_cells(game):
 
     @staticmethod
     def _check_win_condition(game):
+        """
+        Check if the win condition is met for the game.
+
+        Args:
+            game (Game): The game instance.
+
+        Returns:
+            bool: True if the win condition is met, False otherwise.
+        """
         return not Cell.objects.filter(
             game=game, is_revealed=False, is_mine=False
         ).exists()
 
     @staticmethod
     def toggle_flag(game, row, column):
+        """
+        Toggle the flag status of a cell.
+
+        Args:
+            game (Game): The game instance.
+            row (int): The row number of the cell to flag/unflag.
+            column (int): The column number of the cell to flag/unflag.
+
+        Returns:
+            tuple: A tuple containing the response data and HTTP status code.
+        """
         cell = GameService._get_cell(game, row, column)
         if not cell:
             return CELL_NOT_FOUND, HTTP_404_NOT_FOUND

core/views.py

@@ -14,10 +14,12 @@ class GameViewSet(ModelViewSet):
     serializer_class = GameSerializer
 
     def perform_create(self, serializer):
+        """Initialize the cells of the game after creation."""
         game = serializer.save()
         GameService.initialize_cells(game)
 
     def _process_cell_action(self, request, cell_action):
+        """Process a cell action (flag or reveal) on a game."""
         row = request.data.get("row")
         column = request.data.get("column")
         game = self.get_object()
@@ -30,10 +32,12 @@ def _process_cell_action(self, request, cell_action):
 
     @action(detail=True, methods=["post"])
     def flag(self, request, pk=None):
+        """Action to flag a cell in the game."""
         data, status_code = self._process_cell_action(request, GameService.toggle_flag)
         return Response(data, status=status_code)
 
     @action(detail=True, methods=["post"])
     def reveal(self, request, pk=None):
+        """Action to reveal a cell in the game."""
         data, status_code = self._process_cell_action(request, GameService.reveal_cell)
         return Response(data, status=status_code)