Update CHANGELOG for v1.5.1 release and adjust Python version requirement in CONTRIBUTING.md. Refactor error handling in API request processing by introducing a shared _parse_and_raise function to streamline JSON response parsing and error management. Enhance async search functionality with pagination support and update type exports in __init__.py.

Author: alex-omophub

CHANGELOG.md

@@ -117,7 +117,9 @@ 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.4.1...HEAD
+[Unreleased]: https://github.com/omopHub/omophub-python/compare/v1.5.1...HEAD
+[1.5.1]: https://github.com/omopHub/omophub-python/compare/v1.5.0...v1.5.1
+[1.5.0]: https://github.com/omopHub/omophub-python/compare/v1.4.1...v1.5.0
 [1.4.1]: https://github.com/omopHub/omophub-python/compare/v1.4.0...v1.4.1
 [1.4.0]: https://github.com/omopHub/omophub-python/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/omopHub/omophub-python/compare/v1.3.0...v1.3.1

CONTRIBUTING.md

@@ -53,7 +53,7 @@ Feature requests are welcome! Please open an issue with:
 
 ### Prerequisites
 
-- Python 3.9+
+- Python 3.10+
 - pip
 
 ### Installation

src/omophub/_request.py

@@ -17,6 +17,66 @@
 T = TypeVar("T")
 
 
+def _parse_and_raise(
+    content: bytes,
+    status_code: int,
+    headers: Mapping[str, str],
+) -> dict[str, Any]:
+    """Parse JSON response body and raise on HTTP errors.
+
+    Shared by both sync and async request classes to avoid duplicating
+    the JSON-decode, error-extraction, and rate-limit-retry logic.
+
+    Returns:
+        The parsed JSON dict (caller decides whether to unwrap ``data``).
+
+    Raises:
+        OMOPHubError: On invalid JSON from a successful response.
+        APIError / RateLimitError / etc.: On HTTP error status codes.
+    """
+    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
+
+    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")
+
+        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 data  # type: ignore[return-value]
+
+
 class Request(Generic[T]):
     """Handles API request execution and response parsing."""
 
@@ -50,50 +110,8 @@ def _parse_response(
         status_code: int,
         headers: Mapping[str, str],
     ) -> T:
-        """Parse API response and handle errors."""
-        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 successful response data
+        """Parse API response, raise on errors, return the ``data`` field."""
+        data = _parse_and_raise(content, status_code, headers)
         response: APIResponse = data  # type: ignore[assignment]
         return response.get("data", data)
 
@@ -103,55 +121,8 @@ def _parse_response_raw(
         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
+        """Parse API response, raise on errors, return the full dict with ``meta``."""
+        return _parse_and_raise(content, status_code, headers)
 
     def get(
         self,
@@ -238,50 +209,8 @@ def _parse_response(
         status_code: int,
         headers: Mapping[str, str],
     ) -> T:
-        """Parse API response and handle errors."""
-        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 successful response data
+        """Parse API response, raise on errors, return the ``data`` field."""
+        data = _parse_and_raise(content, status_code, headers)
         response: APIResponse = data  # type: ignore[assignment]
         return response.get("data", data)
 
@@ -291,55 +220,8 @@ def _parse_response_raw(
         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
+        """Parse API response, raise on errors, return the full dict with ``meta``."""
+        return _parse_and_raise(content, status_code, headers)
 
     async def get(
         self,

src/omophub/resources/search.py

@@ -4,7 +4,7 @@
 
 from typing import TYPE_CHECKING, Any, Literal, TypedDict
 
-from .._pagination import DEFAULT_PAGE_SIZE, paginate_sync
+from .._pagination import DEFAULT_PAGE_SIZE, paginate_async, paginate_sync
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Iterator
@@ -670,13 +670,14 @@ async def semantic_iter(
         page_size: int = DEFAULT_PAGE_SIZE,
     ) -> AsyncIterator[SemanticSearchResult]:
         """Iterate through all semantic search results with auto-pagination."""
-        page = 1
 
-        while True:
+        async def fetch_page(
+            page: int, size: int
+        ) -> tuple[list[SemanticSearchResult], PaginationMeta | None]:
             params: dict[str, Any] = {
                 "query": query,
                 "page": page,
-                "page_size": page_size,
+                "page_size": size,
             }
             if vocabulary_ids:
                 params["vocabulary_ids"] = ",".join(vocabulary_ids)
@@ -694,18 +695,12 @@ async def semantic_iter(
             )
 
             data = result.get("data", [])
-            results: list[SemanticSearchResult] = (
-                data.get("results", data) if isinstance(data, dict) else data
-            )
-            meta: PaginationMeta | None = result.get("meta", {}).get("pagination")
-
-            for item in results:
-                yield item
-
-            if meta is None or not meta.get("has_next", False):
-                break
+            results = data.get("results", data) if isinstance(data, dict) else data
+            meta = result.get("meta", {}).get("pagination")
+            return results, meta
 
-            page += 1
+        async for item in paginate_async(fetch_page, page_size):
+            yield item
 
     async def bulk_basic(
         self,

src/omophub/types/__init__.py

@@ -107,10 +107,10 @@
     "QueryEnhancement",
     "RecommendedConceptOutput",
     "RelatedConcept",
-    "ResolvedConcept",
     "Relationship",
     "RelationshipSummary",
     "RelationshipType",
+    "ResolvedConcept",
     "ResponseMeta",
     "SearchFacet",
     "SearchFacets",