Created getEaseFactors and setEaseFactors for Cards, along with documentation and tests for the functions (#181)

Co-authored-by: sherpa <spencersharp1999@gmail.com>

actions/cards.md

@@ -1,5 +1,52 @@
 # Card Actions
 
+*   **getEaseFactors**
+
+    Returns an array with the ease factor for each of the given cards (in the same order).
+
+    *Sample request*:
+    ```json
+    {
+        "action": "getEaseFactors",
+        "version": 6,
+        "params": {
+            "cards": [1483959291685, 1483959293217]
+        }
+    }
+    ```
+
+    *Sample result*:
+    ```json
+    {
+        "result": [4100, 3900],
+        "error": null
+    }
+    ```
+
+*   **setEaseFactors**
+
+    Sets ease factor of cards by card ID; returns `true` if successful (all cards existed) or `false` otherwise.
+
+    *Sample request*:
+    ```json
+    {
+        "action": "setEaseFactors",
+        "version": 6,
+        "params": {
+            "cards": [1483959291685, 1483959293217],
+            "easeFactors": [4100, 3900]
+        }
+    }
+    ```
+
+    *Sample result*:
+    ```json
+    {
+        "result": [true, true],
+        "error": null
+    }
+    ```
+
 *   **suspend**
 
     Suspend cards by card ID; returns `true` if successful (at least one card wasn't already suspended) or `false`

plugin/__init__.py

@@ -566,7 +566,35 @@ class AnkiConnect:
     @util.api()
     def getTags(self):
         return self.collection().tags.all()
+    
+    @util.api()
+    def setEaseFactors(self, cards, easeFactors):
+        couldSetEaseFactors = []
+        ind = 0
+        for card in cards:
+            ankiCard = self.collection().getCard(card)
+            if ankiCard is None:
+                raise Exception('card was not found: {}'.format(card['id']))
+                couldSetEaseFactors.append(False)
+            else:
+                couldSetEaseFactors.append(True)
 
+            ankiCard.factor = easeFactors[ind]
+
+            ankiCard.flush()
+
+            ind += 1
+
+        return couldSetEaseFactors
+    
+    @util.api()
+    def getEaseFactors(self, cards):
+        easeFactors = []
+        for card in cards:
+            ankiCard = self.collection().getCard(card)
+            easeFactors.append(ankiCard.factor)
+
+        return easeFactors
 
     @util.api()
     def suspend(self, cards, suspend=True):

tests/test_cards.py

@@ -20,6 +20,16 @@ class TestCards(unittest.TestCase):
         cardIds = util.invoke('findCards', query='deck:test')
         self.assertEqual(len(cardIds), 1)
 
+        # setEaseFactors
+        EASE_TO_TRY = 4200
+        easeFactors = [EASE_TO_TRY for card in cardIds]
+        couldGetEaseFactors = util.invoke('setEaseFactors', cards=cardIds, easeFactors=easeFactors)
+        self.assertEqual([True for card in cardIds], couldGetEaseFactors)
+
+        # getEaseFactors
+        easeFactorsFound = util.invoke('getEaseFactors', cards=cardIds)
+        self.assertEqual(easeFactors, easeFactorsFound)
+
         # suspend
         util.invoke('suspend', cards=cardIds)