API

pyCardDeck

Deck of cards with all the logic, so you don’t have to!

copyright:
  1. 2016 David Jetelina
license:

MIT

Types

pyCardDeck isn’t strict about types. It’s however nice to use Python 3’s type annotations. That’s why we have custom types set up when needed

CardType

Can be either instance of an object, string or an integer. Basically, it’s important that they aren’t bool or NoneType. It’s however recommended to inherit from one of the classes in Cards

Classes and Functions

Deck

class pyCardDeck.deck.Deck(cards: object = None, reshuffle: object = True, name: object = None, discard: Optional[Deck] = None)[source]

Deck you will be using. Make sure to create the instance somewhere reachable :)

Parameters:
  • cards (List[CardType]) –
    Use this parameter if you don’t plan to register your cards another way
    Cards can be either an instance of a object, string or an integer,
    the documentation will be calling this CardType (because of Python’s rank hinting)
  • reshuffle (bool) – Set reshuffle to false if you want your deck not to reshuffle after it’s depleted
  • name (string) – Name of the deck, used when converting the Deck instance into string
  • discard (Union[Deck, None]) – optional Deck object to use as discard pile

Attributes

Deck.name
Returns:The name of the deck
Return type:str
Deck.reshuffle
Returns:Whether the deck will be reshuffled when drawn out
Return type:bool
Deck._cards
Returns:Cards in the deck
Return type:list
Deck._discard_pile

Note

Cards are not put in the discard pile automatically after drawing, the code assumes they went into a hand of sorts and must be discarded with discard() from there. This means that reshuffle doesn’t work on one card deck as you can’t reshuffle an empty deck (errors.NoCards would be raised).

Returns:Cards in the discard pile
Return type:list
Deck.empty
Returns:Whether the deck is empty
Return type:bool
Deck.cards_left

Cards left in the deck

Returns:Number of cards in the deck
Return type:int
Deck.discarded

Cards in the discard pile

Returns:Number of cards in the discard pile
Return type:int
Deck.json

Alternative to Deck.export(“json”)

Returns:jsonpickled Deck
Return type:str
Deck.yaml

Alternative to Deck.export(“yaml”)

Returns:yaml dump of the Deck
Return type:str

Card drawing

Deck.draw() → object[source]

Draw the topmost card from the deck

Returns:

Card from the list

Return type:

CardType

Raises:
  • OutOfCards – when there are no cards in the deck
  • NoCards – when the deck runs out of cards (no reshuffle)
Deck.draw_bottom() → object[source]

Draw the bottommost card from the deck

Returns:

Card from the list

Return type:

CardType

Raises:
  • OutOfCards – when there are no cards in the deck
  • NoCards – when the deck runs out of cards (no reshuffle)
Deck.draw_random() → object[source]

Draw a random card from the deck

Returns:

Card from the list

Return type:

CardType

Raises:
  • OutOfCards – when there are no cards in the deck
  • NoCards – when the deck runs out of cards (no reshuffle)
Deck.draw_specific(specific_card: object) → object[source]

Draw a specific card from the deck

Note

For card instances to match, they should have __eq__ method set to compare their equality. If you don’t want to set those up, make sure their __dict__ are the same and their name is the same.

If you are using a string or an integer, don’t worry about this!

Parameters:

specific_card (CardType) – Card identical to the one you are looking for

Returns:

Card from the list

Return type:

CardType

Raises:
  • OutOfCards – when there are no cards in the deck
  • NoCards – when the deck runs out of cards (no reshuffle)
  • CardNotFound – when the card is not found in the deck

Card information

Deck.card_exists(card: object) → bool[source]

Checks if a card exists in the deck

Note

For card instances to match, they should have __eq__ method set to compare their equality. If you don’t want to set those up, make sure their __dict__ are the same and their name is the same.

If you are using a string or an integer, don’t worry about this!

Parameters:card (CardType) – Card identical to the one you are looking for
Returns:
True if exists
False if doesn’t exist
Return type:bool

Deck Manipulation

Deck.shuffle() → None[source]

Randomizes the order of cards in the deck

Raises:NoCards – when there are no cards to be shuffled
Deck.shuffle_back() → object[source]

Shuffles the discard pile back into the main pile

Deck.discard(card: object) → None[source]

Puts a card into the discard pile

Parameters:card (CardType) – Card to be discarded
Raises:NotACard – When you try to insert False/None into a discard pile
Deck.add_single(card: object, position: int = False) → None[source]

Shuffles (or inserts) a single card into the active deck

Parameters:
  • card (CardType) – Card you want to insert
  • position (int) –
    If you want to let player insert card to a specific location, use position
    where 0 = top of the deck, 1 = second card from top etc.
    By default the position is random
Deck.add_many(cards: List[object]) → None[source]

Shuffles a list of cards into the deck

Parameters:cards (List[CardType]) – Cards you want to shuffle in
Deck.show_top(number: int) → List[object][source]

Selects the top X cards from the deck without drawing them

Useful for mechanics like scry in Magic The Gathering

If there are less cards left than you want to show, it will show only the remaining cards

Parameters:number (int) – How many cards you want to show
Returns:Cards you want to show
Return type:List[CardType]

Import/Export

Deck.export(fmt: str, to_file: bool = False, location: str = None) → str[source]

Export the deck. By default it returns string with either JSON or YaML, but if you set to_file=True, you can instead save the deck as a file. If no location (with filename) is provided, it’ll save to the folder the script is opened from as exported_deck without an extension.

Parameters:
  • fmt (str) – Desired format, either YaML or JSON
  • to_file (bool) – Whether you want to get a string back or save to a file
  • location (str) – Where you want to save your file - include file name!
Raises:

UnknownFormat – When entered format is not supported

Returns:

Your exported deck as a string in your desired format

Return type:

str

Deck.load(to_load: str, is_file: bool = False) → None[source]

Way to override a deck instance with a saved deck from either yaml, JSON or a file with either of those.

The library will first try to check if you have a save location saved, then verifies if the file exists as a path to a file. If it doesn’t, it’l assume it’s a string with one of the supported formats and will load from those.

Parameters:
  • to_load (str) –
    This should be either a path to a file or a string containing
    json/yaml generated by Deck.export(). It’s not safe to trust your users
    with this, as they can provide harmful pickled JSON (see jsonpickle docs for more)
  • is_file (bool) – whether to_load is a file path or actual data. Default is False
Raises:

UnknownFormat – When the entered yaml or json is not valid

Deck.load_standard_deck() → None[source]

Loads a standard deck of 52 cards into the deck

Magic Methods

Deck.__repr__() → str[source]

Used for representation of the object

called with repr(Deck)

Returns:‘Deck of cards’
Return type:string
Deck.__str__() → str[source]

Used for representation of the object for humans

called with str(Deck)

This method is also called when you are providing arguments to str.format(), you can just provide your Deck instance and it will magically know the name, yay!

Returns:Name of the deck if it has a name or ‘Deck of cards’ if it has none
Return type:string
Deck.__len__() → int[source]

Instead of doing len(Deck.cards) you can just check len(Deck)

It’s however recommended to use the cards_left attribute

Returns:Number of cards left in the deck
Return type:int

Other Functions

pyCardDeck.deck._card_compare(card: object, second_card: object) → bool[source]

Function for comparing two cards. First it checks their __eq__, if that returns False, it checks __dict__ and name of the Class that spawned them .

Parameters:
  • card (CardType) – First card to match
  • second_card (CardType) – Second card to match
Returns:

Whether they are the same

Return type:

bool

pyCardDeck.deck._get_exported_string(format_stripped: str, deck: pyCardDeck.deck.Deck) → str[source]

Helper function to Deck.export()

Parameters:
  • format_stripped (str) – Desired format stripped of any spaces and lowercase
  • deck (Deck) – instance of a Deck
Returns:

YAML/JSON string of the deck

Return type:

str

Raises:

UnknownFormat – when it doesn’t recognize format_stripped

Cards

These classes are only recommended to inherit from, feel free to use your own!

class pyCardDeck.cards.BaseCard(name: str)[source]

This is an example Card, showing that each Card should have a name.

This is good, because when we can show player their cards just by converting them to strings.

class pyCardDeck.cards.PokerCard(suit: str, rank: str, name: str)[source]

Example Poker Card, since Poker is a a deck of Unique cards, we can say that if their name equals, they equal too.

Exceptions

exception pyCardDeck.errors.DeckException[source]

Base exception class for pyCardDeck

exception pyCardDeck.errors.NoCards[source]

Exception that’s thrown when there are no cards to be manipulated.

exception pyCardDeck.errors.OutOfCards[source]

Exception that’s thrown when the deck runs out of cards. Unlike NoCardsException, this will happen naturally when reshuffling is disabled

exception pyCardDeck.errors.NotACard[source]

Exception that’s thrown when the manipulated object is False/None

exception pyCardDeck.errors.CardNotFound[source]

Exception that’s thrown when a card is not found

exception pyCardDeck.errors.UnknownFormat[source]

Exception thrown when trying to export to a unknown format. Supported formats: YaML, JSON