MPT-14532 Cleanup base service

Author: albertsola

mpt_api_client/http/async_service.py

@@ -85,7 +85,7 @@ async def _fetch_page_as_response(self, limit: int = 100, offset: int = 0) -> Re
             HTTPStatusError: if the response status code is not 200.
         """
         pagination_params: dict[str, int] = {"limit": limit, "offset": offset}
-        return await self.http_client.request("get", self.build_url(pagination_params))
+        return await self.http_client.request("get", self.build_path(pagination_params))
 
     async def _resource_do_request(  # noqa: WPS211
         self,
@@ -112,7 +112,7 @@ async def _resource_do_request(  # noqa: WPS211
         Raises:
             HTTPError: If the action fails.
         """
-        resource_url = urljoin(f"{self.endpoint}/", resource_id)
+        resource_url = urljoin(f"{self.path}/", resource_id)
         url = urljoin(f"{resource_url}/", action) if action else resource_url
         return await self.http_client.request(
             method, url, json=json, query_params=query_params, headers=headers

mpt_api_client/http/base_service.py

@@ -1,6 +1,6 @@
-import copy
 from typing import Any, Self
 
+from mpt_api_client.http.query_state import QueryState
 from mpt_api_client.http.types import Response
 from mpt_api_client.models import Collection, Meta
 from mpt_api_client.models import Model as BaseModel
@@ -18,62 +18,29 @@ def __init__(
         self,
         *,
         http_client: Client,
-        query_rql: RQLQuery | None = None,
-        query_order_by: list[str] | None = None,
-        query_select: list[str] | None = None,
+        query_state: QueryState | None = None,
         endpoint_params: dict[str, str] | None = None,
     ) -> None:
         self.http_client = http_client
-        self.query_rql: RQLQuery | None = query_rql
-        self.query_order_by = query_order_by
-        self.query_select = query_select
+        self.query_state = query_state or QueryState()
         self.endpoint_params = endpoint_params or {}
 
-    def clone(self) -> Self:
-        """Create a copy of collection client for immutable operations.
-
-        Returns:
-            New collection client with same settings.
-        """
-        return type(self)(
-            http_client=self.http_client,
-            query_rql=self.query_rql,
-            query_order_by=copy.copy(self.query_order_by) if self.query_order_by else None,
-            query_select=copy.copy(self.query_select) if self.query_select else None,
-            endpoint_params=self.endpoint_params,
-        )
-
     @property
-    def endpoint(self) -> str:
+    def path(self) -> str:
         """Service endpoint URL."""
         return self._endpoint.format(**self.endpoint_params)
 
-    def build_url(
+    def build_path(
         self,
         query_params: dict[str, Any] | None = None,
-    ) -> str:  # noqa: WPS210
+    ) -> str:
         """Builds the endpoint URL with all the query parameters.
 
         Returns:
-            Partial URL with query parameters.
+            Complete URL with query parameters.
         """
-        query_params = query_params or {}
-        if self.query_order_by:
-            query_params.update({"order": ",".join(self.query_order_by)})
-        if self.query_select:
-            query_params.update({"select": ",".join(self.query_select)})
-
-        query_parts = [
-            f"{param_key}={param_value}" for param_key, param_value in query_params.items()
-        ]
-
-        if self.query_rql:
-            query_parts.append(str(self.query_rql))
-
-        if query_parts:
-            query = "&".join(query_parts)
-            return f"{self.endpoint}?{query}"
-        return self.endpoint
+        query = self.query_state.build(query_params)
+        return f"{self.path}?{query}" if query else self.path
 
     def order_by(self, *fields: str) -> Self:
         """Returns new collection with ordering setup.
@@ -84,23 +51,35 @@ def order_by(self, *fields: str) -> Self:
         Raises:
             ValueError: If ordering has already been set.
         """
-        if self.query_order_by is not None:
+        if self.query_state.order_by is not None:
             raise ValueError("Ordering is already set. Cannot set ordering multiple times.")
-        new_collection = self.clone()
-        new_collection.query_order_by = list(fields)
-        return new_collection
+        return type(self)(
+            http_client=self.http_client,
+            query_state=QueryState(
+                rql=self.query_state.filter,
+                order_by=list(fields),
+                select=self.query_state.select,
+            ),
+            endpoint_params=self.endpoint_params,
+        )
 
     def filter(self, rql: RQLQuery) -> Self:
         """Creates a new collection with the filter added to the filter collection.
 
         Returns:
             New copy of the collection with the filter added.
         """
-        if self.query_rql:
-            rql = self.query_rql & rql
-        new_collection = self.clone()
-        new_collection.query_rql = rql
-        return new_collection
+        existing_filter = self.query_state.filter
+        combined_filter = existing_filter & rql if existing_filter else rql
+        return type(self)(
+            http_client=self.http_client,
+            query_state=QueryState(
+                rql=combined_filter,
+                order_by=self.query_state.order_by,
+                select=self.query_state.select,
+            ),
+            endpoint_params=self.endpoint_params,
+        )
 
     def select(self, *fields: str) -> Self:
         """Set select fields. Raises ValueError if select fields are already set.
@@ -111,14 +90,19 @@ def select(self, *fields: str) -> Self:
         Raises:
             ValueError: If select fields are already set.
         """
-        if self.query_select is not None:
+        if self.query_state.select is not None:
             raise ValueError(
                 "Select fields are already set. Cannot set select fields multiple times."
             )
-
-        new_client = self.clone()
-        new_client.query_select = list(fields)
-        return new_client
+        return type(self)(
+            http_client=self.http_client,
+            query_state=QueryState(
+                rql=self.query_state.filter,
+                order_by=self.query_state.order_by,
+                select=list(fields),
+            ),
+            endpoint_params=self.endpoint_params,
+        )
 
     @classmethod
     def _create_collection(cls, response: Response) -> Collection[Model]:

mpt_api_client/http/mixins.py

@@ -20,7 +20,7 @@ def create(self, resource_data: ResourceData) -> Model:
         Returns:
             New resource created.
         """
-        response = self.http_client.request("post", self.endpoint, json=resource_data)  # type: ignore[attr-defined]
+        response = self.http_client.request("post", self.path, json=resource_data)  # type: ignore[attr-defined]
 
         return self._model_class.from_response(response)  # type: ignore[attr-defined, no-any-return]
 
@@ -82,7 +82,7 @@ def create(
                 "application/json",
             )
 
-        response = self.http_client.request("post", self.endpoint, files=files)  # type: ignore[attr-defined]
+        response = self.http_client.request("post", self.path, files=files)  # type: ignore[attr-defined]
 
         return self._model_class.from_response(response)  # type: ignore[attr-defined, no-any-return]
 
@@ -110,7 +110,7 @@ async def create(self, resource_data: ResourceData) -> Model:
         Returns:
             New resource created.
         """
-        response = await self.http_client.request("post", self.endpoint, json=resource_data)  # type: ignore[attr-defined]
+        response = await self.http_client.request("post", self.path, json=resource_data)  # type: ignore[attr-defined]
 
         return self._model_class.from_response(response)  # type: ignore[attr-defined, no-any-return]
 
@@ -124,7 +124,7 @@ async def delete(self, resource_id: str) -> None:
         Args:
             resource_id: Resource ID.
         """
-        url = urljoin(f"{self.endpoint}/", resource_id)  # type: ignore[attr-defined]
+        url = urljoin(f"{self.path}/", resource_id)  # type: ignore[attr-defined]
         await self.http_client.request("delete", url)  # type: ignore[attr-defined]
 
 
@@ -173,7 +173,7 @@ async def create(
                 "application/json",
             )
 
-        response = await self.http_client.request("post", self.endpoint, files=files)  # type: ignore[attr-defined]
+        response = await self.http_client.request("post", self.path, files=files)  # type: ignore[attr-defined]
 
         return self._model_class.from_response(response)  # type: ignore[attr-defined, no-any-return]
 

mpt_api_client/http/query_state.py

@@ -0,0 +1,85 @@
+import copy
+from typing import Any, Self
+
+from mpt_api_client.rql import RQLQuery
+
+
+class QueryState:
+    """Stores and manages API query state for filtering, selecting, and ordering data.
+
+    This class maintains the current state of query parameters (filter, order_by, select)
+    and provides functionality to build query strings from that state. It's responsible
+    for both storing query configuration and constructing the appropriate query parameters
+    that modify the behavior and shape of data returned by the API.
+    """
+
+    def __init__(
+        self,
+        rql: RQLQuery | None = None,
+        order_by: list[str] | None = None,
+        select: list[str] | None = None,
+    ) -> None:
+        """Initialize the query state with optional filter, ordering, and selection criteria.
+
+        Args:
+            rql: RQL query for filtering data.
+            order_by: List of fields to order by (prefix with '-' for descending).
+            select: List of fields to select in the response.
+        """
+        self._filter = rql
+        self._order_by = order_by
+        self._select = select
+
+    @property
+    def filter(self) -> RQLQuery | None:
+        """Get the current filter query."""
+        return self._filter
+
+    @property
+    def order_by(self) -> list[str] | None:
+        """Get the current order by fields."""
+        return self._order_by
+
+    @property
+    def select(self) -> list[str] | None:
+        """Get the current select fields."""
+        return self._select
+
+    def clone(self) -> Self:
+        """Create a copy of the query state for immutable operations.
+
+        Returns:
+            New query state instance with the same filter, ordering, and selection settings.
+        """
+        return type(self)(
+            rql=self._filter,
+            order_by=copy.copy(self._order_by) if self._order_by else None,
+            select=copy.copy(self._select) if self._select else None,
+        )
+
+    def build(self, query_params: dict[str, Any] | None = None) -> str:
+        """Build a query string from the current state and additional parameters.
+
+        Args:
+            query_params: Additional query parameters to include in the query string.
+
+        Returns:
+            Complete query string with all parameters, or empty string if no parameters.
+        """
+        query_params = query_params or {}
+        if self._order_by:
+            query_params.update({"order": ",".join(self._order_by)})
+        if self._select:
+            query_params.update({"select": ",".join(self._select)})
+
+        query_parts = [
+            f"{param_key}={param_value}" for param_key, param_value in query_params.items()
+        ]
+
+        if self._filter:
+            query_parts.append(str(self._filter))
+
+        if query_parts:
+            query = "&".join(query_parts)
+            return f"{query}"
+        return ""

mpt_api_client/http/service.py

@@ -84,7 +84,7 @@ def _fetch_page_as_response(self, limit: int = 100, offset: int = 0) -> Response
             HTTPStatusError: if the response status code is not 200.
         """
         pagination_params: dict[str, int] = {"limit": limit, "offset": offset}
-        return self.http_client.request("get", self.build_url(pagination_params))
+        return self.http_client.request("get", self.build_path(pagination_params))
 
     def _resource_do_request(  # noqa: WPS211
         self,
@@ -111,7 +111,7 @@ def _resource_do_request(  # noqa: WPS211
         Raises:
             HTTPError: If the action fails.
         """
-        resource_url = urljoin(f"{self.endpoint}/", resource_id)
+        resource_url = urljoin(f"{self.path}/", resource_id)
         url = urljoin(f"{resource_url}/", action) if action else resource_url
         return self.http_client.request(
             method, url, json=json, query_params=query_params, headers=headers

mpt_api_client/resources/notifications/batches.py

@@ -49,7 +49,7 @@ def create(
                 "application/json",
             )
 
-        response = self.http_client.request("post", self.endpoint, files=files)
+        response = self.http_client.request("post", self.path, files=files)
         return self._model_class.from_response(response)
 
     def get_batch_attachment(self, batch_id: str, attachment_id: str) -> FileModel:
@@ -63,7 +63,7 @@ def get_batch_attachment(self, batch_id: str, attachment_id: str) -> FileModel:
             FileModel containing the attachment.
         """
         response = self.http_client.request(
-            "get", f"{self.endpoint}/{batch_id}/attachments/{attachment_id}"
+            "get", f"{self.path}/{batch_id}/attachments/{attachment_id}"
         )
 
         return FileModel(response)
@@ -101,7 +101,7 @@ async def create(
                 "application/json",
             )
 
-        response = await self.http_client.request("post", self.endpoint, files=files)
+        response = await self.http_client.request("post", self.path, files=files)
         return self._model_class.from_response(response)
 
     async def get_batch_attachment(self, batch_id: str, attachment_id: str) -> FileModel:
@@ -115,6 +115,6 @@ async def get_batch_attachment(self, batch_id: str, attachment_id: str) -> FileM
             FileModel containing the attachment.
         """
         response = await self.http_client.request(
-            "get", f"{self.endpoint}/{batch_id}/attachments/{attachment_id}"
+            "get", f"{self.path}/{batch_id}/attachments/{attachment_id}"
         )
         return FileModel(response)

tests/http/test_async_service.py

@@ -3,6 +3,7 @@
 import respx
 
 from mpt_api_client.exceptions import MPTAPIError
+from mpt_api_client.http.query_state import QueryState
 from tests.http.conftest import AsyncDummyService
 
 
@@ -96,22 +97,22 @@ async def test_async_fetch_page_with_filter(
 
 
 def test_async_init_defaults(async_dummy_service):
-    assert async_dummy_service.query_rql is None
-    assert async_dummy_service.query_order_by is None
-    assert async_dummy_service.query_select is None
-    assert async_dummy_service.build_url() == "/api/v1/test"
+    assert async_dummy_service.query_state.filter is None
+    assert async_dummy_service.query_state.order_by is None
+    assert async_dummy_service.query_state.select is None
+    assert async_dummy_service.build_path() == "/api/v1/test"
 
 
 def test_async_init_with_filter(async_http_client, filter_status_active):
     collection_client = AsyncDummyService(
         http_client=async_http_client,
-        query_rql=filter_status_active,
+        query_state=QueryState(rql=filter_status_active),
     )
 
-    assert collection_client.query_rql == filter_status_active
-    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)"
+    assert collection_client.query_state.filter == filter_status_active
+    assert collection_client.query_state.order_by is None
+    assert collection_client.query_state.select is None
+    assert collection_client.build_path() == "/api/v1/test?eq(status,active)"
 
 
 async def test_async_iterate_single_page(async_dummy_service, single_page_response):