feat(services): add game service to modify game

Author: FlysonBot

src/mastermind/core/models/game_state.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 from typing import Optional
 
-from mastermind.core.controllers.players import Player
+from mastermind.core.controllers.players import PlayerRole
 
 
 @dataclass
@@ -12,9 +12,57 @@ class GameState:
     Attributes:
         game_started (bool): A flag indicating if the game has started.
         game_over (bool): A flag indicating if the game has ended.
-        winner (Player): The player who won the game, if any. Only top level player (CodeSetter or Codebreaker) is allowed.
+        winner (PlayerRole): The player who won the game, if any. Only top level player (CodeSetter or Codebreaker) is allowed.
     """
 
     game_started: bool = False
-    game_over: bool = False
-    winner: Optional[Player] = None
+    winner: Optional[PlayerRole] = None
+
+    @property
+    def game_over(self) -> bool:
+        """Returns a boolean indicating if the game has ended.
+
+        Returns:
+            bool: True if the game has ended, False otherwise.
+
+        Examples:
+            >>> game_state = GameState(game_started=True, winner=None)
+            >>> game_state.game_over
+            False
+            >>> game_state = GameState(game_started=True, winner=PlayerRole.CODE_SETTER)
+            >>> game_state.game_over
+            True
+        """
+        return self.winner is not None
+
+
+def get_winner(
+    num_attempts: int,
+    max_attempts: int,
+    last_feedback: tuple[int, int],
+    number_of_dots: int,
+) -> Optional[PlayerRole]:
+    """Determines the winner of the game based on the number of attempts and the last feedback.
+
+    Args:
+        num_attempts (int): The number of attempts made by the player.
+        max_attempts (int): The maximum number of attempts allowed.
+        last_feedback (tuple[int, int]): The feedback received from the last game round.
+        number_of_dots (int): The number of dots in the code.
+
+    Returns:
+        Optional[PlayerRole]: The winner of the game, if any.
+
+    Examples:
+        >>> get_winner(num_attempts=5, max_attempts=5, last_feedback=(1, 0), number_of_dots=4) == PlayerRole.CODE_SETTER
+        True
+        >>> get_winner(num_attempts=5, max_attempts=5, last_feedback=(4, 0), number_of_dots=4) == PlayerRole.CODE_BREAKER
+        True
+        >>> get_winner(num_attempts=4, max_attempts=5, last_feedback=(1, 0), number_of_dots=4) == None
+        True
+    """
+
+    if last_feedback == (number_of_dots, 0):
+        return PlayerRole.CODE_BREAKER
+
+    return PlayerRole.CODE_SETTER if num_attempts >= max_attempts else None

src/mastermind/core/models/gameboard.py

@@ -39,7 +39,7 @@ def guesses(self) -> Generator[Tuple[int, ...], None, None]:
         Returns a generator of all guesses made in the game to allow for easy iteration.
 
         Returns:
-            Generator[Tuple[int, ...], None, None]: _description_
+            Generator[Tuple[int, ...], None, None]: A generator of all guesses made in the game.
 
         Examples:
             >>> game_board = GameBoard(game_rounds=[GameRound(GUESS=(1, 2, 3, 4), FEEDBACK=(1, 0)), GameRound(GUESS=(3, 4, 5, 6), FEEDBACK=(2, 1))])

src/mastermind/core/services/game_service.py

@@ -0,0 +1,110 @@
+from mastermind.core.models.game import Game
+from mastermind.core.models.game_state import get_winner
+from mastermind.core.services.gameboard_service import GameboardService
+
+
+class GameEndedException(Exception):
+    pass
+
+
+class GameNotStartedException(Exception):
+    pass
+
+
+class GameService:
+    def __init__(self, game: Game) -> None:
+        """Initializes a new game service with the given game.
+
+        Args:
+            game (Game): The game to be managed.
+        """
+
+        self._game_board = game.game_board
+        self._game_configuration = game.game_configuration
+        self._game_entities = game.game_entities
+        self._game_state = game.game_state
+        self._gameboard_service = GameboardService(self._game_board)
+
+    def add_round(self, guess: tuple[int, ...], feedback: tuple[int, int]) -> None:
+        """Adds a new game round with the player's guess and corresponding feedback.
+
+        Appends the round to game rounds and clears the undo stack to prevent branching.
+        This method should be called from the GameController, not directly by the player.
+
+        Args:
+            guess (tuple[int, ...]): A tuple representing the player's current guess.
+            feedback (tuple[int, int]): A tuple containing the number of correct and misplaced pegs.
+
+        Examples:
+            >>> game = create_new_game(GameConfiguration(NUMBER_OF_COLORS=3, NUMBER_OF_DOTS=4, ATTEMPTS_ALLOWED=5, GAME_MODE=GameMode.PVP))
+            >>> service = GameService(game)
+            >>> service.add_round((1, 2, 3, 4), (1, 0))
+            >>> service.game_rounds
+            [GameRound(GUESS=(1, 2, 3, 4), FEEDBACK=(1, 0))]
+
+        Raises:
+            GameEndedException: When trying to add a round to a game that has ended.
+        """
+
+        if self._game_state.game_over:
+            raise GameEndedException("Cannot add round to game that has ended.")
+
+        self._gameboard_service.add_round(guess, feedback)
+        self._game_state.game_started = True
+        self._game_state.winner = get_winner(
+            num_attempts=len(self._game_board),
+            max_attempts=self._game_configuration.ATTEMPTS_ALLOWED,
+            last_feedback=self._gameboard_service.game_rounds[-1].FEEDBACK,
+            number_of_dots=self._game_configuration.NUMBER_OF_DOTS,
+        )
+
+    def undo(self) -> None:
+        """Undo the most recent game round.
+
+        Examples:
+            >>> game = create_new_game(GameConfiguration(NUMBER_OF_COLORS=3, NUMBER_OF_DOTS=4, ATTEMPTS_ALLOWED=5, GAME_MODE=GameMode.PVP))
+            >>> service = GameService(game)
+            >>> service.add_round((1, 2, 3, 4), (1, 0))
+            >>> game.game_board.game_rounds
+            [GameRound(GUESS=(1, 2, 3, 4), FEEDBACK=(1, 0))]
+            >>> service.undo()
+            >>> game.game_board.game_rounds
+            []
+
+        Raises:
+            GameNotStartedException: When trying to undo game rounds before the game has started.
+            GameEndedException: When trying to undo game rounds after the game has ended.
+        """
+
+        if not self._game_state.game_started:
+            raise GameNotStartedException(
+                "Cannot undo game rounds before game has started."
+            )
+
+        if not self._game_state.game_over:
+            raise GameEndedException("Cannot undo game rounds after game has ended.")
+
+        self._gameboard_service.undo()
+
+    def redo(self) -> None:
+        """Restores the most recently undone game round.
+
+        Examples:
+            >>> game = create_new_game(GameConfiguration(NUMBER_OF_COLORS=3, NUMBER_OF_DOTS=4, ATTEMPTS_ALLOWED=5, GAME_MODE=GameMode.PVP))
+            >>> service = GameService(game)
+            >>> service.add_round((1, 2, 3, 4), (1, 0))
+            >>> service.undo()
+            >>> service.redo()
+            >>> service.game_rounds
+            [GameRound(GUESS=(1, 2, 3, 4), FEEDBACK=(1, 0))]
+
+        Raises:
+            GameNotStartedException: When trying to redo game rounds before the game has started.
+        """
+
+        if not self._game_state.game_started:
+            raise GameNotStartedException(
+                "Cannot redo game rounds before game has started."
+            )
+
+        self._gameboard_service.redo()

src/mastermind/core/services/gameboard_service.py

@@ -6,13 +6,22 @@
 
 
 class GameboardService:
+    """This class manages the game board and provides methods for adding and undoing game rounds.
+
+    It should be called from the GameService, not directly by the player.
+
+    Attributes:
+        game_rounds (Deque[GameRound]): A deque of GameRound instances, each representing a round of the game.
+        undo_stack (Deque[GameRound]): A deque of GameRound instances, representing the undo stack.
+    """
+
     def __init__(self, gameboard: GameBoard) -> None:
         """Initializes a new game board service with the current game board state.
 
         The service prepares game rounds and an undo stack for tracking game progress.
 
         Args:
-            gameboard: The current game board to be managed.
+            gameboard (GameBoard): The current game board to be managed.
         """
 
         self.game_rounds: Deque[GameRound] = gameboard.game_rounds
@@ -49,20 +58,19 @@ def redo(self) -> None:
 
         self.game_rounds.append(self.undo_stack.pop())
 
-    def _add_round(self, guess: tuple[int, ...], feedback: tuple[int, int]) -> None:
+    def add_round(self, guess: tuple[int, ...], feedback: tuple[int, int]) -> None:
         """Adds a new game round with the player's guess and corresponding feedback.
 
         Appends the round to game rounds and clears the undo stack to prevent branching.
-        This method should be called from the GameService, not directly by the player.
 
         Args:
-            guess: A tuple representing the player's current guess.
-            feedback: A tuple containing the number of correct and misplaced pegs.
+            guess (tuple[int, ...]): A tuple representing the player's current guess.
+            feedback (tuple[int, int]): A tuple containing the number of correct and misplaced pegs.
 
         Examples:
             >>> gameboard = GameBoard(game_rounds=[GameRound(GUESS=(3, 4, 5, 6), FEEDBACK=(2, 1))])
             >>> service = GameboardService(gameboard)
-            >>> service._add_round((1, 2, 3, 4), (1, 0))
+            >>> service.add_round((1, 2, 3, 4), (1, 0))
             >>> service.game_rounds
             [GameRound(GUESS=(3, 4, 5, 6), FEEDBACK=(2, 1)), GameRound(GUESS=(1, 2, 3, 4), FEEDBACK=(1, 0))]
         """