Merge pull request #81 from Kinto/collection_timestamp

Add `get_records_timestamp()`

Author: Natim

CHANGELOG.rst

@@ -7,7 +7,9 @@ This document describes changes between each past release.
 6.1.0 (unreleased)
 ==================
 
-- Nothing changed yet.
+**New features**
+
+- Add a ``get_records_timestamp`` method to get the collection ``ETag``. (#81)
 
 
 6.0.0 (2016-06-10)

README.rst

@@ -157,7 +157,10 @@ A record is a dict with the "permissions" and "data" keys.
                          collection='todos', bucket='default')
 
     # Retrieve all records.
-    record = client.get_records(collection='todos', bucket='default')
+    records = client.get_records(collection='todos', bucket='default')
+
+    # Retrieve records timestamp.
+    records_timestamp = client.get_records_timestamp(collection='todos', bucket='default')
 
     # Retrieve a specific record and update it.
     record = client.get_record('89881454-e4e9-4ef0-99a9-404d95900352',

kinto_http/__init__.py

@@ -69,6 +69,7 @@ def __init__(self, server_url=None, session=None, auth=None,
         self._bucket_name = bucket
         self._collection_name = collection
         self._server_settings = None
+        self._records_timestamp = {}
 
     def clone(self, **kwargs):
         kwargs.setdefault('session', self.session)
@@ -118,6 +119,11 @@ def _paginated(self, endpoint, records=None, if_none_match=None, **kwargs):
 
         record_resp, headers = self.session.request(
             'get', endpoint, headers=headers, params=kwargs)
+
+        # Save the current records collection timestamp
+        etag = headers.get('ETag', '').strip('"')
+        self._records_timestamp[endpoint] = etag
+
         if record_resp:
             records_tuples = [(r['id'], r) for r in record_resp['data']]
             records.update(collections.OrderedDict(records_tuples))
@@ -294,6 +300,20 @@ def delete_collections(self, bucket=None, safe=True, if_match=None):
 
     # Records
 
+    def get_records_timestamp(self, collection=None, bucket=None,
+                              **kwargs):
+        endpoint = self.get_endpoint('records',
+                                     bucket=bucket,
+                                     collection=collection)
+        if endpoint not in self._records_timestamp:
+            record_resp, headers = self.session.request('head', endpoint)
+
+            # Save the current records collection timestamp
+            etag = headers.get('ETag', '').strip('"')
+            self._records_timestamp[endpoint] = etag
+
+        return self._records_timestamp[endpoint]
+
     def get_records(self, collection=None, bucket=None, **kwargs):
         """Returns all the records"""
         endpoint = self.get_endpoint('records',

kinto_http/tests/test_client.py

@@ -537,6 +537,34 @@ def test_collection_can_retrieve_all_records(self):
         records = self.client.get_records()
         assert list(records) == [{'id': 'foo'}, {'id': 'bar'}]
 
+    def test_collection_can_retrieve_records_timestamp(self):
+        mock_response(self.session, data=[{'id': 'foo'}, {'id': 'bar'}],
+                      headers={"ETag": '"12345"'})
+        timestamp = self.client.get_records_timestamp()
+        assert timestamp == '12345'
+
+    def test_records_timestamp_is_cached(self):
+        mock_response(self.session, data=[{'id': 'foo'}, {'id': 'bar'}],
+                      headers={"ETag": '"12345"'})
+        self.client.get_records()
+        timestamp = self.client.get_records_timestamp()
+        assert timestamp == '12345'
+        assert self.session.request.call_count == 1
+
+    def test_records_timestamp_is_cached_per_collection(self):
+        mock_response(self.session, data=[{'id': 'foo'}, {'id': 'bar'}],
+                      headers={"ETag": '"12345"'})
+        self.client.get_records(collection="foo")
+        mock_response(self.session, data=[{'id': 'foo'}, {'id': 'bar'}],
+                      headers={"ETag": '"67890"'})
+        self.client.get_records(collection="bar")
+
+        timestamp = self.client.get_records_timestamp("foo")
+        assert timestamp == '12345'
+
+        timestamp = self.client.get_records_timestamp("bar")
+        assert timestamp == '67890'
+
     def test_pagination_is_followed(self):
         # Mock the calls to request.
         link = ('http://example.org/buckets/buck/collections/coll/records/'