haive.games.core.game.containers.deck
=====================================

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

.. autoapi-nested-parse::

   Deck classes for card games in the game framework.

   This module defines the Deck container type and related classes for card games.



Classes
-------

.. autoapisummary::

   haive.games.core.game.containers.deck.Card
   haive.games.core.game.containers.deck.Deck
   haive.games.core.game.containers.deck.StandardPlayingCardDeck


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

.. py:class:: Card

   Bases: :py:obj:`game_framework.pieces.base.GamePiece`


   Simple Card class for illustration.


   .. py:method:: flip()

      Flip the card face up/down.



.. py:class:: Deck

   Bases: :py:obj:`game_framework.containers.base.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:: insert(card, position)

      Insert a card at a specific position.

      :param card: Card to insert
      :param position: Position to insert at (0 for top, len(self.pieces) for bottom)

      :raises ValueError: If position is out of bounds



   .. 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:: place_on_bottom(card)

      Place a card on the bottom of the deck.

      :param card: Card to place



   .. 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:: StandardPlayingCardDeck

   Bases: :py:obj:`Deck`


   A standard 52-card playing card deck.


   .. py:class:: Rank

      Bases: :py:obj:`str`, :py:obj:`enum.Enum`


      Standard card ranks.

      Initialize self.  See help(type(self)) for accurate signature.



   .. py:class:: Suit

      Bases: :py:obj:`str`, :py:obj:`enum.Enum`


      Standard card suits.

      Initialize self.  See help(type(self)) for accurate signature.



   .. py:method:: create_standard_deck(include_jokers = False)
      :classmethod:


      Create a standard 52-card deck.

      :param include_jokers: Whether to include jokers in the deck

      :returns: A new StandardPlayingCardDeck instance