fix: add trust_per_page config option to toggle sequential page walk

fix: add trust_per_page config, update __getitem__ and tests accordingly

fix: add trust_per_page config, update __getitem__ and tests accordingly#

Author: GFlores17

discogs_client/client.py

@@ -19,6 +19,7 @@ def __init__(self, user_agent, consumer_key=None, consumer_secret=None, token=No
         self.user_agent = user_agent
         self.verbose = False
         self._fetcher = RequestsFetcher()
+        self._trust_per_page = True  # Default: True
 
         if consumer_key and consumer_secret:
             self.set_consumer_key(consumer_key, consumer_secret)
@@ -219,3 +220,13 @@ def set_timeout(self,
         """
         self._fetcher.connect_timeout = connect
         self._fetcher.read_timeout = read
+
+    @property
+    def trust_per_page(self) -> bool:
+        return self._trust_per_page
+
+    @trust_per_page.setter
+    def trust_per_page(self, value: bool) -> None:
+        if not isinstance(value, bool):
+            raise ValueError("trust_per_page must be a bool")
+        self._trust_per_page = value

discogs_client/models.py

@@ -354,26 +354,40 @@ def _transform(self, item):
         return item
 
     def __getitem__(self, index):
-    # Rather than trusting per_page metadata for offset math, we walk
-    # through actual page sizes sequentially. This handles cases where
-    # Discogs returns fewer items than per_page claims, which causes
-    # index-out-of-range errors when using the standard calculation:
-    # page_index = index // self.per_page + 1
-    # offset = index % self.per_page
-        current = 0
-        page_index = 1
-        while True:
+        if self.client._trust_per_page:
+            # Directly jump to index using offset math.
+            # Default
+            page_index = index // self.per_page + 1
+            offset = index % self.per_page
+
             try:
                 page = self.page(page_index)
             except HTTPError as e:
                 if e.status_code == 404:
                     raise IndexError(e.msg)
                 else:
                     raise
-            if current + len(page) > index:
-                return page[index - current]
-            current += len(page)
-            page_index += 1
+
+            return page[offset]
+
+        else:
+            # Sequentially walks through each page until index or end of array reached.
+            # Opt-in
+            current = 0
+            page_index = 1
+            while True:
+                try:
+                    page = self.page(page_index)
+                except HTTPError as e:
+                    if e.status_code == 404:
+                        raise IndexError(e.msg)
+                    else:
+                        raise
+                if current + len(page) > index:
+                    return page[index - current]
+                current += len(page)
+                page_index += 1
+
 
     def __len__(self):
         return self.count

discogs_client/tests/test_core.py

@@ -114,6 +114,7 @@ def test_pagination(self):
     def test_pagination_with_short_page(self):
         """Indexing walks actual page sizes when the API under-fills a page."""
         client = Client('ua')
+        client.trust_per_page = False  # opt into sequential walk
         client._base_url = ''
         client._fetcher = MemoryFetcher({
             '/artists/1': (
@@ -143,6 +144,7 @@ def test_pagination_with_short_page(self):
     def test_pagination_with_varying_page_sizes(self):
         """Indexing works correctly with pages of different actual sizes."""
         client = Client('ua')
+        client.trust_per_page = False  # opt into sequential walk
         client._base_url = ''
         client._fetcher = MemoryFetcher({
             '/artists/1': (
@@ -194,6 +196,7 @@ def test_pagination_with_varying_page_sizes(self):
     def test_pagination_with_short_page_sequential_traversal(self):
         """Verify sequential page walking works when all pages are short."""
         client = Client('ua')
+        client.trust_per_page = False  # opt into sequential walk
         client._base_url = ''
         client._fetcher = MemoryFetcher({
             '/artists/1': (
@@ -235,6 +238,7 @@ def test_pagination_with_short_page_sequential_traversal(self):
     def test_pagination_404_exception_chaining(self):
         """Verify that HTTPError 404 is properly chained when index is out of bounds."""
         client = Client('ua')
+        client.trust_per_page = False  # opt into sequential walk
         client._base_url = ''
         client._fetcher = MemoryFetcher({
             '/artists/1': (