MPT-12330 Order resource client

Author: albertsola

mpt_api_client/http/collection.py

@@ -6,11 +6,14 @@
 import httpx
 
 from mpt_api_client.http.client import MPTClient
+from mpt_api_client.http.resource import ResourceBaseClient
 from mpt_api_client.models import Collection, Resource
 from mpt_api_client.rql.query_builder import RQLQuery
 
 
-class CollectionBaseClient[ResourceType: Resource](ABC):  # noqa: WPS214
+class CollectionBaseClient[ResourceModel: Resource, ResourceClient: ResourceBaseClient[Resource]](  # noqa: WPS214
+    ABC
+):
     """Immutable Base client for RESTful resource collections.
 
     Examples:
@@ -23,8 +26,9 @@ class CollectionBaseClient[ResourceType: Resource](ABC):  # noqa: WPS214
     """
 
     _endpoint: str
-    _resource_class: type[ResourceType]
-    _collection_class: type[Collection[ResourceType]]
+    _resource_class: type[ResourceModel]
+    _resource_client_class: type[ResourceClient]
+    _collection_class: type[Collection[ResourceModel]]
 
     def __init__(
         self,
@@ -37,7 +41,9 @@ def __init__(
         self.query_select: list[str] | None = None
 
     @classmethod
-    def clone(cls, collection_client: "CollectionBaseClient[ResourceType]") -> Self:
+    def clone(
+        cls, collection_client: "CollectionBaseClient[ResourceModel, ResourceClient]"
+    ) -> Self:
         """Create a copy of collection client for immutable operations.
 
         Returns:
@@ -122,7 +128,7 @@ def select(self, *fields: str) -> Self:
         new_client.query_select = list(fields)
         return new_client
 
-    def fetch_page(self, limit: int = 100, offset: int = 0) -> Collection[ResourceType]:
+    def fetch_page(self, limit: int = 100, offset: int = 0) -> Collection[ResourceModel]:
         """Fetch one page of resources.
 
         Returns:
@@ -131,7 +137,7 @@ def fetch_page(self, limit: int = 100, offset: int = 0) -> Collection[ResourceTy
         response = self._fetch_page_as_response(limit=limit, offset=offset)
         return Collection.from_response(response)
 
-    def fetch_one(self) -> ResourceType:
+    def fetch_one(self) -> ResourceModel:
         """Fetch one page, expect exactly one result.
 
         Returns:
@@ -141,7 +147,7 @@ def fetch_one(self) -> ResourceType:
             ValueError: If the total matching records are not exactly one.
         """
         response = self._fetch_page_as_response(limit=1, offset=0)
-        resource_list: Collection[ResourceType] = Collection.from_response(response)
+        resource_list: Collection[ResourceModel] = Collection.from_response(response)
         total_records = len(resource_list)
         if resource_list.meta:
             total_records = resource_list.meta.pagination.total
@@ -152,7 +158,7 @@ def fetch_one(self) -> ResourceType:
 
         return resource_list[0]
 
-    def iterate(self) -> Iterator[ResourceType]:
+    def iterate(self) -> Iterator[ResourceModel]:
         """Iterate over all resources, yielding GenericResource objects.
 
         Returns:
@@ -163,7 +169,7 @@ def iterate(self) -> Iterator[ResourceType]:
 
         while True:
             response = self._fetch_page_as_response(limit=limit, offset=offset)
-            items_collection: Collection[ResourceType] = Collection.from_response(response)
+            items_collection: Collection[ResourceModel] = Collection.from_response(response)
             yield from items_collection
 
             if not items_collection.meta:
@@ -172,7 +178,11 @@ def iterate(self) -> Iterator[ResourceType]:
                 break
             offset = items_collection.meta.pagination.next_offset()
 
-    def create(self, resource_data: dict[str, Any]) -> ResourceType:
+    def get(self, resource_id: str) -> ResourceClient:
+        """Get resource by resource_id."""
+        return self._resource_client_class(client=self.mpt_client, resource_id=resource_id)
+
+    def create(self, resource_data: dict[str, Any]) -> ResourceModel:
         """Create a new resource using `POST /endpoint`.
 
         Returns:

mpt_api_client/http/resource.py

@@ -51,18 +51,23 @@ def fetch(self) -> Resource:
         return self.resource_
 
     def do_action(
-        self, http_method: str = "GET", payload: dict[str, Any] | list[Any] | None = None  # noqa: WPS221
+        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:
-            http_method: The HTTP method to use.
-            payload: The updated resource data.
+            method: The HTTP method to use.
+            url: The action name to use.
+            json: The updated resource data.
 
         Raises:
             HTTPError: If the action fails.
         """
-        response = self.mpt_client_.request(http_method, self.resource_url, json=payload)
+        url = f"{self.resource_url}/{url}" if url else self.resource_url
+        response = self.mpt_client_.request(method, url, json=json)
         response.raise_for_status()
         return response
 
@@ -80,7 +85,7 @@ def update(self, resource_data: dict[str, Any]) -> Resource:
 
 
         """
-        response = self.do_action("PUT", resource_data)
+        response = self.do_action("PUT", json=resource_data)
         self.resource_ = self._resource_class.from_response(response)  # noqa: WPS120
         return self.resource_
 
@@ -109,7 +114,7 @@ def delete(self) -> None:
         Examples:
             contact.delete()
         """
-        response = self.mpt_client_.delete(self.resource_url)
+        response = self.do_action("DELETE")
         response.raise_for_status()
 
         self.resource_ = None  # noqa: WPS120

mpt_api_client/modules/order.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 from mpt_api_client.http.collection import CollectionBaseClient
 from mpt_api_client.http.resource import ResourceBaseClient
 from mpt_api_client.models import Collection, Resource
@@ -8,17 +10,80 @@ class Order(Resource):
     """Order resource."""
 
 
-@commerce("orders")
-class OrderCollectionClient(CollectionBaseClient[Order]):
-    """Orders client."""
+class OrderResourceClient(ResourceBaseClient[Order]):
+    """Order resource client."""
 
     _endpoint = "/public/v1/commerce/orders"
     _resource_class = Order
-    _collection_class = Collection[Order]
 
+    def validate(self, order: dict[str, Any]) -> Order:
+        """Switch order to validate state.
 
-class OrderResourceClient(ResourceBaseClient[Order]):
-    """Order resource client."""
+        Args:
+            order: Order data will be updated
+        """
+        response = self.do_action("POST", "validate", json=order)
+        return self._resource_class.from_response(response)
+
+    def process(self, order: dict[str, Any]) -> Order:
+        """Switch order to process state.
+
+        Args:
+            order: Order data will be updated
+        """
+        response = self.do_action("POST", "process", json=order)
+        return self._resource_class.from_response(response)
+
+    def query(self, order: dict[str, Any]) -> Order:
+        """Switch order to query state.
+
+        Args:
+            order: Order data will be updated
+        """
+        response = self.do_action("POST", "query", json=order)
+        return self._resource_class.from_response(response)
+
+    def complete(self, order: dict[str, Any]) -> Order:
+        """Switch order to complete state.
+
+        Args:
+            order: Order data will be updated
+        """
+        response = self.do_action("POST", "complete", json=order)
+        return self._resource_class.from_response(response)
+
+    def fail(self, order: dict[str, Any]) -> Order:
+        """Switch order to fail state.
+
+        Args:
+            order: Order data will be updated
+        """
+        response = self.do_action("POST", "fail", json=order)
+        return self._resource_class.from_response(response)
+
+    def notify(self, user: dict[str, Any]) -> None:
+        """Notify user about order status.
+
+        Args:
+            user: User data
+        """
+        self.do_action("POST", "notify", json=user)
+
+    def template(self) -> str:
+        """Render order template.
+
+        Returns:
+            Order template text in markdown format.
+        """
+        response = self.do_action("GET", "template")
+        return response.text
+
+
+@commerce("orders")
+class OrderCollectionClient(CollectionBaseClient[Order, OrderResourceClient]):
+    """Orders client."""
 
     _endpoint = "/public/v1/commerce/orders"
     _resource_class = Order
+    _resource_client_class = OrderResourceClient
+    _collection_class = Collection[Order]

mpt_api_client/registry.py

@@ -3,7 +3,7 @@
 
 from mpt_api_client.http.collection import CollectionBaseClient
 
-ItemType = type[CollectionBaseClient[Any]]
+ItemType = type[CollectionBaseClient[Any, Any]]
 
 
 class Registry:

setup.cfg

@@ -48,4 +48,6 @@ per-file-ignores =
   tests/*:
     # Allow magic strings
     WPS432
+    # Found too many modules members
+    WPS202
 

tests/http/collection/conftest.py

@@ -1,13 +1,8 @@
 import pytest
 
 from mpt_api_client.http.client import MPTClient
-from mpt_api_client.models import Resource
 from mpt_api_client.rql.query_builder import RQLQuery
-from tests.http.collection.conftest import DummyCollectionClient
-
-
-class DummyResource(Resource):
-    """Dummy resource for testing."""
+from tests.http.conftest import DummyCollectionClient
 
 
 @pytest.fixture

tests/http/collection/test_collection_client_init.py

@@ -0,0 +1,4 @@
+def test_get(collection_client):
+    resource = collection_client.get("RES-123")
+    assert resource.resource_id_ == "RES-123"
+    assert isinstance(resource, collection_client._resource_client_class)  # noqa: SLF001

tests/http/collection/test_collection_get.py

@@ -1,7 +1,9 @@
 import pytest
 
 from mpt_api_client.http.client import MPTClient
+from mpt_api_client.http.collection import CollectionBaseClient
 from mpt_api_client.http.resource import ResourceBaseClient
+from mpt_api_client.models import Collection
 from tests.conftest import DummyResource
 
 
@@ -10,6 +12,13 @@ class DummyResourceClient(ResourceBaseClient[DummyResource]):
     _resource_class = DummyResource
 
 
+class DummyCollectionClient(CollectionBaseClient[DummyResource, DummyResourceClient]):
+    _endpoint = "/api/v1/test"
+    _resource_class = DummyResource
+    _resource_client_class = DummyResourceClient
+    _collection_class = Collection[DummyResource]
+
+
 @pytest.fixture
 def api_url():
     return "https://api.example.com"
@@ -28,3 +37,8 @@ def mpt_client(api_url, api_token):
 @pytest.fixture
 def resource_client(mpt_client):
     return DummyResourceClient(client=mpt_client, resource_id="RES-123")
+
+
+@pytest.fixture
+def collection_client(mpt_client) -> DummyCollectionClient:
+    return DummyCollectionClient(client=mpt_client)

tests/http/resource/conftest.py tests/http/conftest.pytests/http/resource/conftest.py renamed to tests/http/conftest.py

@@ -1,11 +1,6 @@
-from mpt_api_client.modules.order import Order, OrderCollectionClient
+from mpt_api_client.modules.order import OrderCollectionClient
 
 
 def test_order_collection_client(mpt_client):
     order_cc = OrderCollectionClient(client=mpt_client)
     assert order_cc.query_rql is None
-
-
-def test_order():
-    order = Order()
-    assert order is not None