PyDataMailBox #1 Add getdata method (#2)

Author: Othman Moumni Abdou

HISTORY.md

@@ -1,5 +1,9 @@
 ## History
 
+### 0.2.2
+
+- Add `getdata` method
+
 ### 0.2.1
 
 - Add global request timeout

docs/home.md

@@ -25,4 +25,7 @@ client.getewon(name="test")
 # Iterate on all the data by chunk
 for data in client.iterate_syncdata():
     pass
+
+# get tag dat for a given period
+client.getdata(1, 1, '2021-07-15T12:30:20', '2021-07-15T12:30:33')
 ```

pydatamailbox/client.py

@@ -126,6 +126,39 @@ def syncdata(self, last_transaction_id=None):
             data["lastTransactionId"] = last_transaction_id
         return self._request(url=self._build_url("syncdata"), data=data)
 
+    def getdata(self, ewon_id, tag_id, from_ts, to_ts, limit=None):
+        """
+        ``getdata`` is used as a “one-shot” request to retrieve filtered data based on specific
+        criteria. It is not destined to grab historical data with the same timestamp or enormous
+        data involving the use of the moreData filter.
+
+        :param ewon_id: The ID of the single Ewon gateway for which data from DataMailbox is requested.
+        :param tag_id: ID of the single tag for which data from DataMailbox is requested.
+        :param from_ts: Timestamp after which data should be returned. No data older than this time stamp will
+be sent in ISO format.
+        :param to_ts: Timestamp before which data should be returned. No data newer than this time stamp
+will be sent in ISO format
+        :param limit: The maximum amount of historical data returned.
+            The historical data is the historical tag values but also the historical alarms. If you set the
+            limit to 4, the response will consist in 4 historical tag values and 4 historical alarms (if
+            available) for each tag of each Ewon gateway allowed bu the Talk2M token.
+            If the size of the historical data saved in the DataMailbox exceeds this limit, only the
+            oldest historical data will be returned and the result contains a moreDataAvailable value
+            indicating that more data is available on the server.
+            If limit is not used or is too high, the DataMailbox uses a limit pre-defined in the system
+            (server-side).
+        """
+        data = {
+            **self.data,
+            "ewonId": ewon_id,
+            "tagId": tag_id,
+            "from": from_ts,
+            "to": to_ts,
+        }
+        if limit:
+            data["limit"] = limit
+        return self._request(url=self._build_url("getdata"), data=data)
+
     def iterate_syncdata(self, last_transaction_id=None):
         """
         Returns an iterator on syncdata.

setup.py

@@ -42,6 +42,6 @@
     test_suite="tests",
     tests_require=test_requirements,
     url="https://github.com/optimdata/pydatamailbox",
-    version="0.2.1",
+    version="0.2.2",
     zip_safe=False,
 )

tests/test_pydatamailbox.py

@@ -41,6 +41,28 @@ def syncdata(request, context):
                 "moreDataAvailable": "lastTransactionId" not in request._request.body,
             }
 
+        def getdata(request, context):
+            return {
+                "ewons": [
+                    {
+                        **ewon,
+                        "tags": [
+                            {
+                                **tag,
+                                "history": [
+                                    {"date": "2021-07-15T12:30:22Z", "value": 1},
+                                    {"date": "2021-07-15T12:30:28Z", "value": 0},
+                                    {"date": "2021-07-15T12:30:29Z", "value": 1},
+                                ],
+                            }
+                        ],
+                        "lastSynchroDate": "2021-07-16T14:59:40Z",
+                        "timeZone": "Europe/Paris",
+                    }
+                ],
+                "success": True,
+            }
+
         ewon = {"id": 1, "name": "test"}
         tag = {
             "id": 1,
@@ -85,6 +107,7 @@ def syncdata(request, context):
             },
         )
         self.post("https://data.talk2m.com/syncdata", json=syncdata)
+        self.post("https://data.talk2m.com/getdata", json=getdata)
         self.post(
             "https://m2web.talk2m.com/t2mapi/getaccountinfo",
             json={
@@ -150,6 +173,7 @@ def test_datamailbox():
         assert client.syncdata()
         assert client.syncdata(last_transaction_id=1)
         assert list(client.iterate_syncdata())
+        assert client.getdata(1, 1, "2021-07-15T12:30:20", "2021-07-15T12:30:33")
         with pytest.raises(DataMailboxArgsError):
             client.getewon()