MPT-12358 Resource client async

Author: albertsola

mpt_api_client/http/collection.py

@@ -6,7 +6,7 @@
 import httpx
 
 from mpt_api_client.http.client import HTTPClient, HTTPClientAsync
-from mpt_api_client.http.resource import ResourceBaseClient
+from mpt_api_client.http.resource import AsyncResourceBaseClient, ResourceBaseClient
 from mpt_api_client.models import Collection, Resource
 from mpt_api_client.rql.query_builder import RQLQuery
 
@@ -230,7 +230,7 @@ def _fetch_page_as_response(self, limit: int = 100, offset: int = 0) -> httpx.Re
 
 class AsyncCollectionClientBase[
     ResourceModel: Resource,
-    ResourceClient: ResourceBaseClient[Resource],
+    ResourceClient: AsyncResourceBaseClient[Resource],
 ](ABC, CollectionMixin):
     """Immutable Base client for RESTful resource collections.
 
@@ -313,7 +313,7 @@ async def iterate(self, batch_size: int = 100) -> AsyncIterator[ResourceModel]:
 
     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]
+        return self._resource_client_class(http_client=self.http_client, resource_id=resource_id)
 
     async def create(self, resource_data: dict[str, Any]) -> ResourceModel:
         """Create a new resource using `POST /endpoint`.

mpt_api_client/http/resource.py

@@ -3,25 +3,27 @@
 
 from httpx import Response
 
-from mpt_api_client.http.client import HTTPClient
+from mpt_api_client.http.client import HTTPClient, HTTPClientAsync
 from mpt_api_client.models import Resource
 
 
-class ResourceBaseClient[ResourceModel: Resource](ABC):  # noqa: WPS214
-    """Client for RESTful resources."""
+class ResourceMixin:
+    """Mixin for resource clients."""
 
     _endpoint: str
-    _resource_class: type[ResourceModel]
+    _resource_class: type[Any]
     _safe_attributes: ClassVar[set[str]] = {"http_client_", "resource_id_", "resource_"}
 
-    def __init__(self, http_client: HTTPClient, resource_id: str) -> None:
-        self.http_client_ = http_client  # noqa: WPS120
-        self.resource_id_ = resource_id  # noqa: WPS120
-        self.resource_: Resource | None = None  # noqa: WPS120
+    def __init__(
+        self, http_client: HTTPClient | HTTPClientAsync, resource_id: str, resource: Resource | None
+    ) -> None:
+        self.http_client_ = http_client
+        self.resource_id_ = resource_id
+        self.resource_: Resource | None = resource
 
     def __getattr__(self, attribute: str) -> Any:
         """Returns the resource data."""
-        self._ensure_resource_is_fetched()
+        self._assert_resource_is_set()
         return self.resource_.__getattr__(attribute)  # type: ignore[union-attr]
 
     @property
@@ -34,9 +36,32 @@ def __setattr__(self, attribute: str, attribute_value: Any) -> None:
         if attribute in self._safe_attributes:
             object.__setattr__(self, attribute, attribute_value)
             return
-        self._ensure_resource_is_fetched()
+        self._assert_resource_is_set()
         self.resource_.__setattr__(attribute, attribute_value)
 
+    def _assert_resource_is_set(self) -> None:
+        if not self.resource_:
+            raise RuntimeError(
+                f"Resource data not available. Call fetch() method first to retrieve"  # noqa: WPS237
+                f" the resource `{self._resource_class.__name__}`"
+            )
+
+
+class ResourceBaseClient[ResourceModel: Resource](ABC, ResourceMixin):  # noqa: WPS214
+    """Client for RESTful resources."""
+
+    _endpoint: str
+    _resource_class: type[ResourceModel]
+    _safe_attributes: ClassVar[set[str]] = {"http_client_", "resource_id_", "resource_"}
+
+    def __init__(
+        self, http_client: HTTPClient, resource_id: str, resource: Resource | None = None
+    ) -> None:
+        self.http_client_: HTTPClient = http_client  # type: ignore[mutable-override]
+        ResourceMixin.__init__(
+            self, http_client=http_client, resource_id=resource_id, resource=resource
+        )
+
     def fetch(self) -> ResourceModel:
         """Fetch a specific resource using `GET /endpoint/{resource_id}`.
 
@@ -47,7 +72,7 @@ def fetch(self) -> ResourceModel:
         """
         response = self.do_action("GET")
 
-        self.resource_ = self._resource_class.from_response(response)  # noqa: WPS120
+        self.resource_ = self._resource_class.from_response(response)
         return self.resource_
 
     def resource_action(
@@ -58,7 +83,7 @@ def resource_action(
     ) -> ResourceModel:
         """Perform an action on a specific resource using `HTTP_METHOD /endpoint/{resource_id}`."""
         response = self.do_action(method, url, json=json)
-        self.resource_ = self._resource_class.from_response(response)  # noqa: WPS120
+        self.resource_ = self._resource_class.from_response(response)
         return self.resource_
 
     def do_action(
@@ -97,7 +122,7 @@ def update(self, resource_data: dict[str, Any]) -> ResourceModel:
 
         """
         response = self.do_action("PUT", json=resource_data)
-        self.resource_ = self._resource_class.from_response(response)  # noqa: WPS120
+        self.resource_ = self._resource_class.from_response(response)
         return self.resource_
 
     def save(self) -> Self:
@@ -111,9 +136,8 @@ def save(self) -> Self:
             contact.save()
 
         """
-        if not self.resource_:
-            raise ValueError("Unable to save resource that has not been set.")
-        self.update(self.resource_.to_dict())
+        self._assert_resource_is_set()
+        self.update(self.resource_.to_dict())  # type: ignore[union-attr]
         return self
 
     def delete(self) -> None:
@@ -128,8 +152,110 @@ def delete(self) -> None:
         response = self.do_action("DELETE")
         response.raise_for_status()
 
-        self.resource_ = None  # noqa: WPS120
+        self.resource_ = None
 
-    def _ensure_resource_is_fetched(self) -> None:
-        if not self.resource_:
-            self.fetch()
+
+class AsyncResourceBaseClient[ResourceModel: Resource](ABC, ResourceMixin):  # noqa: WPS214
+    """Client for RESTful resources."""
+
+    _endpoint: str
+    _resource_class: type[ResourceModel]
+    _safe_attributes: ClassVar[set[str]] = {"http_client_", "resource_id_", "resource_"}
+
+    def __init__(
+        self, http_client: HTTPClientAsync, resource_id: str, resource: Resource | None = None
+    ) -> None:
+        self.http_client_: HTTPClientAsync = http_client  # type: ignore[mutable-override]
+        ResourceMixin.__init__(
+            self, http_client=http_client, resource_id=resource_id, resource=resource
+        )
+
+    async def fetch(self) -> ResourceModel:
+        """Fetch a specific resource using `GET /endpoint/{resource_id}`.
+
+        It fetches and caches the resource.
+
+        Returns:
+            The fetched resource.
+        """
+        response = await self.do_action("GET")
+
+        self.resource_ = self._resource_class.from_response(response)
+        return self.resource_
+
+    async def resource_action(
+        self,
+        method: str = "GET",
+        url: str | None = None,
+        json: dict[str, Any] | list[Any] | None = None,  # noqa: WPS221
+    ) -> ResourceModel:
+        """Perform an action on a specific resource using `HTTP_METHOD /endpoint/{resource_id}`."""
+        response = await self.do_action(method, url, json=json)
+        self.resource_ = self._resource_class.from_response(response)
+        return self.resource_
+
+    async def do_action(
+        self,
+        method: str = "GET",
+        url: str | None = None,
+        json: dict[str, Any] | list[Any] | None = None,  # noqa: WPS221
+    ) -> Response:
+        """Perform an action on a specific resource using `HTTP_METHOD /endpoint/{resource_id}`.
+
+        Args:
+            method: The HTTP method to use.
+            url: The action name to use.
+            json: The updated resource data.
+
+        Raises:
+            HTTPError: If the action fails.
+        """
+        url = f"{self.resource_url}/{url}" if url else self.resource_url
+        response = await self.http_client_.request(method, url, json=json)
+        response.raise_for_status()
+        return response
+
+    async def update(self, resource_data: dict[str, Any]) -> ResourceModel:
+        """Update a specific in the API and catches the result as a current resource.
+
+        Args:
+            resource_data: The updated resource data.
+
+        Returns:
+            The updated resource.
+
+        Examples:
+            updated_contact = contact.update({"name": "New Name"})
+
+
+        """
+        return await self.resource_action("PUT", json=resource_data)
+
+    async def save(self) -> Self:
+        """Save the current state of the resource to the api using the update method.
+
+        Raises:
+            ValueError: If the resource has not been set.
+
+        Examples:
+            contact.name = "New Name"
+            contact.save()
+
+        """
+        self._assert_resource_is_set()
+        await self.update(self.resource_.to_dict())  # type: ignore[union-attr]
+        return self
+
+    async def delete(self) -> None:
+        """Delete the resource using `DELETE /endpoint/{resource_id}`.
+
+        Raises:
+            HTTPStatusError: If the deletion fails.
+
+        Examples:
+            contact.delete()
+        """
+        response = await self.do_action("DELETE")
+        response.raise_for_status()
+
+        self.resource_ = None

setup.cfg

@@ -33,21 +33,25 @@ extend-ignore =
 
 per-file-ignores =
   mpt_api_client/rql/query_builder.py:
-    # Forbid blacklisted variable names
+    # Forbid blacklisted variable names.
     WPS110
-    # Found `noqa` comments overuse
+    # Found `noqa` comments overuse.
     WPS402
   tests/http/collection/test_collection_client_iterate.py:
     # Found too many module members
     WPS202
   tests/http/collection/test_collection_client_fetch.py:
-    # Found too many module members
+    # Found too many module members.
     WPS202
-    # Found magic number
+    # Found magic number.
     WPS432
+  mpt_api_client/http/resource.py:
+    WPS120
+    # Found regular name with trailing underscore.
+    # We use trailing underscore to avoid potential collisions with API models attributes.
   tests/*:
-    # Allow magic strings
+    # Allow magic strings.
     WPS432
-    # Found too many modules members
+    # Found too many modules members.
     WPS202
 

tests/http/collection/test_async_collection_get.py

@@ -0,0 +1,8 @@
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_get(async_collection_client):
+    resource = await async_collection_client.get("RES-123")
+    assert resource.resource_id_ == "RES-123"
+    assert isinstance(resource, async_collection_client._resource_client_class)  # noqa: SLF001

tests/http/conftest.py

@@ -2,7 +2,7 @@
 
 from mpt_api_client.http.client import HTTPClient, HTTPClientAsync
 from mpt_api_client.http.collection import AsyncCollectionClientBase, CollectionClientBase
-from mpt_api_client.http.resource import ResourceBaseClient
+from mpt_api_client.http.resource import AsyncResourceBaseClient, ResourceBaseClient
 from mpt_api_client.models import Collection
 from tests.conftest import DummyResource
 
@@ -19,10 +19,17 @@ class DummyCollectionClientBase(CollectionClientBase[DummyResource, DummyResourc
     _collection_class = Collection[DummyResource]
 
 
-class DummyAsyncCollectionClientBase(AsyncCollectionClientBase[DummyResource, DummyResourceClient]):
+class DummyAsyncResourceClient(AsyncResourceBaseClient[DummyResource]):
+    _endpoint = "/api/v1/test-resource"
+    _resource_class = DummyResource
+
+
+class DummyAsyncCollectionClientBase(
+    AsyncCollectionClientBase[DummyResource, DummyAsyncResourceClient]
+):
     _endpoint = "/api/v1/test"
     _resource_class = DummyResource
-    _resource_client_class = DummyResourceClient
+    _resource_client_class = DummyAsyncResourceClient
     _collection_class = Collection[DummyResource]
 
 
@@ -59,3 +66,9 @@ def collection_client(http_client) -> DummyCollectionClientBase:
 @pytest.fixture
 def async_collection_client(http_client_async) -> DummyAsyncCollectionClientBase:
     return DummyAsyncCollectionClientBase(http_client=http_client_async)
+
+
+@pytest.fixture
+def async_resource_client(http_client_async):
+    """Create an async resource client for testing."""
+    return DummyAsyncResourceClient(http_client=http_client_async, resource_id="RES-123")