Fix non-terminating auto_paging_iter; release 0.5.2

The reviews feed returns pageInfo.endCursor as null and hasNextPage as true on
every page, including the empty page past the last record. SyncPage trusted
has_more alone and then called the fetcher with a None cursor, which dropped the
`after` query parameter and silently re-requested the first page. As a result
client.reviews.list(...).auto_paging_iter() never terminated: it walked the feed
and then restarted it, re-yielding every record indefinitely.

Two guards, both on SyncPage so every paginated resource is covered rather than
just reviews:

  - next_page() returns None when there is no cursor to page from.
  - auto_paging_iter() stops on a page that comes back with no records.

Also expose the feed's totalCount as page.total on reviews.list, matching what
locations.list already did.

Set pythonpath = ["src"] for pytest. An installed build of the package was
shadowing src/, so the suite was exercising code that is not in this checkout
and reported nine failures because of it. Against the working tree the suite is
green: 77 passing.

Author: Anirudha2604

README.md

@@ -102,13 +102,19 @@ page = client.locations.list(first=50)
 for loc in page:
     print(loc.name)
 
+print(page.total)                      # total records matching the query
+
 if page.has_more:                      # manual paging
     next_page = page.next_page()
 
 for loc in page.auto_paging_iter():    # every record, all pages
     print(loc.name)
 ```
 
+`auto_paging_iter()` walks to the end of the result set and stops there, so it is
+safe to use on large histories. `client.reviews.list(...)` exposes `page.total`
+the same way, from the feed's `totalCount`.
+
 Responses are `APIObject`s: dot access (`loc.name`), dict access (`loc["stateIso"]`), and `loc.to_dict()` all work.
 
 ## Locations

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "listingsapi"
-version = "0.5.1"
+version = "0.5.2"
 description = "Python SDK for listingsAPI — listings, reviews, posts, and analytics for local marketing"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -48,3 +48,7 @@ listingsapi = ["py.typed"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# Test the working tree, not whatever version happens to be pip-installed.
+# Without this an installed copy shadows src/ and the suite silently reports
+# failures for code that is not in this checkout.
+pythonpath = ["src"]

src/listingsapi/__init__.py

@@ -23,7 +23,7 @@
     ValidationError,
 )
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 
 __all__ = [
     # Client

src/listingsapi/_types.py

@@ -117,8 +117,14 @@ def __repr__(self) -> str:
         return f"SyncPage(items={len(self.data)}, has_more={self.has_more})"
 
     def next_page(self) -> SyncPage | None:
-        """Fetch the next page of results, or None if no more pages."""
-        if not self.has_more or not self._fetch_next:
+        """Fetch the next page of results, or None if there is no next page.
+
+        Returns None when there is no cursor to page from, not just when
+        has_more is False. Without a cursor the fetcher would omit `after`
+        entirely and the API would answer with the *first* page again, so
+        paging would silently restart instead of ending.
+        """
+        if not self.has_more or not self._fetch_next or self._end_cursor is None:
             return None
         return self._fetch_next(self._end_cursor)
 
@@ -132,6 +138,9 @@ def auto_paging_iter(self) -> Generator[APIObject, None, None]:
         page: SyncPage | None = self
         while page is not None:
             yield from page.data
-            if not page.has_more:
+            # An empty page means the feed is exhausted. Treat that as
+            # authoritative: some endpoints keep reporting has_more=True
+            # past the final record, so has_more alone cannot terminate.
+            if not page.data or not page.has_more:
                 break
             page = page.next_page()

src/listingsapi/resources/reviews.py

@@ -118,6 +118,7 @@ def list(
             data=items,
             has_more=page_info.get("hasNextPage", False),
             end_cursor=end_cursor,
+            total=result.get("totalCount"),
             _fetch_next=lambda cursor: self.list(
                 location_id,
                 first=first,

tests/test_listingsapi.py

@@ -198,6 +198,68 @@ def test_sync_page_auto_paging_iter():
     assert names == ["a", "b", "c"]
 
 
+def test_sync_page_next_page_none_when_cursor_missing():
+    """Without a cursor, `after` would be omitted and the API would return the
+    first page again, so paging must stop rather than silently restart."""
+    page = SyncPage(
+        data=[{"name": "a"}],
+        has_more=True,
+        end_cursor=None,
+        _fetch_next=lambda cursor: pytest.fail("must not refetch without a cursor"),
+    )
+    assert page.next_page() is None
+
+
+def test_sync_page_auto_paging_iter_stops_on_empty_page():
+    """An empty page ends the feed even if the API still claims has_more."""
+    empty = SyncPage(data=[], has_more=True, end_cursor=None)
+    page1 = SyncPage(
+        data=[{"name": "a"}],
+        has_more=True,
+        end_cursor="cursor1",
+        _fetch_next=lambda cursor: empty,
+    )
+    assert [item.name for item in page1.auto_paging_iter()] == ["a"]
+
+
+def test_auto_paging_iter_terminates_when_api_always_reports_has_more(client, monkeypatch):
+    """Regression: the reviews feed returns pageInfo.endCursor=null and
+    hasNextPage=true on every page, including the empty one past the last
+    record. Paging must still finish exactly once over the data."""
+    total = 12
+    page_size = 5
+    calls = []
+
+    def fake_location_get(location_id, path_suffix, params=None):
+        params = params or {}
+        assert len(calls) < 10, "auto_paging_iter did not terminate"
+        after = params.get("after")
+        start = int(after.split(":")[1]) if after else 0
+        rows = range(start + 1, min(start + page_size, total) + 1)
+        calls.append(len(rows))
+        return {
+            "data": {
+                "interactions": {
+                    "edges": [
+                        {"cursor": f"Interaction:{n}", "node": {"interactionId": f"r{n}"}}
+                        for n in rows
+                    ],
+                    "totalCount": total,
+                    # verbatim live shape: no usable cursor, has-next never false
+                    "pageInfo": {"hasNextPage": True, "endCursor": None},
+                }
+            }
+        }
+
+    monkeypatch.setattr(client, "_location_get", fake_location_get)
+
+    ids = [r.interactionId for r in client.reviews.list(1, first=page_size).auto_paging_iter()]
+
+    assert ids == [f"r{n}" for n in range(1, total + 1)]
+    assert len(ids) == len(set(ids)), "no record may be yielded twice"
+    assert calls == [5, 5, 2, 0]
+
+
 # --- Exceptions ---
 
 def test_exception_hierarchy():
@@ -388,7 +450,7 @@ def test_analytics_google(client):
 
 
 def test_version():
-    assert listingsapi.__version__ == "0.5.1"
+    assert listingsapi.__version__ == "0.5.2"
 
 
 # --- locations.add (one-call create with validation) ---