add support for cursor based pagination

Signed-off-by: Bruno Vieira <[email protected]>

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog],
+and this project adheres to [Semantic Versioning].
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+[Semantic Versioning]: https://semver.org/spec/v2.0.0.html
+
+## [3.1.3] - 2023-09-27
+
+### Added
+- Support for cursor based pagination to `.all()` endpoints.
+- Changelog.

README.md

@@ -119,7 +119,7 @@ chartmogul.DataSource.destroy(config, uuid='ds_5915ee5a-babd-406b-b8ce-d207133fb
 
 ```python
 chartmogul.Customer.create(config, data={})
-chartmogul.Customer.all(config, page=2, per_page=20)
+chartmogul.Customer.all(config, cursor='cursor==', per_page=20)
 chartmogul.Customer.retrieve(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb')
 chartmogul.Customer.search(config, email='[email protected]')
 chartmogul.Customer.merge(config, data={
@@ -217,7 +217,7 @@ chartmogul.Plan.retrieve(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb'
 chartmogul.Plan.modify(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={
     'name': 'new name'
 })
-chartmogul.Plan.all(config, page=2, external_id='')
+chartmogul.Plan.all(config, cursor='cursor==', external_id='')
 chartmogul.Plan.destroy(config, uuid='')
 ```
 
@@ -227,7 +227,7 @@ chartmogul.Plan.destroy(config, uuid='')
 chartmogul.PlanGroup.create(config, data={})
 chartmogul.PlanGroup.retrieve(config, uuid='plg_5915ee5a-babd-406b-b8ce-d207133fb4cb')
 chartmogul.PlanGroup.modify(config, uuid='plg_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={})
-chartmogul.PlanGroup.all(config, page=2)
+chartmogul.PlanGroup.all(config, cursor='cursor==')
 chartmogul.PlanGroup.all(config, uuid='plg_5915ee5a-babd-406b-b8ce-d207133fb4cb')
 chartmogul.PlanGroup.destroy(config, uuid='')
 ```
@@ -238,7 +238,7 @@ chartmogul.PlanGroup.destroy(config, uuid='')
 import chartmogul
 
 chartmogul.Invoice.create(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={})
-chartmogul.Invoice.all(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', page=2, per_page=10)
+chartmogul.Invoice.all(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', cursor='cursor==', per_page=10)
 chartmogul.Invoice.all(config, customer_uuid='cus_f466e33d-ff2b-4a11-8f85-417eb02157a7', external_id='INV0001')
 chartmogul.Invoice.retrieve(config, uuid='inv_22910fc6-c931-48e7-ac12-90d2cb5f0059')
 ```

chartmogul/api/activity.py

@@ -5,11 +5,13 @@
 
 class Activity(Resource):
     """
-    https://dev.chartmogul.com/v1.0/reference#list-customer-subscriptions
+    https://dev.chartmogul.com/reference/list-activities
     """
-    _path = "/activities"
+    _path = '/activities'
     _root_key = 'entries'
-    _many = namedtuple('Activities', [_root_key, "has_more", "per_page"])
+    _many = namedtuple('Activities',
+                       [_root_key, 'has_more', 'per_page', 'cursor'],
+                       defaults=[None, None, None])
 
     class _Schema(Schema):
         activity_arr = fields.Number(data_key='activity-arr')

chartmogul/api/contact.py

@@ -9,8 +9,7 @@ class Contact(Resource):
     """
     _path = "/contacts{/uuid}"
     _root_key = "entries"
-    _many = namedtuple("Contacts",
-                       [_root_key, "has_more", "cursor"])
+    _many = namedtuple("Contacts", [_root_key, "has_more", "cursor"])
 
     class _Schema(Schema):
         uuid = fields.String()

chartmogul/api/customer.py

@@ -32,7 +32,9 @@ class Customer(Resource):
     _path = "/customers{/uuid}"
     _root_key = 'entries'
     _many = namedtuple('Customers',
-                       [_root_key, "has_more", "per_page", "page", "current_page", "total_pages"])
+        [_root_key, "has_more", "per_page", "page",
+        "current_page", "total_pages", "cursor"],
+        defaults=[None, None, None, None, None, None])
 
     class _Schema(Schema):
         # All operations

chartmogul/api/customers/activity.py

@@ -7,9 +7,11 @@ class CustomerActivity(Resource):
     """
     https://dev.chartmogul.com/v1.0/reference#list-customer-subscriptions
     """
-    _path = "/customers{/uuid}/activities"
+    _path = '/customers{/uuid}/activities'
     _root_key = 'entries'
-    _many = namedtuple('Activities', [_root_key, "has_more", "per_page", "page"])
+    _many = namedtuple('Activities',
+                       [_root_key, 'has_more', 'per_page', 'page', 'cursor'],
+                       defaults=[None, None, None, None])
 
     class _Schema(Schema):
         id = fields.Int()

chartmogul/api/customers/subscription.py

@@ -8,9 +8,11 @@ class CustomerSubscription(Resource):
     https://dev.chartmogul.com/v1.0/reference#list-customer-subscriptions
     https://dev.chartmogul.com/v1.0/reference#list-a-customers-subscriptions
     """
-    _path = "/customers{/uuid}/subscriptions"
+    _path = '/customers{/uuid}/subscriptions'
     _root_key = 'entries'
-    _many = namedtuple('Subscriptions', [_root_key, "has_more", "per_page", "page"])
+    _many = namedtuple('Subscriptions',
+                       [_root_key, 'has_more', 'per_page', 'page', 'cursor'],
+                       defaults=[None, None, None, None])
 
     class _Schema(Schema):
         id = fields.Int(allow_none=True)
@@ -45,11 +47,16 @@ def make(self, data, **kwargs):
     @classmethod
     def _loadJSON(cls, jsonObj):
         if "subscriptions" in jsonObj:
-            _many = namedtuple('Subscriptions', ["subscriptions", "current_page", "total_pages", "customer_uuid"])
-            return _many(cls._schema.load(jsonObj["subscriptions"], many=True),
-                         jsonObj["current_page"],
-                         jsonObj["total_pages"],
-                         jsonObj["customer_uuid"])
+            _many = namedtuple(
+                'Subscriptions',
+                ["subscriptions", "current_page", "total_pages", "customer_uuid", "has_more", "cursor"]
+            )
+            return _many(cls._schema.load(jsonObj['subscriptions'], many=True),
+                         current_page=jsonObj.get('current_page', None),
+                         total_pages=jsonObj.get('total_pages', None),
+                         customer_uuid=jsonObj.get('customer_uuid', None),
+                         has_more=jsonObj.get('has_more', None),
+                         cursor=jsonObj.get('cursor', None))
         else:
             return super(CustomerSubscription, cls)._loadJSON(jsonObj)
 

chartmogul/api/invoice.py

@@ -40,7 +40,9 @@ class Invoice(Resource):
     """
     _path = "/import/customers{/uuid}/invoices"
     _root_key = 'invoices'
-    _many = namedtuple('Invoices', [_root_key, "current_page", "total_pages", "customer_uuid"])
+    _many = namedtuple('Invoices',
+        [_root_key, "current_page", "total_pages", "cursor", "has_more", "customer_uuid"],
+        defaults=[None, None, None, None, None])
     _many.__new__.__defaults__ = (None,) * len(_many._fields)
 
     class _Schema(Schema):

chartmogul/api/plan.py

@@ -7,9 +7,12 @@ class Plan(Resource):
     """
     https://dev.chartmogul.com/v1.0/reference#plans
     """
-    _path = "/plans{/uuid}"
+    _path = '/plans{/uuid}'
     _root_key = 'plans'
-    _many = namedtuple('Plans', [_root_key, "current_page", "total_pages"])
+    _many = namedtuple(
+        'Plans',
+        [_root_key, 'current_page', 'total_pages', 'has_more', 'cursor'],
+        defaults=[None, None, None, None])
 
     class _Schema(Schema):
         uuid = fields.String()

chartmogul/api/plan_group.py

@@ -8,9 +8,11 @@ class PlanGroup(Resource):
     """
     https://dev.chartmogul.com/v1.0/reference#plan_groups
     """
-    _path = "/plan_groups{/uuid}"
+    _path = '/plan_groups{/uuid}'
     _root_key = 'plan_groups'
-    _many = namedtuple('PlanGroups', [_root_key, "current_page", "total_pages"])
+    _many = namedtuple('PlanGroups',
+        [_root_key, 'current_page', 'total_pages', 'has_more', 'cursor'],
+        defaults=[None, None, None, None])
 
     class _Schema(Schema):
         uuid = fields.String()

chartmogul/api/plan_group_plans.py

@@ -7,9 +7,11 @@ class PlanGroupPlans(Resource):
     """
     https://dev.chartmogul.com/v1.0/reference#plan_groups
     """
-    _path = "/plan_groups{/uuid}/plans"
+    _path = '/plan_groups{/uuid}/plans'
     _root_key = 'plans'
-    _many = namedtuple('PlanGroupPlans', [_root_key, "current_page", "total_pages"])
+    _many = namedtuple('PlanGroupPlans',
+        [_root_key, 'current_page', 'total_pages', 'has_more', 'cursor'],
+        defaults=[None, None, None, None])
 
     class _Schema(Schema):
         uuid = fields.String()

chartmogul/api/subscription_event.py

@@ -7,9 +7,11 @@ class SubscriptionEvent(Resource):
     """
     https://dev.chartmogul.com/reference/subscription-events
     """
-    _path = "/subscription_events"
+    _path = '/subscription_events'
     _root_key = 'subscription_events'
-    _many = namedtuple('SubscriptionEvents', [_root_key, 'meta'])
+    _many = namedtuple('SubscriptionEvents',
+                       [_root_key, 'meta', 'has_more', 'cursor'],
+                       defaults=[None, None, None])
 
     class _Schema(Schema):
         id = fields.Int(required=True)

chartmogul/version.py

@@ -1 +1 @@
-__version__ = '3.1.2'
+__version__ = '3.1.3'

test/api/test_activity.py

@@ -36,14 +36,17 @@ def test_all(self, mock_requests):
                             "uuid": "f1a49735-21c7-4e3f-9ddc-67927aaadcf4"
                         },
                     ],
-                    "has_more":False,
-                    "per_page":200,
+                    "has_more": False,
+                    "per_page": 200,
+                    "cursor": "cursor=="
                 }
         )
         config = Config("token")  # is actually checked in mock
         result = Activity.all(config).get()
 
-        self.assertEqual(mock_requests.call_count, 1, "expected call")
+        self.assertEqual(mock_requests.call_count, 1, 'expected call')
         self.assertEqual(mock_requests.last_request.qs, {})
         self.assertEqual(result.__class__.__name__, Activity._many.__name__)
         self.assertEqual(result.entries[0].uuid, 'f1a49735-21c7-4e3f-9ddc-67927aaadcf4')
+        self.assertFalse(result.has_more)
+        self.assertEqual(result.cursor, 'cursor==')

test/api/test_contact.py

@@ -45,7 +45,7 @@
 
 allContacts = {
     "entries": [contact],
-    "cursor": "MjAyMy0wMy0xMFQwMzo1MzoxNS44MTg1MjUwMDArMDA6MDAmY29uXzE2NDcwZjk4LWJlZjctMTFlZC05MjA4LTdiMDhhNDBmMzA0OQ==",
+    "cursor": "cursor==",
     "has_more": False
 }
 
@@ -77,6 +77,8 @@ def test_all(self, mock_requests):
         self.assertEqual(mock_requests.last_request.text, None)
         self.assertEqual(dir(contacts), dir(expected))
         self.assertTrue(isinstance(contacts.entries[0], Contact))
+        self.assertFalse(contacts.has_more)
+        self.assertEqual(contacts.cursor, "cursor==")
 
     @requests_mock.mock()
     def test_create(self, mock_requests):