[MPT-18938] Added render() as queryable mixin (#226)

This pull request introduces support for a new `render()` query
parameter in the API client, allowing users to request rendered output
in their queries. The implementation includes updates to the core
query-building logic, a new method for chaining `render()` into queries,
and comprehensive tests to ensure correctness.

Enhancements to query parameter handling:

* Added a `with_render` boolean option to the `QueryState` class,
allowing the inclusion of the `render()` parameter in the query string
when building API requests. (`mpt_api_client/http/query_state.py`)
[[1]](diffhunk://#diff-1d40a2820baa57fd0d1a32181811a6269490c4ebe0d01a81e2092753e230a035R20-R34)
[[2]](diffhunk://#diff-1d40a2820baa57fd0d1a32181811a6269490c4ebe0d01a81e2092753e230a035R51-R55)
[[3]](diffhunk://#diff-1d40a2820baa57fd0d1a32181811a6269490c4ebe0d01a81e2092753e230a035R78-R84)
* Introduced the `with_render()` method in `QueryableMixin`, enabling
method chaining to easily add the `render()` parameter to queries.
(`mpt_api_client/http/mixins/queryable_mixin.py`)

Testing and validation:

* Added end-to-end tests for both async and sync clients to verify that
records returned with `render()` do not contain template characters and
that the correct object is returned.
(`tests/e2e/audit/records/test_async_records.py`,
`tests/e2e/audit/records/test_sync_records.py`)
[[1]](diffhunk://#diff-d5824e2487473d7b2d7b6d429cb542a344a8e292af159e30c2db414e273507c4R45-R55)
[[2]](diffhunk://#diff-485960b9be8eac93a315313579525f281be8ed7106f8364dfb5ce40c83e43f11R46-R56)
* Created unit tests for the new `with_render()` method and for query
string building with and without `render()`.
(`tests/unit/http/mixins/test_queryable_mixin.py`,
`tests/unit/http/test_query_state.py`)
[[1]](diffhunk://#diff-e42182fb74793b73637a4e1d86903f0c68b5bc2ab85edb80c2d8cb413df329a6R81-R88)
[[2]](diffhunk://#diff-1e8de208c42e77b791fcd52302bf69b5cb1cbd4107cc40e320015c08425b0964R26)
[[3]](diffhunk://#diff-1e8de208c42e77b791fcd52302bf69b5cb1cbd4107cc40e320015c08425b0964R38-R55)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
Closes [MPT-18938](https://softwareone.atlassian.net/browse/MPT-18938)

- Add support for requesting rendered output via a render() query
parameter
- Extend QueryState with a with_render flag/property; QueryState.build()
appends render() when enabled
- Add with_render() to QueryableMixin to enable chaining render() into
queries and propagate the flag through filter/order_by/select
- Add unit tests for QueryState.with_render and QueryableMixin chaining
behavior
- Add sync and async end-to-end tests verifying rendered records contain
no template delimiters and return the expected objects
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

[MPT-18938]:
https://softwareone.atlassian.net/browse/MPT-18938?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Author: robcsegal

mpt_api_client/http/mixins/queryable_mixin.py

@@ -23,6 +23,7 @@ def order_by(self, *fields: str) -> Self:
                 rql=self.query_state.filter,  # type: ignore[attr-defined]
                 order_by=list(fields),
                 select=self.query_state.select,  # type: ignore[attr-defined]
+                render=self.query_state.render,  # type: ignore[attr-defined]
             )
         )
 
@@ -39,6 +40,7 @@ def filter(self, rql: RQLQuery) -> Self:
                 rql=combined_filter,
                 order_by=self.query_state.order_by,  # type: ignore[attr-defined]
                 select=self.query_state.select,  # type: ignore[attr-defined]
+                render=self.query_state.render,  # type: ignore[attr-defined]
             )
         )
 
@@ -60,6 +62,22 @@ def select(self, *fields: str) -> Self:
                 rql=self.query_state.filter,  # type: ignore[attr-defined]
                 order_by=self.query_state.order_by,  # type: ignore[attr-defined]
                 select=list(fields),
+                render=self.query_state.render,  # type: ignore[attr-defined]
+            ),
+        )
+
+    def options(self, *, render: bool = False) -> Self:
+        """Set query options.
+
+        Returns:
+            New copy of the collection with the given options applied.
+        """
+        return self._create_new_instance(
+            QueryState(
+                rql=self.query_state.filter,  # type: ignore[attr-defined]
+                order_by=self.query_state.order_by,  # type: ignore[attr-defined]
+                select=self.query_state.select,  # type: ignore[attr-defined]
+                render=render,
             ),
         )
 

mpt_api_client/http/query_state.py

@@ -17,17 +17,21 @@ def __init__(
         rql: RQLQuery | None = None,
         order_by: list[str] | None = None,
         select: list[str] | None = None,
+        *,
+        render: bool = False,
     ) -> 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.
+            render: Whether to include the render() parameter in the query string.
         """
         self._filter = rql
         self._order_by = order_by
         self._select = select
+        self._render = render
 
     @property
     def filter(self) -> RQLQuery | None:
@@ -44,6 +48,11 @@ def select(self) -> list[str] | None:
         """Get the current select fields."""
         return self._select
 
+    @property
+    def render(self) -> bool:
+        """Get the current render state."""
+        return self._render
+
     def build(self, query_params: dict[str, Any] | None = None) -> str:
         """Build a query string from the current state and additional parameters.
 
@@ -66,7 +75,11 @@ def build(self, query_params: dict[str, Any] | None = None) -> str:
         if self._filter:
             query_parts.append(str(self._filter))
 
+        if self._render:
+            query_parts.append("render()")
+
         if query_parts:
             query = "&".join(query_parts)
             return f"{query}"
+
         return ""

tests/e2e/audit/records/test_async_records.py

@@ -42,3 +42,15 @@ async def test_get_record_not_found(async_mpt_vendor: AsyncMPTClient) -> None:
 
     with pytest.raises(MPTAPIError):
         await service.get("REC-000-000-000")
+
+
+async def test_get_records_with_render(async_mpt_vendor: AsyncMPTClient, product_id: str) -> None:
+    template_chars = ["{{", "}}"]
+    audit_filter = RQLQuery(object__id=product_id)
+    service = async_mpt_vendor.audit.records.filter(audit_filter).options(render=True)
+    records = [record async for record in service.iterate()]
+
+    assert records
+    for record in records:
+        assert record.object.id == product_id
+        assert not any(char in record.details for char in template_chars)

tests/e2e/audit/records/test_sync_records.py

@@ -43,3 +43,16 @@ def test_get_record_not_found(mpt_vendor: MPTClient) -> None:
 
     with pytest.raises(MPTAPIError):
         service.get("REC-000-000-000")
+
+
+def test_get_records_with_render(mpt_vendor: MPTClient, product_id) -> None:
+    template_chars = ["{{", "}}"]
+    audit_filter = RQLQuery(object__id=product_id)
+    service = mpt_vendor.audit.records.filter(audit_filter).options(render=True)
+
+    result = list(service.iterate())
+
+    assert result
+    for record in result:
+        assert record.object.id == product_id
+        assert not any(char in record.details for char in template_chars)

tests/unit/http/mixins/test_queryable_mixin.py

@@ -78,3 +78,12 @@ def test_queryable_mixin_method_chaining(
     assert result.query_state.filter == filter_status_active
     assert result.query_state.order_by == ["created", "-name"]
     assert result.query_state.select == ["id", "name"]
+
+
+def test_queryable_mixin_options_render(dummy_service: DummyService) -> None:
+    result = dummy_service.options(render=True)
+
+    assert result != dummy_service
+    assert not dummy_service.query_state.render
+    assert result.query_state.render
+    assert result.select("id").query_state.render

tests/unit/http/test_query_state.py

@@ -23,6 +23,7 @@ def test_build_url(filter_status_active):
         rql=filter_status_active,
         select=["-audit", "product.agreements", "-product.agreements.product"],
         order_by=["-created", "name"],
+        render=False,
     )
 
     result = query_state.build()
@@ -34,6 +35,24 @@ def test_build_url(filter_status_active):
     )
 
 
+def test_build_url_with_render(filter_status_active):
+    query_state = QueryState(
+        rql=filter_status_active,
+        select=["-audit", "product.agreements", "-product.agreements.product"],
+        order_by=["-created", "name"],
+        render=True,
+    )
+
+    result = query_state.build()
+
+    assert result == (
+        "order=-created,name"
+        "&select=-audit,product.agreements,-product.agreements.product"
+        "&eq(status,'active')"
+        "&render()"
+    )
+
+
 def test_empty_build(query_state):
     result = query_state.build()