haive.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 haive.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 haive.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 haive.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