games.cards.models.card¶

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.

Example

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

Classes¶

`Card`	A playing card with rank and suit.
`Rank`	Playing card ranks.
`Suit`	Playing card suits.

Module Contents¶

class games.cards.models.card.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.

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

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

value¶: The numeric value of the card for comparisons.

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.

Parameters:

rank (Rank) – The rank of the card.
suit (Suit) – The suit of the card.

Raises:

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

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.
Return type:: int

classmethod from_string(card_str)¶

Create a card from a string representation.

Parameters:: card_str (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.
Return type:: Card

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.
Return type:: bool

property long_name: str¶

Get the full name of the card.

Returns:: A string with the full name (e.g., “Ace of Spades”).
Return type:: str

class games.cards.models.card.Rank(*args, **kwds)¶

Bases: enum.Enum

Playing card ranks.

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

class games.cards.models.card.Suit(*args, **kwds)¶

Bases: enum.Enum

Playing card suits.

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

property color: str¶

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

Returns:: “red” or “black”.
Return type:: The color as a string