Prepare release v1.3.1

alex-omophub · alex-omophub · commit 0a64db988ee6 · 2026-01-24T22:12:35.000Z
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] - 2026-01-24
+
+### Fixed
+
+- Fixed `search.basic_iter()` pagination bug that caused only the first page of results to be returned. The iterator now correctly fetches all pages when iterating through search results.
+
+### Changed
+
+- Added `get_raw()` method to internal request classes for retrieving full API responses with pagination metadata.
+- Expanded `search.basic_iter()` method signature to explicitly list all filter parameters instead of using `**kwargs`.
+
 ## [1.3.0] - 2026-01-06
 
 ### Changes
@@ -72,7 +83,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Full type hints and PEP 561 compliance
 - HTTP/2 support via httpx
 
-[Unreleased]: https://github.com/omopHub/omophub-python/compare/v1.3.0...HEAD
+[Unreleased]: https://github.com/omopHub/omophub-python/compare/v1.3.1...HEAD
+[1.3.1]: https://github.com/omopHub/omophub-python/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/omopHub/omophub-python/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/omopHub/omophub-python/compare/v0.1.0...v1.2.0
 [0.1.0]: https://github.com/omopHub/omophub-python/releases/tag/v0.1.0
diff --git a/src/omophub/_request.py b/src/omophub/_request.py
@@ -97,6 +97,62 @@ def _parse_response(
         response: APIResponse = data  # type: ignore[assignment]
         return response.get("data", data)
 
+    def _parse_response_raw(
+        self,
+        content: bytes,
+        status_code: int,
+        headers: Mapping[str, str],
+    ) -> dict[str, Any]:
+        """Parse API response and return full response dict with meta.
+
+        Unlike _parse_response which extracts just the 'data' field,
+        this method returns the complete response including 'meta' for pagination.
+        """
+        request_id = headers.get("X-Request-Id") or headers.get("x-request-id")
+
+        try:
+            data = json.loads(content) if content else {}
+        except json.JSONDecodeError as exc:
+            if status_code >= 400:
+                raise_for_status(
+                    status_code,
+                    f"Request failed with status {status_code}",
+                    request_id=request_id,
+                )
+            raise OMOPHubError(
+                f"Invalid JSON response: {content[:200].decode(errors='replace')}"
+            ) from exc
+
+        # Handle error responses
+        if status_code >= 400:
+            error_response: ErrorResponse = data  # type: ignore[assignment]
+            error = error_response.get("error", {})
+            message = error.get("message", f"Request failed with status {status_code}")
+            error_code = error.get("code")
+            details = error.get("details")
+
+            # Check for rate limit retry-after
+            retry_after = None
+            if status_code == 429:
+                retry_after_header = headers.get("Retry-After") or headers.get(
+                    "retry-after"
+                )
+                if retry_after_header:
+                    with contextlib.suppress(ValueError):
+                        retry_after = int(retry_after_header)
+
+            raise_for_status(
+                status_code,
+                message,
+                request_id=request_id,
+                error_code=error_code,
+                details=details,
+                retry_after=retry_after,
+            )
+
+        # Return full response dict (includes 'data' and 'meta')
+        return data
+
     def get(
         self,
         path: str,
@@ -112,6 +168,25 @@ def get(
         )
         return self._parse_response(content, status_code, headers)
 
+    def get_raw(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make a GET request and return full response with meta.
+
+        Unlike get() which extracts just the 'data' field,
+        this method returns the complete response including 'meta' for pagination.
+        """
+        url = self._build_url(path)
+        content, status_code, headers = self._http_client.request(
+            "GET",
+            url,
+            headers=self._get_auth_headers(),
+            params=params,
+        )
+        return self._parse_response_raw(content, status_code, headers)
+
     def post(
         self,
         path: str,
@@ -210,6 +285,62 @@ def _parse_response(
         response: APIResponse = data  # type: ignore[assignment]
         return response.get("data", data)
 
+    def _parse_response_raw(
+        self,
+        content: bytes,
+        status_code: int,
+        headers: Mapping[str, str],
+    ) -> dict[str, Any]:
+        """Parse API response and return full response dict with meta.
+
+        Unlike _parse_response which extracts just the 'data' field,
+        this method returns the complete response including 'meta' for pagination.
+        """
+        request_id = headers.get("X-Request-Id") or headers.get("x-request-id")
+
+        try:
+            data = json.loads(content) if content else {}
+        except json.JSONDecodeError as exc:
+            if status_code >= 400:
+                raise_for_status(
+                    status_code,
+                    f"Request failed with status {status_code}",
+                    request_id=request_id,
+                )
+            raise OMOPHubError(
+                f"Invalid JSON response: {content[:200].decode(errors='replace')}"
+            ) from exc
+
+        # Handle error responses
+        if status_code >= 400:
+            error_response: ErrorResponse = data  # type: ignore[assignment]
+            error = error_response.get("error", {})
+            message = error.get("message", f"Request failed with status {status_code}")
+            error_code = error.get("code")
+            details = error.get("details")
+
+            # Check for rate limit retry-after
+            retry_after = None
+            if status_code == 429:
+                retry_after_header = headers.get("Retry-After") or headers.get(
+                    "retry-after"
+                )
+                if retry_after_header:
+                    with contextlib.suppress(ValueError):
+                        retry_after = int(retry_after_header)
+
+            raise_for_status(
+                status_code,
+                message,
+                request_id=request_id,
+                error_code=error_code,
+                details=details,
+                retry_after=retry_after,
+            )
+
+        # Return full response dict (includes 'data' and 'meta')
+        return data
+
     async def get(
         self,
         path: str,
@@ -225,6 +356,25 @@ async def get(
         )
         return self._parse_response(content, status_code, headers)
 
+    async def get_raw(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make an async GET request and return full response with meta.
+
+        Unlike get() which extracts just the 'data' field,
+        this method returns the complete response including 'meta' for pagination.
+        """
+        url = self._build_url(path)
+        content, status_code, headers = await self._http_client.request(
+            "GET",
+            url,
+            headers=self._get_auth_headers(),
+            params=params,
+        )
+        return self._parse_response_raw(content, status_code, headers)
+
     async def post(
         self,
         path: str,
diff --git a/src/omophub/resources/search.py b/src/omophub/resources/search.py
@@ -125,17 +125,31 @@ def basic_iter(
         *,
         vocabulary_ids: list[str] | None = None,
         domain_ids: list[str] | None = None,
+        concept_class_ids: list[str] | None = None,
+        standard_concept: str | None = None,
+        include_synonyms: bool = False,
+        include_invalid: bool = False,
+        min_score: float | None = None,
+        exact_match: bool = False,
         page_size: int = DEFAULT_PAGE_SIZE,
-        **kwargs: Any,
+        sort_by: str | None = None,
+        sort_order: str | None = None,
     ) -> Iterator[Concept]:
         """Iterate through all search results with auto-pagination.
 
         Args:
             query: Search query string
             vocabulary_ids: Filter by vocabulary IDs
             domain_ids: Filter by domain IDs
+            concept_class_ids: Filter by concept class IDs
+            standard_concept: Filter by standard concept ("S", "C", or None)
+            include_synonyms: Search in synonyms
+            include_invalid: Include invalid concepts
+            min_score: Minimum relevance score
+            exact_match: Require exact match
             page_size: Results per page
-            **kwargs: Additional search parameters
+            sort_by: Sort field
+            sort_order: Sort order ("asc" or "desc")
 
         Yields:
             Individual concepts from all pages
@@ -144,22 +158,40 @@ def basic_iter(
         def fetch_page(
             page: int, size: int
         ) -> tuple[list[Concept], PaginationMeta | None]:
-            result = self.basic(
-                query,
-                vocabulary_ids=vocabulary_ids,
-                domain_ids=domain_ids,
-                page=page,
-                page_size=size,
-                **kwargs,
-            )
-            concepts = (
-                result.get("concepts", result) if isinstance(result, dict) else result
-            )
-            meta = (
-                result.get("meta", {}).get("pagination")
-                if isinstance(result, dict)
-                else None
-            )
+            # Build params manually to use get_raw() for full response with meta
+            params: dict[str, Any] = {
+                "query": query,
+                "page": page,
+                "page_size": size,
+            }
+            if vocabulary_ids:
+                params["vocabulary_ids"] = ",".join(vocabulary_ids)
+            if domain_ids:
+                params["domain_ids"] = ",".join(domain_ids)
+            if concept_class_ids:
+                params["concept_class_ids"] = ",".join(concept_class_ids)
+            if standard_concept:
+                params["standard_concept"] = standard_concept
+            if include_synonyms:
+                params["include_synonyms"] = "true"
+            if include_invalid:
+                params["include_invalid"] = "true"
+            if min_score is not None:
+                params["min_score"] = min_score
+            if exact_match:
+                params["exact_match"] = "true"
+            if sort_by:
+                params["sort_by"] = sort_by
+            if sort_order:
+                params["sort_order"] = sort_order
+
+            # Use get_raw() to preserve pagination metadata
+            result = self._request.get_raw("/search/concepts", params=params)
+
+            # Extract concepts from 'data' field (may be list or dict with 'concepts')
+            data = result.get("data", [])
+            concepts = data.get("concepts", data) if isinstance(data, dict) else data
+            meta = result.get("meta", {}).get("pagination")
             return concepts, meta
 
         yield from paginate_sync(fetch_page, page_size)
diff --git a/tests/integration/test_search.py b/tests/integration/test_search.py
@@ -131,18 +131,32 @@ def test_autocomplete_with_filters(self, integration_client: OMOPHub) -> None:
         assert isinstance(suggestions, list)
 
     def test_basic_iter_pagination(self, integration_client: OMOPHub) -> None:
-        """Test auto-pagination with basic_iter."""
-        # Collect first 5 concepts using iterator
+        """Test auto-pagination with basic_iter.
+
+        This test verifies that basic_iter correctly fetches multiple pages
+        of results. With page_size=2, we should be able to collect 5 concepts
+        which requires fetching at least 3 pages, proving pagination works.
+        """
+        # Collect concepts using iterator with small page size
         concepts = []
+        page_size = 2
+        max_concepts = 5
+
         for concept in integration_client.search.basic_iter(
             "diabetes",
-            page_size=2,  # Small page size to test pagination
+            page_size=page_size,  # Small page size to test pagination
         ):
             concepts.append(concept)
-            if len(concepts) >= 5:
+            if len(concepts) >= max_concepts:
                 break
 
-        assert len(concepts) == 5
+        # Should get requested number of concepts (proves pagination worked)
+        assert len(concepts) == max_concepts, (
+            f"Expected {max_concepts} concepts from paginated iterator, "
+            f"got {len(concepts)}. With page_size={page_size}, getting only "
+            f"{len(concepts)} concepts suggests pagination is broken."
+        )
+
         # All should have concept_id
         for concept in concepts:
             assert "concept_id" in concept
diff --git a/tests/unit/resources/test_search.py b/tests/unit/resources/test_search.py
@@ -77,15 +77,14 @@ def test_basic_search_with_filters(
     @respx.mock
     def test_basic_iter_single_page(self, sync_client: OMOPHub, base_url: str) -> None:
         """Test basic_iter with single page of results."""
+        # Note: meta is at top level, not nested inside data
         search_response = {
             "success": True,
-            "data": {
-                "concepts": [
-                    {"concept_id": 201826, "concept_name": "Type 2 diabetes mellitus"},
-                    {"concept_id": 201820, "concept_name": "Diabetes mellitus"},
-                ],
-                "meta": {"pagination": {"page": 1, "has_next": False}},
-            },
+            "data": [
+                {"concept_id": 201826, "concept_name": "Type 2 diabetes mellitus"},
+                {"concept_id": 201820, "concept_name": "Diabetes mellitus"},
+            ],
+            "meta": {"pagination": {"page": 1, "has_next": False}},
         }
         respx.get(f"{base_url}/search/concepts").mock(
             return_value=Response(200, json=search_response)
@@ -99,19 +98,16 @@ def test_basic_iter_multiple_pages(
         self, sync_client: OMOPHub, base_url: str
     ) -> None:
         """Test basic_iter auto-pagination across multiple pages."""
+        # Note: meta is at top level, not nested inside data
         page1_response = {
             "success": True,
-            "data": {
-                "concepts": [{"concept_id": 1}],
-                "meta": {"pagination": {"page": 1, "has_next": True}},
-            },
+            "data": [{"concept_id": 1}],
+            "meta": {"pagination": {"page": 1, "has_next": True}},
         }
         page2_response = {
             "success": True,
-            "data": {
-                "concepts": [{"concept_id": 2}],
-                "meta": {"pagination": {"page": 2, "has_next": False}},
-            },
+            "data": [{"concept_id": 2}],
+            "meta": {"pagination": {"page": 2, "has_next": False}},
         }
 
         call_count = 0
