feat: cardsInfo now also returns the modification time (#279)

* feat: cardsInfo now also returns the modification time

* minor: wrong indentation

* new method: get modification time of cards

* docs: mentions new method cardsModTime

* docs: readme now mentions that modification time is in the result from cardsInfo

Co-authored-by: thiswillbeyourgithub <github@32mail.33mail.comm>

README.md

@@ -444,10 +444,40 @@ corresponding to when the API was available for use.
     }
     ```
 
+*   **cardsModTime**
+
+    Returns a list of objects containings for each card ID the modification time.
+    This function is about 15 times faster than executing `cardsInfo`.
+
+    *Sample request*:
+    ```json
+    {
+        "action": "cardsModTime",
+        "version": 6,
+        "params": {
+            "cards": [1498938915662, 1502098034048]
+        }
+    }
+    ```
+
+    *Sample result*:
+    ```json
+    {
+        "result": [
+            {
+                "cardId": 1498938915662,
+                "mod": 1629454092
+            }
+        ],
+        "error": null
+    }
+    ```
+
+
 *   **cardsInfo**
 
     Returns a list of objects containing for each card ID the card fields, front and back sides including CSS, note
-    type, the note that the card belongs to, and deck name, as well as ease and interval.
+    type, the note that the card belongs to, and deck name, last modification timestamp as well as ease and interval.
 
     *Sample request*:
     ```json
@@ -484,7 +514,8 @@ corresponding to when the API was available for use.
                 "due": 1,
                 "reps": 1,
                 "lapses": 0,
-                "left": 6
+                "left": 6,
+                "mod": 1629454092
             },
             {
                 "answer": "back content",

plugin/__init__.py

@@ -1167,6 +1167,7 @@ class AnkiConnect:
                     'reps': card.reps,
                     'lapses': card.lapses,
                     'left': card.left,
+                    'mod': card.mod,
                 })
             except NotFoundError:
                 # Anki will give a NotFoundError if the card ID does not exist.
@@ -1177,6 +1178,24 @@ class AnkiConnect:
 
         return result
 
+    @util.api()
+    def cardsModTime(self, cards):
+        result = []
+        for cid in cards:
+            try:
+                card = self.getCard(cid)
+                result.append({
+                    'cardId': card.id,
+                    'mod': card.mod,
+                })
+            except NotFoundError:
+                # Anki will give a NotFoundError if the card ID does not exist.
+                # Best behavior is probably to add an 'empty card' to the
+                # returned result, so that the items of the input and return
+                # lists correspond.
+                result.append({})
+        return result
+
 
     @util.api()
     def forgetCards(self, cards):