devrev-Python-SDK 3.0.0__tar.gz → 3.0.1__tar.gz

{devrev_python_sdk-3.0.0 → devrev_python_sdk-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devrev-Python-SDK
-Version: 3.0.0
+Version: 3.0.1
 Summary: A modern, type-safe Python SDK for the DevRev API
 Project-URL: Homepage, https://github.com/mgmonteleone/py-dev-rev
 Project-URL: Documentation, https://github.com/mgmonteleone/py-dev-rev

{devrev_python_sdk-3.0.0 → devrev_python_sdk-3.0.1}/docs/changelog.md

@@ -13,6 +13,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+## [3.0.1] - 2026-04-22
+
+### Changed
+
+- **Shared pagination helper** (CUSS-457) — Extracted the per-request page-size
+  clamp (`_MAX_PAGE = 100`) and the `resolve_page_limit` helper from
+  `conversations.py` and `works.py` into a single shared module
+  `src/devrev/services/_pagination.py`. Non-breaking internal refactor; no
+  public SDK or MCP surface change. The shared helper adopts the tighter of
+  the two pre-existing semantics, eliminating a small over-fetch on the
+  final page of paginated `list_*_since` calls in `WorksService`.
+
 ## [3.0.0] - 2026-04-22
 
 ### Added

{devrev_python_sdk-3.0.0 → devrev_python_sdk-3.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "devrev-Python-SDK"
-version = "3.0.0"
+version = "3.0.1"
 description = "A modern, type-safe Python SDK for the DevRev API"
 readme = "README.md"
 requires-python = ">=3.11"

devrev_python_sdk-3.0.1/src/devrev/services/_pagination.py

@@ -0,0 +1,54 @@
+"""Shared pagination helpers for cursor-streaming list helpers.
+
+The DevRev ``*.list`` endpoints cap per-page responses at 100 items and the
+corresponding ``*ListRequest.limit`` fields are pydantic-constrained to
+``le=100``. Any service that drives cursor pagination from a user-supplied
+``overall_limit`` / ``page_size`` pair must therefore clamp the value it puts
+on the request body before construction, or the request will fail validation
+locally before it is ever sent.
+
+:func:`resolve_page_limit` centralises that clamping so every ``list_*_since``
+helper resolves the per-page ``limit`` identically.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+_MAX_PAGE: Final[int] = 100
+
+
+def resolve_page_limit(
+    overall_limit: int | None,
+    collected: int,
+    page_size: int | None,
+) -> int | None:
+    """Compute the ``limit`` to send for the next page request.
+
+    The returned value is always clamped to :data:`_MAX_PAGE` so callers using
+    an ``overall_limit`` greater than the server maximum (e.g. ``limit=200,
+    page_size=None``) still paginate correctly. When both ``overall_limit`` and
+    ``page_size`` are supplied the tightest of ``{page_size, remaining,
+    _MAX_PAGE}`` wins.
+
+    Args:
+        overall_limit: Caller-supplied hard cap on total items to return across
+            all pages, or ``None`` to stream until the server runs out of
+            results.
+        collected: Number of items already accumulated across prior pages.
+        page_size: Caller-supplied per-page size, or ``None`` to defer to the
+            server default (still clamped to :data:`_MAX_PAGE`).
+
+    Returns:
+        The ``limit`` to put on the next ``*ListRequest``, or ``None`` to omit
+        it entirely (only when both ``overall_limit`` and ``page_size`` are
+        ``None``).
+    """
+    if overall_limit is None:
+        if page_size is None:
+            return None
+        return min(page_size, _MAX_PAGE)
+    remaining = overall_limit - collected
+    if page_size is None:
+        return min(remaining, _MAX_PAGE)
+    return min(page_size, remaining, _MAX_PAGE)

{devrev_python_sdk-3.0.0 → devrev_python_sdk-3.0.1}/src/devrev/services/conversations.py

@@ -23,6 +23,7 @@ from devrev.models.conversations import (
     ConversationsUpdateRequest,
     ConversationsUpdateResponse,
 )
+from devrev.services._pagination import resolve_page_limit
 from devrev.services.base import AsyncBaseService, BaseService
 
 
@@ -47,33 +48,6 @@ def _normalize_sort_by(sort_by: Sequence[str] | None) -> list[str] | None:
     return normalized
 
 
-# ``ConversationsListRequest.limit`` is pydantic-constrained to ``le=100``;
-# clamp any computed per-page limit so pagination loops do not construct a
-# request body that fails validation before it is ever sent.
-_CONVERSATIONS_MAX_PAGE = 100
-
-
-def _resolve_page_limit(
-    overall_limit: int | None,
-    collected: int,
-    page_size: int | None,
-) -> int | None:
-    """Compute the ``limit`` to send for the next page request.
-
-    The returned value is always clamped to ``_CONVERSATIONS_MAX_PAGE`` so
-    callers using an ``overall_limit`` greater than the server maximum (e.g.
-    ``limit=200, page_size=None``) still paginate correctly.
-    """
-    if overall_limit is None:
-        if page_size is None:
-            return None
-        return min(page_size, _CONVERSATIONS_MAX_PAGE)
-    remaining = overall_limit - collected
-    if page_size is None:
-        return min(remaining, _CONVERSATIONS_MAX_PAGE)
-    return min(page_size, remaining, _CONVERSATIONS_MAX_PAGE)
-
-
 def _is_before_cutoff(modified_date: datetime | None, cutoff: datetime) -> bool:
     """Return True if ``modified_date`` is strictly older than ``cutoff``.
 
@@ -135,7 +109,7 @@ class ConversationsService(BaseService):
         while True:
             if limit is not None and len(results) >= limit:
                 break
-            request_limit = _resolve_page_limit(limit, len(results), page_size)
+            request_limit = resolve_page_limit(limit, len(results), page_size)
             request = ConversationsListRequest(
                 cursor=cursor,
                 limit=request_limit,
@@ -267,7 +241,7 @@ class AsyncConversationsService(AsyncBaseService):
         while True:
             if limit is not None and len(results) >= limit:
                 break
-            request_limit = _resolve_page_limit(limit, len(results), page_size)
+            request_limit = resolve_page_limit(limit, len(results), page_size)
             request = ConversationsListRequest(
                 cursor=cursor,
                 limit=request_limit,

{devrev_python_sdk-3.0.0 → devrev_python_sdk-3.0.1}/src/devrev/services/works.py

@@ -31,6 +31,7 @@ from devrev.models.works import (
     WorksUpdateResponse,
     WorkType,
 )
+from devrev.services._pagination import resolve_page_limit
 from devrev.services.base import AsyncBaseService, BaseService
 
 if TYPE_CHECKING:
@@ -58,31 +59,6 @@ def _is_before_cutoff(timestamp: datetime | None, cutoff: datetime) -> bool:
         return False
 
 
-# ``WorksListRequest.limit`` is pydantic-constrained to ``le=100``; clamp any
-# computed per-page limit so pagination loops do not construct a request body
-# that fails validation before it is ever sent.
-_WORKS_MAX_PAGE = 100
-
-
-def _resolve_page_limit(
-    overall_limit: int | None,
-    collected: int,
-    page_size: int | None,
-) -> int | None:
-    """Compute the ``limit`` to send for the next page request.
-
-    The returned value is always clamped to ``_WORKS_MAX_PAGE`` so callers using
-    an ``overall_limit`` greater than the server maximum (e.g. ``limit=200,
-    page_size=None``) still paginate correctly.
-    """
-    if page_size is not None:
-        return min(page_size, _WORKS_MAX_PAGE)
-    if overall_limit is None:
-        return None
-    remaining = overall_limit - collected
-    return min(remaining, _WORKS_MAX_PAGE)
-
-
 def _normalize_sort_by(sort_by: Sequence[str] | None) -> _StrList | None:
     """Normalize sort_by entries to the server-expected ``field:direction`` form.
 
@@ -351,7 +327,7 @@ class WorksService(BaseService):
                 owned_by=owned_by,
                 applies_to_part=applies_to_part,
                 cursor=cursor,
-                limit=_resolve_page_limit(limit, len(collected), page_size),
+                limit=resolve_page_limit(limit, len(collected), page_size),
                 sort_by=sort_by,
             )
             stop = False
@@ -577,7 +553,7 @@ class AsyncWorksService(AsyncBaseService):
                 owned_by=owned_by,
                 applies_to_part=applies_to_part,
                 cursor=cursor,
-                limit=_resolve_page_limit(limit, len(collected), page_size),
+                limit=resolve_page_limit(limit, len(collected), page_size),
                 sort_by=sort_by,
             )
             stop = False

devrev_python_sdk-3.0.1/tests/unit/services/test_pagination.py

@@ -0,0 +1,48 @@
+"""Unit tests for the shared pagination helper."""
+
+from __future__ import annotations
+
+import pytest
+
+from devrev.services._pagination import _MAX_PAGE, resolve_page_limit
+
+
+class TestResolvePageLimit:
+    """Tight-clamping semantics for ``resolve_page_limit``."""
+
+    def test_max_page_constant_is_one_hundred(self) -> None:
+        """Server-side cap is exactly 100 items per page."""
+        assert _MAX_PAGE == 100
+
+    @pytest.mark.parametrize(
+        ("overall_limit", "collected", "page_size", "expected"),
+        [
+            # No overall cap, no page size → defer entirely to server.
+            (None, 0, None, None),
+            # No overall cap, small page size → pass through.
+            (None, 0, 50, 50),
+            # No overall cap, page_size above MAX → clamp to MAX.
+            (None, 0, 200, 100),
+            # Overall cap below MAX, no page size → send remaining.
+            (50, 0, None, 50),
+            # Overall cap with some collected, no page size → send remaining.
+            (50, 45, None, 5),
+            # Overall cap above MAX, no page size → clamp to MAX.
+            (500, 0, None, 100),
+            # Tightest of {page_size=10, remaining=5, MAX=100} wins.
+            (50, 45, 10, 5),
+            # Tightest of {page_size=50, remaining=500, MAX=100} wins.
+            (500, 0, 50, 50),
+            # page_size > MAX with large remaining → MAX wins.
+            (500, 0, 200, 100),
+        ],
+    )
+    def test_resolve_page_limit_cases(
+        self,
+        overall_limit: int | None,
+        collected: int,
+        page_size: int | None,
+        expected: int | None,
+    ) -> None:
+        """Exhaustive coverage of the clamping matrix from the ticket."""
+        assert resolve_page_limit(overall_limit, collected, page_size) == expected