haive.games.core.game.containers.base
=====================================

.. py:module:: haive.games.core.game.containers.base

.. autoapi-nested-parse::

   Container models for game pieces in the game framework.

   This module defines containers for game pieces like decks of cards, bags of tiles, and
   player hands.



Classes
-------

.. autoapisummary::

   haive.games.core.game.containers.base.Deck
   haive.games.core.game.containers.base.GamePieceContainer
   haive.games.core.game.containers.base.PlayerHand


Module Contents
---------------

.. py:class:: Deck

   Bases: :py:obj:`GamePieceContainer`\ [\ :py:obj:`C`\ ]


   A deck of cards.

   This represents a collection of cards that can be drawn, shuffled, and dealt.



   .. py:method:: deal(num_players, cards_per_player)

      Deal cards to multiple players.

      :param num_players: Number of players to deal to
      :param cards_per_player: Number of cards per player

      :returns: List of lists, where each inner list contains a player's cards



   .. py:method:: discard(card)

      Add a card to the discard pile.

      :param card: Card to discard



   .. py:method:: draw()

      Draw the top card and set its face up/down based on deck configuration.

      :returns: The drawn card, or None if deck is empty



   .. py:method:: draw_bottom()

      Draw the bottom card.

      :returns: The bottom card, or None if deck is empty



   .. py:method:: peek_bottom(count = 1)

      Look at bottom cards without drawing.

      :param count: Number of cards to peek at

      :returns: List of cards from the bottom



   .. py:method:: peek_top(count = 1)

      Look at top cards without drawing.

      :param count: Number of cards to peek at

      :returns: List of cards from the top



   .. py:method:: recycle_discards(shuffle = True)

      Move all cards from discard pile back into the deck.

      :param shuffle: Whether to shuffle the deck after recycling



.. py:class:: GamePieceContainer(/, **data)

   Bases: :py:obj:`pydantic.BaseModel`, :py:obj:`Generic`\ [\ :py:obj:`T`\ ]


   Base container for game pieces.

   This represents a collection of game pieces like a deck of cards, a bag of tiles, or
   a player's hand.


   Create a new model by parsing and validating input data from keyword arguments.

   Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
   validated to form a valid model.

   `self` is explicitly positional-only to allow `self` as a field name.


   .. py:method:: add(piece, position = 'top')

      Add a piece to this container.

      :param piece: The piece to add
      :param position: Where to add the piece ("top", "bottom", or "random")

      :raises ValueError: If position is not valid



   .. py:method:: clear()

      Remove all pieces from the container.



   .. py:method:: count()

      Count pieces in the container.

      :returns: Number of pieces in the container



   .. py:method:: draw()

      Draw the top piece.

      :returns: The top piece, or None if container is empty



   .. py:method:: draw_many(count)

      Draw multiple pieces from the top.

      :param count: Number of pieces to draw

      :returns: List of drawn pieces



   .. py:method:: filter(predicate)

      Filter pieces by predicate.

      :param predicate: Function that returns True for pieces to include

      :returns: List of pieces matching the predicate



   .. py:method:: find(predicate)

      Find a piece matching the predicate.

      :param predicate: Function that returns True for the desired piece

      :returns: The first matching piece, or None if not found



   .. py:method:: get_property(key, default = None)

      Get a container property.

      :param key: Property name
      :param default: Default value if property doesn't exist

      :returns: Property value or default



   .. py:method:: is_empty()

      Check if container is empty.

      :returns: True if the container is empty, False otherwise



   .. py:method:: peek(count = 1)

      Look at the top pieces without removing them.

      :param count: Number of pieces to peek at

      :returns: List of pieces from the top



   .. py:method:: remove(piece_id)

      Remove a piece by ID.

      :param piece_id: ID of the piece to remove

      :returns: The removed piece, or None if not found



   .. py:method:: set_property(key, value)

      Set a container property.

      :param key: Property name
      :param value: Property value



   .. py:method:: shuffle()

      Shuffle the pieces in the container.



.. py:class:: PlayerHand

   Bases: :py:obj:`GamePieceContainer`\ [\ :py:obj:`T`\ ]


   A player's hand of pieces.

   This represents the collection of pieces a player holds, such as cards in a card
   game or tiles in Scrabble.



   .. py:method:: add_piece(piece)

      Add a piece to the hand and assign ownership to the player.

      :param piece: The piece to add



   .. py:method:: play_piece(piece_id)

      Play a piece (remove from hand).

      :param piece_id: ID of the piece to play

      :returns: The played piece, or None if not found



   .. py:method:: play_pieces(piece_ids)

      Play multiple pieces.

      :param piece_ids: List of piece IDs to play

      :returns: List of played pieces