API Documentation¶
This is the PyDealer API documentation. It contains the documentation extracted from the docstrings of the various classes, methods, and functions in the PyDealer package. If you want to know what a certain function/method does, this is the place to look.
card Module¶
This module contains the Card class. Each Card instance represents a single playing card, of a given value and suit.
- class pydealer.card.Card(value, suit)¶
The Card class, each instance representing a single playing card.
Parameters: - value (str) – The card value.
- suit (str) – The card suit.
- eq(other, ranks=None)¶
Compares the card against another card, other, and checks whether the card is equal to other, based on the given rank dict.
Parameters: - other (Card) – The second Card to compare.
- ranks (dict) – The ranks to refer to for comparisons.
Returns: True or False.
- ge(other, ranks=None)¶
Compares the card against another card, other, and checks whether the card is greater than or equal to other, based on the given rank dict.
Parameters: - other (Card) – The second Card to compare.
- ranks (dict) – The ranks to refer to for comparisons.
Returns: True or False.
- gt(other, ranks=None)¶
Compares the card against another card, other, and checks whether the card is greater than other, based on the given rank dict.
Parameters: - other (Card) – The second Card to compare.
- ranks (dict) – The ranks to refer to for comparisons.
Returns: True or False.
- le(other, ranks=None)¶
Compares the card against another card, other, and checks whether the card is less than or equal to other, based on the given rank dict.
Parameters: - other (Card) – The second Card to compare.
- ranks (dict) – The ranks to refer to for comparisons.
Returns: True or False.
- lt(other, ranks=None)¶
Compares the card against another card, other, and checks whether the card is less than other, based on the given rank dict.
Parameters: - other (Card) – The second Card to compare.
- ranks (dict) – The ranks to refer to for comparisons.
Returns: True or False.
- ne(other, ranks=None)¶
Compares the card against another card, other, and checks whether the card is not equal to other, based on the given rank dict.
Parameters: - other (Card) – The second Card to compare.
- ranks (dict) – The ranks to refer to for comparisons.
Returns: True or False.
- pydealer.card.card_abbrev(value, suit)¶
Constructs an abbreviation for the card, using the given value, and suit.
Parameters: - value (str) – The value to use.
- suit (str) – The suit to use.
Returns: A newly constructed abbreviation, using the given value & suit
- pydealer.card.card_name(value, suit)¶
Constructs a name for the card, using the given value, and suit.
Parameters: - value (str) – The value to use.
- suit (str) – The suit to use.
Returns: A newly constructed name, using the given value & suit.
stack Module¶
This module contains the Stack class, which is the backbone of the PyDealer package. A Stack is essentially just a generic “card container”, with all of the methods users may need to work with the cards they contain. A Stack can be used as a hand, or a discard pile, etc.
- class pydealer.stack.Stack(**kwargs)¶
The Stack class, representing a collection of cards. This is the main ‘card container’ class, with methods for manipulating it’s contents.
Parameters: - cards (list) – A list of cards to be the initial contents of the Stack.
- ranks (dict) – If sort=True, The rank dict to reference for sorting. Defaults to DEFAULT_RANKS.
- sort (bool) – Whether or not to sort the stack upon instantiation.
- add(cards, end='top')¶
Adds the given list of Card instances to the top of the stack.
Parameters: - cards – The cards to add to the Stack. Can be a single Card instance, or a list of cards.
- end (str) – The end of the Stack to add the cards to. Can be TOP (“top”) or BOTTOM (“bottom”).
- cards¶
The cards property.
Returns: The cards in the Stack/Deck.
- deal(num=1, end='top')¶
Returns a list of cards, which are removed from the Stack.
Parameters: - num (int) – The number of cards to deal.
- end (str) – Which end to deal from. Can be 0 (top) or 1 (bottom).
Returns: The given number of cards from the stack.
- empty(return_cards=False)¶
Empties the stack, removing all cards from it, and returns them.
Parameters: return_cards (bool) – Whether or not to return the cards. Returns: If return_cards=True, a list containing the cards removed from the Stack.
- find(term, limit=0, sort=False, ranks=None)¶
Searches the stack for cards with a value, suit, name, or abbreviation matching the given argument, ‘term’.
Parameters: - term (str) – The search term. Can be a card full name, value, suit, or abbreviation.
- limit (int) – The number of items to retrieve for each term. 0 equals no limit.
- sort (bool) – Whether or not to sort the results.
- ranks (dict) – The rank dict to reference for sorting. If None, it will default to DEFAULT_RANKS.
Returns: A list of stack indices for the cards matching the given terms, if found.
- find_list(terms, limit=0, sort=False, ranks=None)¶
Searches the stack for cards with a value, suit, name, or abbreviation matching the given argument, ‘terms’.
Parameters: - terms (list) – The search terms. Can be card full names, suits, values, or abbreviations.
- limit (int) – The number of items to retrieve for each term.
- sort (bool) – Whether or not to sort the results, by poker ranks.
- ranks (dict) – The rank dict to reference for sorting. If None, it will default to DEFAULT_RANKS.
Returns: A list of stack indices for the cards matching the given terms, if found.
- get(term, limit=0, sort=False, ranks=None)¶
Get the specified card from the stack.
Parameters: - term – The search term. Can be a card full name, value, suit, abbreviation, or stack indice.
- limit (int) – The number of items to retrieve for each term.
- sort (bool) – Whether or not to sort the results, by poker ranks.
- ranks (dict) – The rank dict to reference for sorting. If None, it will default to DEFAULT_RANKS.
Returns: A list of the specified cards, if found.
- get_list(terms, limit=0, sort=False, ranks=None)¶
Get the specified cards from the stack.
Parameters: - term – The search term. Can be a card full name, value, suit, abbreviation, or stack indice.
- limit (int) – The number of items to retrieve for each term.
- sort (bool) – Whether or not to sort the results, by poker ranks.
- ranks (dict) – The rank dict to reference for sorting. If None, it will default to DEFAULT_RANKS.
Returns: A list of the specified cards, if found.
- insert(card, indice=-1)¶
Insert a given card into the stack at a given indice.
Parameters: - card (Card) – The card to insert into the stack.
- indice (int) – Where to insert the given card.
- insert_list(cards, indice=-1)¶
Insert a list of given cards into the stack at a given indice.
Parameters: - cards (list) – The list of cards to insert into the stack.
- indice (int) – Where to insert the given cards.
- is_sorted(ranks=None)¶
Checks whether the stack is sorted.
Parameters: ranks (dict) – The rank dict to reference for checking. If None, it will default to DEFAULT_RANKS. Returns: Whether or not the cards are sorted.
- open_cards(filename=None)¶
Open cards from a txt file.
Parameters: filename (str) – The filename of the deck file to open. If no filename given, defaults to “cards-YYYYMMDD.txt”, where “YYYYMMDD” is the year, month, and day. For example, “cards-20140711.txt”.
- random_card(remove=False)¶
Returns a random card from the Stack. If remove=True, it will also remove the card from the deck.
Parameters: remove (bool) – Whether or not to remove the card from the deck. Returns: A random Card object, from the Stack.
- reverse()¶
Reverse the order of the Stack in place.
- save_cards(filename=None)¶
Save the current stack contents, in plain text, to a txt file.
Parameters: filename (str) – The filename to use for the file. If no filename given, defaults to “cards-YYYYMMDD.txt”, where “YYYYMMDD” is the year, month, and day. For example, “cards-20140711.txt”.
- set_cards(cards)¶
Change the Deck’s current contents to the given cards.
Parameters: cards (list) – The Cards to assign to the stack.
- shuffle(times=1)¶
Shuffles the Stack.
Note
Shuffling large numbers of cards (100,000+) may take a while.
Parameters: times (int) – The number of times to shuffle.
- size¶
Counts the number of cards currently in the stack.
Returns: The number of cards in the stack.
- sort(ranks=None)¶
Sorts the stack, either by poker ranks, or big two ranks.
Parameters: ranks (dict) – The rank dict to reference for sorting. If None, it will default to DEFAULT_RANKS. Returns: The sorted cards.
- split(indice=None)¶
Splits the Stack, either in half, or at the given indice, into two separate Stacks.
Parameters: indice (int) – Optional. The indice to split the Stack at. Defaults to the middle of the Stack. Returns: The two parts of the Stack, as separate Stack instances.
- pydealer.stack.convert_to_stack(deck)¶
Convert a Deck to a Stack.
Parameters: deck (Deck) – The Deck to convert. Returns: A new Stack instance, containing the cards from the given Deck instance.
deck Module¶
This module contains the Deck class. Each Deck instance contains a full, 52 card French deck of playing cards upon instantiation. The Deck class is a subclass of the Stack class, with a few extra/differing methods.
- class pydealer.deck.Deck(**kwargs)¶
Bases: pydealer.stack.Stack
The Deck class, representing the deck that the cards will be in. It is a sublcass of Stack, sharing all of the same methods, in addition to a couple of others you would expect a deck class to have.
Warning
At the moment, adding Jokers may cause some (most) functions/methods to throw errors.
Parameters: - cards – A list of cards to be the initial contents of the Deck. If provided, the deck will not automatically build a new deck. Can be a Stack, Deck, or list instance.
- jokers (bool) – Whether or not to include jokers in the deck.
- num_jokers (int) – How many jokers to add to the deck.
- build (bool) – Whether or not to build the deck on instantiation.
- rebuild (bool) – Whether or not to rebuild the deck when it runs out of cards due to dealing.
- re_shuffle (bool) – Whether or not to shuffle the deck after rebuilding.
- ranks (dict) – The rank dict that will be referenced by the sorting methods etc. Defaults to DEFAULT_RANKS
- build(jokers=False, num_jokers=0)¶
Builds a standard 52 card French deck of Card instances.
Parameters: - jokers (bool) – Whether or not to include jokers in the deck.
- num_jokers (int) – The number of jokers to include.
- deal(num=1, rebuild=False, shuffle=False, end='top')¶
Returns a list of cards, which are removed from the deck.
Parameters: - num (int) – The number of cards to deal.
- rebuild (bool) – Whether or not to rebuild the deck when cards run out.
- shuffle (bool) – Whether or not to shuffle on rebuild.
- end (str) – The end of the Stack to add the cards to. Can be TOP (“top”) or BOTTOM (“bottom”).
Returns: A given number of cards from the deck.
- pydealer.deck.convert_to_deck(stack)¶
Convert a Stack to a Deck.
Parameters: stack (Stack) – The Stack instance to convert.
tools Module¶
The tools module contains functions for working with sequences of cards, some of which are used by the classes in the PyDealer package, such as the functions build_cards, sort_cards, and check_term for example.
- pydealer.tools.build_cards(jokers=False, num_jokers=0)¶
Builds a list containing a full French deck of 52 Card instances. The cards are sorted according to DEFAULT_RANKS.
Parameters: - jokers (bool) – Whether or not to include jokers in the deck.
- num_jokers (int) – The number of jokers to include.
Returns: A list containing a full French deck of 52 Card instances.
- pydealer.tools.check_sorted(cards, ranks=None)¶
Checks whether the given cards are sorted by the given ranks.
Parameters: - cards – The cards to check. Can be a Stack, Deck, or list of Card isntances.
- ranks (dict) – The ranks to check against. Default is DEFAULT_RANKS.
Returns: True or False.
- pydealer.tools.check_term(card, term)¶
Checks a given search term against a given card’s full name, suit, value, and abbreviation.
Parameters: - card (Card) – The card to check.
- term (str) – The search term to check for. Can be a card full name, suit, value, or abbreviation.
Returns: True or False.
- pydealer.tools.compare_stacks(cards_x, cards_y, sorted=False)¶
Checks whether two given Stack, Deck, or list instances, contain the same cards (based on value & suit, not instance). Does not take into account the ordering.
Parameters: - cards_x – The first stack to check. Can be a Stack, Deck, or list instance.
- cards_y – The second stack to check. Can be a Stack, Deck, or list instance.
- sorted (bool) – Whether or not the cards are already sorted. If True, then compare_stacks will skip the sorting process.
Returns: True or False.
- pydealer.tools.find_card(cards, term, limit=0, sort=False, ranks=None)¶
Searches the given cards for cards with a value, suit, name, or abbreviation matching the given argument, term.
Parameters: - cards – The cards to search. Can be a Stack, Deck or list.
- term (str) – The search term. Can be a card full name, value, suit, or abbreviation.
- limit (int) – The number of items to retrieve for each term.
- sort (bool) – Whether or not to sort the results, by poker ranks.
- ranks (dict) – The rank dict to reference for sorting. If None, it will default to DEFAULT_RANKS.
Returns: A list of indices for the cards matching the given terms, if found.
- pydealer.tools.find_list(cards, terms, limit=0, sort=False, ranks=None)¶
Searches the given cards for cards with a value, suit, name, or abbreviation matching the given argument, terms.
Parameters: - cards – The cards to search. Can be a Stack, Deck or list.
- terms (list) – The search terms. Can be card full names, suits, values, or abbreviations.
- limit (int) – The number of items to retrieve for each term. 0 == no limit.
- sort (bool) – Whether or not to sort the results, by poker ranks.
- ranks (dict) – The rank dict to reference for sorting. If None, it will default to DEFAULT_RANKS.
Returns: A list of indices for the cards matching the given terms, if found.
- pydealer.tools.get_card(cards, term, limit=0, sort=False, ranks=None)¶
Get the specified card from the stack.
Parameters: - cards – The cards to get from. Can be a Stack, Deck or list.
- term (str) – The card’s full name, value, suit, abbreviation, or stack indice.
- limit (int) – The number of items to retrieve for each term.
- sort (bool) – Whether or not to sort the results, by poker ranks.
- ranks (dict) – If sort=True, the rank dict to refer to for sorting.
Returns: A copy of the given cards, with the found cards removed, and a list of the specified cards, if found.
- pydealer.tools.get_list(cards, terms, limit=0, sort=False, ranks=None)¶
Get the specified cards from the stack.
Parameters: - cards – The cards to get from. Can be a Stack, Deck or list.
- terms (list) – A list of card’s full names, values, suits, abbreviations, or stack indices.
- limit (int) – The number of items to retrieve for each term.
- sort (bool) – Whether or not to sort the results, by poker ranks.
- ranks (dict) – If sort=True, the rank dict to refer to for sorting.
Returns: A list of the specified cards, if found.
- pydealer.tools.open_cards(filename=None)¶
Open cards from a txt file.
Parameters: filename (str) – The filename of the deck file to open. If no filename given, defaults to “cards-YYYYMMDD.txt”, where “YYYYMMDD” is the year, month, and day. For example, “cards-20140711.txt”. Returns: The opened cards, as a list.
- pydealer.tools.random_card(cards, remove=False)¶
Returns a random card from the Stack. If remove=True, it will also remove the card from the deck.
Parameters: remove (bool) – Whether or not to remove the card from the deck. Returns: A random Card object, from the Stack.
- pydealer.tools.save_cards(cards, filename=None)¶
Save the given cards, in plain text, to a txt file.
Parameters: - cards – The cards to save. Can be a Stack, Deck, or list.
- filename (str) – The filename to use for the cards file. If no filename given, defaults to “cards-YYYYMMDD.txt”, where “YYYYMMDD” is the year, month, and day. For example, “cards-20140711.txt”.
- pydealer.tools.sort_card_indices(cards, indices, ranks=None)¶
Sorts the given Deck indices by the given ranks. Must also supply the Stack, Deck, or list that the indices are from.
Parameters: - cards – The cards the indices are from. Can be a Stack, Deck, or list
- indices (list) – The indices to sort.
- ranks (dict) – The rank dict to reference for sorting. If None, it will default to DEFAULT_RANKS.
Returns: The sorted indices.
- pydealer.tools.sort_cards(cards, ranks=None)¶
Sorts a given list of cards, either by poker ranks, or big two ranks.
Parameters: - cards – The cards to sort.
- ranks (dict) – The rank dict to reference for sorting. If None, it will default to DEFAULT_RANKS.
Returns: The sorted cards.
const Module¶
These are the few constants that are used by the PyDealer package. The poker ranks, and big two ranks could be used for sorting, or by anyone making a game that relies on those ranks. PyDealer references DEFAULT_RANKS for sorting order, and ordering of newly instantiated decks by default.
- pydealer.const.SUITS¶
["Diamonds", "Clubs", "Hearts", "Spades"]
- pydealer.const.VALUES¶
["2", "3", "4", "5", "6", "7", "8", "9", "10", "Jack", "Queen", "King", "Ace"]
- pydealer.const.BIG2_RANKS¶
{
"values": {
"2": 13,
"Ace": 12,
"King": 11,
"Queen": 10,
"Jack": 9,
"10": 8,
"9": 7,
"8": 6,
"7": 5,
"6": 4,
"5": 3,
"4": 2,
"3": 1,
},
"suits": {
"Spades": 4,
"Hearts": 3,
"Clubs": 2,
"Diamonds": 1
}
}
- pydealer.const.DEFAULT_RANKS¶
{
"values": {
"Ace": 13,
"King": 12,
"Queen": 11,
"Jack": 10,
"10": 9,
"9": 8,
"8": 7,
"7": 6,
"6": 5,
"5": 4,
"4": 3,
"3": 2,
"2": 1
},
"suits": {
"Spades": 4,
"Hearts": 3,
"Clubs": 2,
"Diamonds": 1
}
}
- pydealer.const.POKER_RANKS¶
{
"Ace": 13,
"King": 12,
"Queen": 11,
"Jack": 10,
"10": 9,
"9": 8,
"8": 7,
"7": 6,
"6": 5,
"5": 4,
"4": 3,
"3": 2,
"2": 1
}
- pydealer.const.TOP¶
"top"
- pydealer.const.BOTTOM¶
"bottom"