haive.games.cards.models.card
=============================

.. py:module:: haive.games.cards.models.card

.. autoapi-nested-parse::

   Card representation and operations for card games.

   This module provides classes for representing playing cards, including ranks,
   suits, and card values. It's designed to be used in various card game implementations
   with consistent handling of card comparisons and representations.

   .. rubric:: Example

   >>> from haive.games.cards.models.card import Card, Rank, Suit
   >>> card = Card(Rank.ACE, Suit.SPADES)
   >>> print(card)
   A`
   >>> card.value
   14



Classes
-------

.. autoapisummary::

   haive.games.cards.models.card.Card
   haive.games.cards.models.card.Rank
   haive.games.cards.models.card.Suit


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

.. py:class:: Card(rank, suit)

   A playing card with rank and suit.

   Represents a standard playing card with rank and suit, providing methods
   for comparison, display, and game-specific value calculations.

   .. attribute:: rank

      The rank of the card (2-10, J, Q, K, A, Joker).

   .. attribute:: suit

      The suit of the card (clubs, diamonds, hearts, spades, joker).

   .. attribute:: value

      The numeric value of the card for comparisons.

   .. rubric:: Examples

   >>> card = Card(Rank.ACE, Suit.SPADES)
   >>> print(card)
   A`
   >>> card.value
   14
   >>> card.long_name
   'Ace of Spades'

   Initialize a card with rank and suit.

   :param rank: The rank of the card.
   :param suit: The suit of the card.

   :raises ValueError: If a standard card is created with Joker suit but not Joker rank.


   .. py:method:: blackjack_value()

      Calculate the value of the card in Blackjack.

      Aces are worth 11 by default (caller should handle alternate values).
      Face cards (J, Q, K) are worth 10.

      :returns: The card's value in Blackjack.



   .. py:method:: from_string(card_str)
      :classmethod:


      Create a card from a string representation.

      :param card_str: A string like "AH" (Ace of Hearts) or "10S" (Ten of Spades).

      :returns: A new Card instance.

      :raises ValueError: If the string format is invalid.



   .. py:method:: is_face_card()

      Check if the card is a face card (Jack, Queen, or King).

      :returns: True if the card is a face card, False otherwise.



   .. py:property:: long_name
      :type: str


      Get the full name of the card.

      :returns: A string with the full name (e.g., "Ace of Spades").


.. py:class:: Rank(*args, **kwds)

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


   Playing card ranks.

   Standard card ranks for a 52-card deck, with values that facilitate numeric
   comparisons between cards.



.. py:class:: Suit(*args, **kwds)

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


   Playing card suits.

   Standard card suits for a 52-card deck, with optional support for additional special
   suits in non-standard decks.



   .. py:property:: color
      :type: str


      Get the color of the suit (red or black).

      :returns: "red" or "black".
      :rtype: The color as a string