pooltool.ruleset
================

.. py:module:: pooltool.ruleset

    Ruleset logic
    -------------
    
    

Overview
--------

.. list-table:: Classes
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`AIPlayer <pooltool.ruleset.AIPlayer>`
     - Base class for protocol classes.
   * - :py:obj:`BallInHandOptions <pooltool.ruleset.BallInHandOptions>`
     - Enum where members are also (and must be) strings
   * - :py:obj:`Player <pooltool.ruleset.Player>`
     - A player
   * - :py:obj:`Ruleset <pooltool.ruleset.Ruleset>`
     - Abstract base class for a pool game ruleset.
   * - :py:obj:`ShotConstraints <pooltool.ruleset.ShotConstraints>`
     - Constraints for a player's upcoming shot
   * - :py:obj:`ShotInfo <pooltool.ruleset.ShotInfo>`
     - Info about a played shot


.. list-table:: Function
   :header-rows: 0
   :widths: auto
   :class: summarytable

   * - :py:obj:`get_ruleset <pooltool.ruleset.get_ruleset>`\ (game)
     - Retrieve a ruleset class



Classes
-------
.. autoclass:: AIPlayer


   Bases: :py:obj:`Protocol`




.. autoclass:: BallInHandOptions


   Bases: :py:obj:`pooltool.utils.strenum.StrEnum`




.. autoclass:: Player





.. autoclass:: Ruleset(players: Optional[List[Player]] = None)


   Bases: :py:obj:`abc.ABC`

   .. py:property:: last_player
      :type: Player

      Returns the last player who played before the active player

      If no turns have occurred, meaning the active player is the first player to
      shoot in the game, this erroneously returns the last player in the player order.



   .. rubric:: Methods:
   .. py:method:: set_next_player() -> None

      Sets the index for the next player

      It is through this index that self.last_player and self.active_player are
      defined from.


   .. py:method:: player_order() -> Generator[Player, None, None]

      Generates player order from current player until last-to-play


   .. py:method:: process_shot(shot: pooltool.system.datatypes.System) -> None

      Processes the information of the shot just played

      :param shot: The shot data from the system.


   .. py:method:: advance(shot: pooltool.system.datatypes.System) -> None

      Advances the game state after a shot has been made and processed

      :param shot: The shot data from the system.


   .. py:method:: build_shot_info(shot: pooltool.system.datatypes.System) -> ShotInfo
      :abstractmethod:

      Construct the ShotInfo object for the current shot

      This method evaluates the legality of a shot, determines if the turn or game is
      over, and if applicable, decides the winner.

      :param shot: The current shot being played.

      :returns:     Contains details about the legality of the shot, whether the turn and
                    game are over, and who the winner is, if there is one.
      :rtype: ShotInfo


   .. py:method:: next_shot_constraints(shot: pooltool.system.datatypes.System) -> ShotConstraints
      :abstractmethod:

      Determine the constraints for the next shot based on the current game state.

      The method sets the conditions under which the next shot will be played, such as
      whether ball-in-hand rules apply and which balls are legally hittable.

      :param shot: The current shot being played.

      :returns:     Shot constraints for the next shot.
      :rtype: ShotConstraints


   .. py:method:: initial_shot_constraints() -> ShotConstraints
      :abstractmethod:

      Define the initial constraints for the first shot of the game.

      :returns:     Predefined shot constraints for the initial shot.
      :rtype: ShotConstraints


   .. py:method:: respot_balls(shot: pooltool.system.datatypes.System) -> None
      :abstractmethod:

      Respot balls

      This method should decide which balls should be respotted, and respot them. This
      method should probably make use of ``pooltool.ruleset.utils.respot``


   .. py:method:: copy() -> Ruleset
      :abstractmethod:

      Copy the game state

      If you don't know how to implement this method, you can create a placeholder
      function:

      ::
          def copy(self):
              return self



.. autoclass:: ShotConstraints





.. autoclass:: ShotInfo






Functions
---------
.. py:function:: get_ruleset(game: pooltool.game.datatypes.GameType) -> Type[datatypes.Ruleset]

   Retrieve a ruleset class

   :param game: The game type.

   :returns:     An uninitialized class object representing a game.
   :rtype: Type[Ruleset]