API¶
pyCardDeck¶
Deck of cards with all the logic, so you don’t have to!
copyright: |
|
---|---|
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
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 wayCards 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
- cards (List[CardType]) –
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 thatreshuffle
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: 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: 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: 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: 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 existsFalse if doesn’t existReturn 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.
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 positionwhere 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 containingjson/yaml generated by Deck.export(). It’s not safe to trust your userswith 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
- to_load (str) –
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
attributeReturns: 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: 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!
Exceptions¶
-
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