Merge branch 'dev'

CHANGES.rst

@@ -2,16 +2,64 @@
 PyDealer Changelog
 ==================
 
-**Changes**
-    Major changes that may break things.
-**Features**
-    New features that usually don't break anything.
-**Refactoring**
-    Changes/improvements to the code that shouldn't break anything.
-**Bugfixes**
+**Changes** -- *Will probably break things*
+    Major changes to the package/code.
+**Features** -- *May or may not break things*
+    New, added features/functionality.
+**Refactoring** -- *Shouldn't break things*
+    Changes/improvements to the code.
+**Bugfixes** -- *Won't break things*
     Smaller bugfixes, fixing broken functionality.
-**Other**
-    Any other changes that may be of note.
+**Other** -- *Won't break things*
+    Any other changes that may be of note, such as updating/modifying of documentation.
+
+v1.3.0 (03-07-2014)
+-------------------
+
+Changes
+^^^^^^^
+
+- Added a couple of extra arguments to ``Deck.__init__``.
+    - ``Deck.__init__`` now takes a list of cards as the first argument, ``cards``, so you can instantiate a deck with a given list of cards.
+    - You can now prevent a ``Deck`` from building itself automatically, on instantiation, with the bool argument ``build``. If ``build=False``, the ``Deck`` skips building.
+- ``Deck.find``, and ``Deck.get`` no longer accept lists of terms, and only accept a single term. I have made separate methods for finding/getting lists of terms (see the features section below).
+    - These methods also only return lists (empty or otherwise) now.
+- Scrapped ``Deck.peek``, because it was pretty much useless.
+- The abbreviation for jokers is now "JKR", instead of "JK".
+
+Features
+^^^^^^^^
+
+- PyDealer is now hosted on the PyPi! Installing just got that much easier.
+- ``Deck``s now store their ``Cards`` in a deque, instead of a list.
+- Added ``Deck.find_list``, and ``Deck.get_list``, for retrieving items matching the terms in a given list.
+- Added a ``sort`` kwarg to ``Deck``, ``Deck.build``, ``Deck.find``, ``Deck.find_list``, ``Deck.get`` and ``Deck.get_list``.
+    - ``sort`` is a boolean argument, which, if ``True``, will sort the newly built ``Deck``, or results by poker rank, otherwise they are built/returned in the order they are created/found. Default is ``False``.
+- Added the global function ``compare_decks``, for checking whether two ``Deck`` instances have the same cards (``Card`` suits & values, not ``Card``  instances).
+- Added the global functions ``sort_cards``, and ``sort_card_indices``, for sorting given cards, or deck indices by poker ranks.
+- Added the method ``Deck.set_cards``, to set a ``Deck``'s contents to a given list of cards at any time. You could just do ``Deck.cards = deque([Card, Card, ...])`` as well. This method just handles the extra step of converting a list to a deque.
+- ``Deck.shuffle()`` now takes the argument ``times``, which is the number of times to shuffle.
+
+Refactoring
+^^^^^^^^^^^
+
+- Changed ``Deck.cards`` to a deque, instead of a list.
+- Tweaked the item retrieval methods ``Deck.find``, and ``Deck.find_list``, so that they use ``enumerate`` in their loops now, instead of getting card indexes using ``self.cards.index(card)``.
+- Changed the ordering of the items in ``FACES``, and ``SUITS``, so that ``Deck``s are sorted by big two ranks by default, when built.
+
+Bugfixes
+^^^^^^^^
+
+- Fixed ``check_term`` again. Should actually work with 10s now. Really.
+- Added a dirty little try/except fix for the ``xrange`` function, because it doesn't exist in Python 3. If ``xrange`` can't be found, implying the package is being run under Python 3, then Python 3's ``range`` is assigned to the variable ``xrange``, using ``xrange = range``.
+- Changed ``Deck.find``, so that it doesn't return lists with duplicates.
+
+Other
+^^^^^
+
+- Tweaked the function/method docstrings a bit, to try to make them easier to read.
+- Updated the readme.
+- Tweaked the section key at the top of the changelog slightly.
 
 v1.2.2 (30-06-2014)
 -------------------

README.rst

@@ -2,9 +2,9 @@
 PyDealer: Playing Card Package
 ==============================
 
-A simple package for constructing a ``Deck`` object, of 52 common 
-playing cards. Each card is a separate ``Card`` object, with a name, value, 
-suit, and abbreviation. Could possibly be used for a command prompt/console, card-based game, or even a graphical game as well, I suppose.
+A simple package for constructing ``Deck`` instances, of 52 common 
+playing cards. Each card is a separate ``Card`` instance, with a name, value, 
+suit, and abbreviation. Could possibly be used for a CLI card-based game, or even a graphical game as well, I suppose.
 
 Attention
 =========
@@ -14,17 +14,17 @@ If you are going to make a pull request, please do so on the dev branch, thanks.
 Install/Uninstall with PIP_
 ===========================
 
-Install Latest Version
-----------------------
+Install
+-------
 ::
 
-    pip install https://github.com/Trebek/pydealer/archive/master.zip
+    pip install pydealer
 
-Install Development Version
----------------------------
+Update
+------
 ::
 
-    pip install https://github.com/Trebek/pydealer/archive/dev.zip
+    pip install pydealer -U
 
 Uninstall
 ---------
@@ -60,8 +60,8 @@ Make a Deck, Deal Some Cards
     4 of Clubs
     6 of Hearts
 
-Peek at Specific Deck Indice
-----------------------------
+Peek at a Deck Indice
+---------------------
 ::
 
     import pydealer
@@ -70,7 +70,7 @@ Peek at Specific Deck Indice
     deck.shuffle()
 
     i = 25
-    card = deck.peek(i)
+    card = deck[i]
 
     print card
 
@@ -79,8 +79,8 @@ Peek at Specific Deck Indice
 
     3 of Spades
 
-Find Specific Card(s) Locations
--------------------------------
+Find Specific Card Locations
+----------------------------
 
 You can search using full card names, abbreviations, suits, or values.
 
@@ -96,7 +96,7 @@ Single Card
     name = "Ace of Spades"
     i = deck.find(name)
 
-    card = deck.peek(i)
+    card = deck[i]
     print "deck[%d] = %s" % (i, card)
 
 **Example output:**
@@ -115,11 +115,11 @@ The list can contain full card names, abbreviations, suits, values, or a mixture
     deck.shuffle()
 
     terms = ["AS", "Queen of Hearts", "2"]
-    indices = deck.find(terms)
+    indices = deck.find_list(terms)
 
     for i in indices:
-        card = deck.peek(i)
-        print "deck.cards[%d] = %s" % (i, card)
+        card = deck[i]
+        print "deck[%d] = %s" % (i, card)
 
 **Example output:**
 ::
@@ -131,8 +131,8 @@ The list can contain full card names, abbreviations, suits, values, or a mixture
     deck.cards[28] = 2 of Clubs
     deck.cards[34] = Ace of Spades
 
-Get & Remove Specific Card(s)
------------------------------
+Get & Remove Specific Cards
+---------------------------
 ::
 
     import pydealer
@@ -144,19 +144,30 @@ Get & Remove Specific Card(s)
     card = deck.get(name)
 
     print card
-    print
+
+**Example output:**
+::
+
+    Ace of Spades
+
+Get & Remove a List of Cards
+----------------------------
+::
+
+    import pydealer
+
+    deck = Deck()
+    deck.shuffle()
 
     terms = ["KD", "Queen of Hearts", "2"]
-    cards = deck.get(terms)
+    cards = deck.get_list(terms)
 
     for card in cards:
         print card
 
 **Example output:**
 ::
 
-    Ace of Spades
-    
     King of Diamonds
     Queen of Hearts
     2 of Diamonds