MPT-12358 Collection client async

Author: albertsola

mpt_api_client/http/collection.py

@@ -1,6 +1,6 @@
 import copy
 from abc import ABC
-from collections.abc import Iterator
+from collections.abc import AsyncIterator, Iterator
 from typing import Any, Self
 
 import httpx
@@ -226,3 +226,117 @@ def _fetch_page_as_response(self, limit: int = 100, offset: int = 0) -> httpx.Re
         response.raise_for_status()
 
         return response
+
+
+class AsyncCollectionClientBase[
+    ResourceModel: Resource,
+    ResourceClient: ResourceBaseClient[Resource],
+](ABC, CollectionMixin):
+    """Immutable Base client for RESTful resource collections.
+
+    Examples:
+        active_orders_cc = order_collection.filter(RQLQuery(status="active"))
+        active_orders = active_orders_cc.order_by("created").iterate()
+        product_active_orders = active_orders_cc.filter(RQLQuery(product__id="PRD-1")).iterate()
+
+        new_order = order_collection.create(order_data)
+
+    """
+
+    _resource_class: type[ResourceModel]
+    _resource_client_class: type[ResourceClient]
+    _collection_class: type[Collection[ResourceModel]]
+
+    def __init__(
+        self,
+        query_rql: RQLQuery | None = None,
+        http_client: HTTPClientAsync | None = None,
+    ) -> None:
+        self.http_client: HTTPClientAsync = http_client or HTTPClientAsync()  # type: ignore[mutable-override]
+        CollectionMixin.__init__(self, http_client=self.http_client, query_rql=query_rql)
+
+    async def fetch_page(self, limit: int = 100, offset: int = 0) -> Collection[ResourceModel]:
+        """Fetch one page of resources.
+
+        Returns:
+            Collection of resources.
+        """
+        response = await self._fetch_page_as_response(limit=limit, offset=offset)
+        return Collection.from_response(response)
+
+    async def fetch_one(self) -> ResourceModel:
+        """Fetch one page, expect exactly one result.
+
+        Returns:
+            One resource.
+
+        Raises:
+            ValueError: If the total matching records are not exactly one.
+        """
+        response = await self._fetch_page_as_response(limit=1, offset=0)
+        resource_list: Collection[ResourceModel] = Collection.from_response(response)
+        total_records = len(resource_list)
+        if resource_list.meta:
+            total_records = resource_list.meta.pagination.total
+        if total_records == 0:
+            raise ValueError("Expected one result, but got zero results")
+        if total_records > 1:
+            raise ValueError(f"Expected one result, but got {total_records} results")
+
+        return resource_list[0]
+
+    async def iterate(self, batch_size: int = 100) -> AsyncIterator[ResourceModel]:
+        """Iterate over all resources, yielding GenericResource objects.
+
+        Args:
+            batch_size: Number of resources to fetch per request
+
+        Returns:
+            Iterator of resources.
+        """
+        offset = 0
+        limit = batch_size  # Default page size
+
+        while True:
+            response = await self._fetch_page_as_response(limit=limit, offset=offset)
+            items_collection: Collection[ResourceModel] = self._collection_class.from_response(
+                response
+            )
+            for resource in items_collection:
+                yield resource
+
+            if not items_collection.meta:
+                break
+            if not items_collection.meta.pagination.has_next():
+                break
+            offset = items_collection.meta.pagination.next_offset()
+
+    async def get(self, resource_id: str) -> ResourceClient:
+        """Get resource by resource_id."""
+        return self._resource_client_class(http_client=self.http_client, resource_id=resource_id)  # type: ignore[arg-type]
+
+    async def create(self, resource_data: dict[str, Any]) -> ResourceModel:
+        """Create a new resource using `POST /endpoint`.
+
+        Returns:
+            New resource created.
+        """
+        response = await self.http_client.post(self._endpoint, json=resource_data)
+        response.raise_for_status()
+
+        return self._resource_class.from_response(response)
+
+    async def _fetch_page_as_response(self, limit: int = 100, offset: int = 0) -> httpx.Response:
+        """Fetch one page of resources.
+
+        Returns:
+            httpx.Response object.
+
+        Raises:
+            HTTPStatusError: if the response status code is not 200.
+        """
+        pagination_params: dict[str, int] = {"limit": limit, "offset": offset}
+        response = await self.http_client.get(self.build_url(pagination_params))
+        response.raise_for_status()
+
+        return response

tests/http/collection/test_async_collection_client_create.py

@@ -0,0 +1,26 @@
+import json
+
+import httpx
+import pytest
+import respx
+
+
+@pytest.mark.asyncio
+async def test_create_resource(async_collection_client):  # noqa: WPS210
+    resource_data = {"name": "Test Resource", "status": "active"}
+    new_resource_data = {"id": "new-resource-id", "name": "Test Resource", "status": "active"}
+    create_response = httpx.Response(201, json={"data": new_resource_data})
+
+    with respx.mock:
+        mock_route = respx.post("https://api.example.com/api/v1/test").mock(
+            return_value=create_response
+        )
+
+        created_resource = await async_collection_client.create(resource_data)
+
+    assert created_resource.to_dict() == new_resource_data
+    assert mock_route.call_count == 1
+    request = mock_route.calls[0].request
+    assert request.method == "POST"
+    assert request.url == "https://api.example.com/api/v1/test"
+    assert json.loads(request.content.decode()) == resource_data

tests/http/collection/test_async_collection_client_fetch.py

@@ -0,0 +1,146 @@
+import httpx
+import pytest
+import respx
+
+from mpt_api_client.rql import RQLQuery
+
+
+@pytest.fixture
+def list_response():
+    return httpx.Response(httpx.codes.OK, json={"data": [{"id": "ID-1"}]})
+
+
+@pytest.fixture
+def single_result_response():
+    return httpx.Response(
+        httpx.codes.OK,
+        json={
+            "data": [{"id": "ID-1", "name": "Test Resource"}],
+            "$meta": {"pagination": {"total": 1, "offset": 0, "limit": 1}},
+        },
+    )
+
+
+@pytest.fixture
+def no_results_response():
+    return httpx.Response(
+        httpx.codes.OK,
+        json={"data": [], "$meta": {"pagination": {"total": 0, "offset": 0, "limit": 1}}},
+    )
+
+
+@pytest.fixture
+def multiple_results_response():
+    return httpx.Response(
+        200,
+        json={
+            "data": [{"id": "ID-1", "name": "Resource 1"}, {"id": "ID-2", "name": "Resource 2"}],
+            "$meta": {"pagination": {"total": 2, "offset": 0, "limit": 1}},
+        },
+    )
+
+
+@pytest.fixture
+def no_meta_response():
+    return httpx.Response(httpx.codes.OK, json={"data": [{"id": "ID-1"}]})
+
+
+@pytest.fixture
+def filter_status_active():
+    return RQLQuery(status="active")
+
+
+@pytest.mark.asyncio
+async def test_fetch_one_success(async_collection_client, single_result_response):
+    with respx.mock:
+        mock_route = respx.get("https://api.example.com/api/v1/test").mock(
+            return_value=single_result_response
+        )
+
+        resource = await async_collection_client.fetch_one()
+
+    assert resource.id == "ID-1"
+    assert resource.name == "Test Resource"
+    assert mock_route.called
+
+    first_request = mock_route.calls[0].request
+    assert "limit=1" in str(first_request.url)
+    assert "offset=0" in str(first_request.url)
+
+
+@pytest.mark.asyncio
+async def test_fetch_one_no_results(async_collection_client, no_results_response):
+    with respx.mock:
+        respx.get("https://api.example.com/api/v1/test").mock(return_value=no_results_response)
+
+        with pytest.raises(ValueError, match="Expected one result, but got zero results"):
+            await async_collection_client.fetch_one()
+
+
+@pytest.mark.asyncio
+async def test_fetch_one_multiple_results(async_collection_client, multiple_results_response):
+    with respx.mock:
+        respx.get("https://api.example.com/api/v1/test").mock(
+            return_value=multiple_results_response
+        )
+
+        with pytest.raises(ValueError, match=r"Expected one result, but got 2 results"):
+            await async_collection_client.fetch_one()
+
+
+@pytest.mark.asyncio
+async def test_fetch_one_with_filters(
+    async_collection_client, single_result_response, filter_status_active
+):
+    filtered_collection = (
+        async_collection_client.filter(filter_status_active)
+        .select("id", "name")
+        .order_by("created")
+    )
+
+    with respx.mock:
+        mock_route = respx.get("https://api.example.com/api/v1/test").mock(
+            return_value=single_result_response
+        )
+        resource = await filtered_collection.fetch_one()
+
+    assert resource.id == "ID-1"
+    assert mock_route.called
+
+    first_request = mock_route.calls[0].request
+    assert first_request.method == "GET"
+    assert first_request.url == (
+        "https://api.example.com/api/v1/test"
+        "?limit=1&offset=0&order=created"
+        "&select=id,name&eq(status,active)"
+    )
+
+
+@pytest.mark.asyncio
+async def test_fetch_page_with_filter(
+    async_collection_client, list_response, filter_status_active
+) -> None:
+    custom_collection = (
+        async_collection_client.filter(filter_status_active)
+        .select("-audit", "product.agreements", "-product.agreements.product")
+        .order_by("-created", "name")
+    )
+
+    expected_url = (
+        "https://api.example.com/api/v1/test?limit=10&offset=5"
+        "&order=-created,name"
+        "&select=-audit,product.agreements,-product.agreements.product"
+        "&eq(status,active)"
+    )
+    with respx.mock:
+        mock_route = respx.get("https://api.example.com/api/v1/test").mock(
+            return_value=list_response
+        )
+        collection_results = await custom_collection.fetch_page(limit=10, offset=5)
+
+    assert collection_results.to_list() == [{"id": "ID-1"}]
+    assert mock_route.called
+    assert mock_route.call_count == 1
+    request = mock_route.calls[0].request
+    assert request.method == "GET"
+    assert request.url == expected_url

tests/http/collection/test_async_collection_client_init.py

@@ -0,0 +1,34 @@
+import pytest
+
+from mpt_api_client.http.client import HTTPClientAsync
+from mpt_api_client.rql.query_builder import RQLQuery
+from tests.http.conftest import DummyAsyncCollectionClientBase
+
+
+@pytest.fixture
+def mock_mpt_client_async(api_url, api_token):
+    return HTTPClientAsync(base_url=api_url, api_token=api_token)
+
+
+@pytest.fixture
+def sample_rql_query():
+    return RQLQuery(status="active")
+
+
+def test_init_defaults(async_collection_client):
+    assert async_collection_client.query_rql is None
+    assert async_collection_client.query_order_by is None
+    assert async_collection_client.query_select is None
+    assert async_collection_client.build_url() == "/api/v1/test"
+
+
+def test_init_with_filter(http_client_async, sample_rql_query):
+    collection_client = DummyAsyncCollectionClientBase(
+        http_client=http_client_async,
+        query_rql=sample_rql_query,
+    )
+
+    assert collection_client.query_rql == sample_rql_query
+    assert collection_client.query_order_by is None
+    assert collection_client.query_select is None
+    assert collection_client.build_url() == "/api/v1/test?eq(status,active)"