popgym.core.deck
================

.. py:module:: popgym.core.deck


Attributes
----------

.. autoapisummary::

   popgym.core.deck.RANKS
   popgym.core.deck.SUITS
   popgym.core.deck.SUITS_UNICODE
   popgym.core.deck.COLORS
   popgym.core.deck.DECK_SIZE


Exceptions
----------

.. autoapisummary::

   popgym.core.deck.DeckEmptyError


Classes
-------

.. autoapisummary::

   popgym.core.deck.Deck


Functions
---------

.. autoapisummary::

   popgym.core.deck.ascii_version_of_card


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

.. py:function:: ascii_version_of_card(ranks, suits, return_string=True)

   Instead of a boring text version of the card we render an ASCII image of
   the card.

   :param cards: One or more card objects
   :param return_string: By default we return the string version
       of the card, but the dealer hide the 1st card and we
   keep it as a list so that the dealer can add a hidden card in front of the list


.. py:exception:: DeckEmptyError

   Bases: :py:obj:`Exception`


   Common base class for all non-exit exceptions.


.. py:data:: RANKS

.. py:data:: SUITS

.. py:data:: SUITS_UNICODE
   :value: ['♠', '♦', '♥', '♣']


.. py:data:: COLORS

.. py:data:: DECK_SIZE
   :value: 52


.. py:class:: Deck(num_decks=1, shuffle=False)

   An object that represents a collection of cards.

   A deck can represent a single deck or multiple decks


   .. py:method:: get_obs_space(fields=['colors', 'suits', 'ranks'], hand_size=1)


   .. py:attribute:: num_decks
      :value: 1



   .. py:attribute:: num_cards
      :value: 52



   .. py:attribute:: idx


   .. py:attribute:: ranks


   .. py:attribute:: ranks_idx


   .. py:attribute:: suits


   .. py:attribute:: suits_idx


   .. py:attribute:: colors


   .. py:attribute:: colors_idx


   .. py:attribute:: hands


   .. py:attribute:: deck_len
      :value: 52



   .. py:attribute:: keys
      :value: ['idx', 'ranks', 'suits', 'colors']



   .. py:attribute:: idx_keys
      :value: ['ranks_idx', 'suits_idx', 'colors_idx', 'idx']



   .. py:method:: define_hand_value(fn: Callable[[List[str]], int], fields: List[str]) -> None

      Pass in a function to be used to define the value of a hand
      or set of cards



   .. py:method:: clone() -> Deck


   .. py:method:: value(player: str) -> int

      Returns the value of a players hand by calling the function passed
      to define_hand_value



   .. py:method:: value_idx(idx: List[int]) -> int

      Returns the value of a selection of cards



   .. py:method:: add_players(*players: List[str]) -> None


   .. py:method:: deal(player: str, num_cards: int = 1) -> None

      Deals a number of cards to the specified player
      from the deck



   .. py:method:: discard_hands(*players: List[str])

      Discards the cards in the hand of a player. Note that
      these cards do not go back into the deck. Call reset()
      to fold the hands back into the deck



   .. py:method:: discard_all()

      Discards the cards in all player hands. Note that
      these cards do not go back into the deck. Call reset()
      to fold the hands back into the deck



   .. py:method:: discard(player: str, hand_idx: int)

      Discards one card in the players hand at the specified idx.
      Note this idx refers to the idx of the card in the hand, rather
      than the idx of the card in the deck



   .. py:method:: reset(shuffle=True, rng=None)

      Empties the hands of all players and places cards
      back into the deck in their original position. Optionally
      shuffles the deck afterwards



   .. py:method:: show(player: str, fields: List[str] = ['colors', 'suits', 'ranks'], pad_to=None) -> List[numpy.ndarray]

      Shows the hand of the player, returning the fields specified of the cards
      they hold. Optionally zero-pad to a size.



   .. py:method:: hand_size(player: str) -> int


   .. py:method:: visualize(player: str) -> str

      Returns a string visualization of a player's hand, for printing
      to the terminal



   .. py:method:: visualize_idx(idx: List[int]) -> str

      Returns a string visualization of the following idx,
      referring to cards in the hand or deck