Fix service and improve orders docstrings

Author: albertsola

mpt_api_client/http/async_service.py

@@ -5,6 +5,8 @@
 
 from mpt_api_client.http.async_client import AsyncHTTPClient
 from mpt_api_client.http.base_service import ServiceBase
+from mpt_api_client.http.helper import prepare_query_params
+from mpt_api_client.http.types import QueryParam
 from mpt_api_client.models import Collection, ResourceData
 from mpt_api_client.models import Model as BaseModel
 from mpt_api_client.models.collection import ResourceList
@@ -23,7 +25,11 @@ class AsyncService[Model: BaseModel](ServiceBase[AsyncHTTPClient, Model]):  # no
     """
 
     async def fetch_page(self, limit: int = 100, offset: int = 0) -> Collection[Model]:
-        """Fetch one page of resources."""
+        """Fetch one page of resources.
+
+        Returns:
+            Collection of resources.
+        """
         response = await self._fetch_page_as_response(limit=limit, offset=offset)
         return self._create_collection(response)
 
@@ -83,16 +89,39 @@ async def create(self, resource_data: ResourceData) -> Model:
 
         return self._model_class.from_response(response)
 
-    async def get(self, resource_id: str) -> Model:
-        """Fetch a specific resource using `GET /endpoint/{resource_id}`."""
-        return await self._resource_action(resource_id=resource_id)
+    async def get(self, resource_id: str, select: list[str] | str | None = None) -> Model:
+        """Fetch a specific resource using `GET /endpoint/{resource_id}`.
+
+        Args:
+            resource_id: Resource ID.
+            select: List of fields to select.
+
+        Returns:
+            Resource object.
+        """
+        if isinstance(select, list):
+            select = ",".join(select) if select else None
+        return await self._resource_action(resource_id=resource_id, query_params={"select": select})
 
     async def update(self, resource_id: str, resource_data: ResourceData) -> Model:
-        """Update a resource using `PUT /endpoint/{resource_id}`."""
+        """Update a resource using `PUT /endpoint/{resource_id}`.
+
+        Args:
+            resource_id: Resource ID.
+            resource_data: Resource data.
+
+        Returns:
+            Resource object.
+
+        """
         return await self._resource_action(resource_id, "PUT", json=resource_data)
 
     async def delete(self, resource_id: str) -> None:
-        """Delete resource using `DELETE /endpoint/{resource_id}`."""
+        """Delete resource using `DELETE /endpoint/{resource_id}`.
+
+        Args:
+            resource_id: Resource ID.
+        """
         url = urljoin(f"{self._endpoint}/", resource_id)
         response = await self.http_client.delete(url)
         response.raise_for_status()
@@ -118,6 +147,7 @@ async def _resource_do_request(
         method: str = "GET",
         action: str | None = None,
         json: ResourceData | ResourceList | None = None,
+        query_params: QueryParam | None = None,
     ) -> httpx.Response:
         """Perform an action on a specific resource using.
 
@@ -129,13 +159,16 @@ async def _resource_do_request(
             method: The HTTP method to use.
             action: The action name to use.
             json: The updated resource data.
+            query_params: Additional query parameters.
 
         Raises:
             HTTPError: If the action fails.
         """
         resource_url = urljoin(f"{self._endpoint}/", resource_id)
         url = urljoin(f"{resource_url}/", action) if action else resource_url
-        response = await self.http_client.request(method, url, json=json)
+        response = await self.http_client.request(
+            method, url, json=json, params=prepare_query_params(query_params)
+        )
         response.raise_for_status()
         return response
 
@@ -145,7 +178,18 @@ async def _resource_action(
         method: str = "GET",
         action: str | None = None,
         json: ResourceData | ResourceList | None = None,
+        query_params: QueryParam | None = None,
     ) -> Model:
-        """Perform an action on a specific resource using `HTTP_METHOD /endpoint/{resource_id}`."""
-        response = await self._resource_do_request(resource_id, method, action, json=json)
+        """Perform an action on a specific resource using `HTTP_METHOD /endpoint/{resource_id}`.
+
+        Args:
+            resource_id: The resource ID to operate on.
+            method: The HTTP method to use.
+            action: The action name to use.
+            json: The updated resource data.
+            query_params: Additional query parameters.
+        """
+        response = await self._resource_do_request(
+            resource_id, method, action, json=json, query_params=query_params
+        )
         return self._model_class.from_response(response)

mpt_api_client/http/helper.py

@@ -0,0 +1,24 @@
+from mpt_api_client.http.types import QueryParam
+
+
+def prepare_query_params(query_params: QueryParam | None) -> dict[str, str] | None:
+    """
+    Prepare and clean the query params dict.
+
+    Converts all params to string and removes any value that is None.
+
+    Args:
+        query_params: dict of query params.
+
+    Returns:
+        dict or None if the params were not present.
+
+    """
+    if not query_params:
+        return None
+    clean_params = {
+        param_name: str(param_value)
+        for param_name, param_value in query_params.items()
+        if param_value is not None
+    }
+    return clean_params or None

mpt_api_client/http/service.py

@@ -5,6 +5,8 @@
 
 from mpt_api_client.http.base_service import ServiceBase
 from mpt_api_client.http.client import HTTPClient
+from mpt_api_client.http.helper import prepare_query_params
+from mpt_api_client.http.types import QueryParam
 from mpt_api_client.models import Collection, ResourceData
 from mpt_api_client.models import Model as BaseModel
 from mpt_api_client.models.collection import ResourceList
@@ -86,16 +88,40 @@ def create(self, resource_data: ResourceData) -> Model:
 
         return self._model_class.from_response(response)
 
-    def get(self, resource_id: str) -> Model:
-        """Fetch a specific resource using `GET /endpoint/{resource_id}`."""
-        return self._resource_action(resource_id=resource_id)
+    def get(self, resource_id: str, select: list[str] | str | None = None) -> Model:
+        """Fetch a specific resource using `GET /endpoint/{resource_id}`.
+
+        Args:
+            resource_id: Resource ID.
+            select: List of fields to select.
+
+        Returns:
+            Resource object.
+        """
+        if isinstance(select, list):
+            select = ",".join(select) if select else None
+
+        return self._resource_action(resource_id=resource_id, query_params={"select": select})
 
     def update(self, resource_id: str, resource_data: ResourceData) -> Model:
-        """Update a resource using `PUT /endpoint/{resource_id}`."""
+        """Update a resource using `PUT /endpoint/{resource_id}`.
+
+        Args:
+            resource_id: Resource ID.
+            resource_data: Resource data.
+
+        Returns:
+            Resource object.
+
+        """
         return self._resource_action(resource_id, "PUT", json=resource_data)
 
     def delete(self, resource_id: str) -> None:
-        """Delete the resoruce using `DELETE /endpoint/{resource_id}`."""
+        """Delete resource using `DELETE /endpoint/{resource_id}`.
+
+        Args:
+            resource_id: Resource ID.
+        """
         response = self._resource_do_request(resource_id, "DELETE")
         response.raise_for_status()
 
@@ -120,6 +146,7 @@ def _resource_do_request(
         method: str = "GET",
         action: str | None = None,
         json: ResourceData | ResourceList | None = None,
+        query_params: QueryParam | None = None,
     ) -> httpx.Response:
         """Perform an action on a specific resource using `HTTP_METHOD /endpoint/{resource_id}`.
 
@@ -128,6 +155,7 @@ def _resource_do_request(
             method: The HTTP method to use.
             action: The action name to use.
             json: The updated resource data.
+            query_params: Additional query parameters.
 
         Returns:
             HTTP response object.
@@ -137,7 +165,9 @@ def _resource_do_request(
         """
         resource_url = urljoin(f"{self._endpoint}/", resource_id)
         url = urljoin(f"{resource_url}/", action) if action else resource_url
-        response = self.http_client.request(method, url, json=json)
+        response = self.http_client.request(
+            method, url, json=json, params=prepare_query_params(query_params)
+        )
         response.raise_for_status()
         return response
 
@@ -147,7 +177,18 @@ def _resource_action(
         method: str = "GET",
         action: str | None = None,
         json: ResourceData | ResourceList | None = None,
+        query_params: QueryParam | None = None,
     ) -> Model:
-        """Perform an action on a specific resource using `HTTP_METHOD /endpoint/{resource_id}`."""
-        response = self._resource_do_request(resource_id, method, action, json=json)
+        """Perform an action on a specific resource using `HTTP_METHOD /endpoint/{resource_id}`.
+
+        Args:
+            resource_id: The resource ID to operate on.
+            method: The HTTP method to use.
+            action: The action name to use.
+            json: The updated resource data.
+            query_params: Additional query parameters.
+        """
+        response = self._resource_do_request(
+            resource_id, method, action, json=json, query_params=query_params
+        )
         return self._model_class.from_response(response)

mpt_api_client/http/types.py

@@ -0,0 +1,2 @@
+PrimitiveType = str | int | float | bool | None
+QueryParam = dict[str, PrimitiveType]

mpt_api_client/resources/commerce/orders.py

@@ -15,7 +15,7 @@ class OrdersServiceConfig:
 
 
 class OrdersService(Service[Order], OrdersServiceConfig):
-    """Orders client."""
+    """Orders service."""
 
     def validate(self, resource_id: str, resource_data: ResourceData | None = None) -> Order:
         """Switch order to validate state.
@@ -85,7 +85,7 @@ def template(self, resource_id: str) -> str:
 
 
 class AsyncOrdersService(AsyncService[Order], OrdersServiceConfig):
-    """Async Orders client."""
+    """Async Orders service."""
 
     async def validate(self, resource_id: str, resource_data: ResourceData | None = None) -> Order:
         """Switch order to validate state.

tests/http/test_async_service.py

@@ -300,6 +300,6 @@ async def test_async_get(async_dummy_service):
             return_value=httpx.Response(httpx.codes.OK, json=resource_data)
         )
 
-        resource = await async_dummy_service.get("RES-123")
+        resource = await async_dummy_service.get("RES-123", select=["id", "name"])
     assert isinstance(resource, DummyModel)
     assert resource.to_dict() == resource_data

tests/http/test_service.py

@@ -101,7 +101,7 @@ def test_sync_get(dummy_service):
             return_value=httpx.Response(httpx.codes.OK, json=resource_data)
         )
 
-        resource = dummy_service.get("RES-123")
+        resource = dummy_service.get("RES-123", select=["id", "name"])
     assert isinstance(resource, DummyModel)
     assert resource.to_dict() == resource_data