refactor: the query method can use ResponseParameters

Author: azmeuk

doc/changelog.rst

@@ -1,6 +1,16 @@
 Changelog
 =========
 
+[0.7.4] - Unreleased
+--------------------
+
+Changed
+^^^^^^^
+- The ``query`` method now accepts :class:`~scim2_models.ResponseParameters` in addition
+  to :class:`~scim2_models.SearchRequest`.
+- The ``search_request`` parameter of ``query`` is renamed to ``query_parameters``.
+  The old name is deprecated and will be removed in 0.9.
+
 [0.7.3] - 2026-02-04
 --------------------
 

pyproject.toml

@@ -27,7 +27,7 @@ classifiers = [
 
 requires-python = ">= 3.10"
 dependencies = [
-    "scim2-models>=0.6.4",
+    "scim2-models>=0.6.7",
 ]
 
 [project.optional-dependencies]

scim2_client/client.py

@@ -1,5 +1,6 @@
 import asyncio
 import sys
+import warnings
 from collections.abc import Collection
 from dataclasses import dataclass
 from typing import TypeVar
@@ -14,6 +15,7 @@
 from scim2_models import PatchOp
 from scim2_models import Resource
 from scim2_models import ResourceType
+from scim2_models import ResponseParameters
 from scim2_models import Schema
 from scim2_models import SearchRequest
 from scim2_models import ServiceProviderConfig
@@ -400,11 +402,26 @@ def _prepare_query_request(
         self,
         resource_model: type[Resource] | None = None,
         id: str | None = None,
-        search_request: SearchRequest | dict | None = None,
+        query_parameters: ResponseParameters | dict | None = None,
         check_request_payload: bool | None = None,
         expected_status_codes: list[int] | None = None,
         **kwargs,
     ) -> RequestPayload:
+        if "search_request" in kwargs:
+            if query_parameters is not None:
+                raise TypeError(
+                    "Cannot pass both 'query_parameters' and "
+                    "deprecated 'search_request'"
+                )
+            warnings.warn(
+                "The 'search_request' parameter of 'query' is deprecated, "
+                "use 'query_parameters' instead. "
+                "Will be removed in 0.9.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+            query_parameters = kwargs.pop("search_request")
+
         req = RequestPayload(
             expected_status_codes=expected_status_codes,
             request_kwargs=kwargs,
@@ -416,17 +433,23 @@ def _prepare_query_request(
         if resource_model and check_request_payload:
             self._check_resource_model(resource_model)
 
-        payload: SearchRequest | None
+        payload: ResponseParameters | None
         if not check_request_payload:
-            payload = search_request
+            payload = query_parameters
 
-        elif isinstance(search_request, SearchRequest):
-            payload = search_request.model_dump(
+        elif isinstance(query_parameters, SearchRequest):
+            payload = query_parameters.model_dump(
                 exclude_unset=True,
                 exclude={"schemas"},
                 scim_ctx=Context.RESOURCE_QUERY_REQUEST,
             )
 
+        elif isinstance(query_parameters, ResponseParameters):
+            payload = query_parameters.model_dump(
+                exclude_unset=True,
+                by_alias=True,
+            )
+
         else:
             payload = None
 
@@ -703,7 +726,7 @@ def query(
         self,
         resource_model: type[Resource] | None = None,
         id: str | None = None,
-        search_request: SearchRequest | dict | None = None,
+        query_parameters: ResponseParameters | dict | None = None,
         check_request_payload: bool | None = None,
         check_response_payload: bool | None = None,
         expected_status_codes: list[int]
@@ -718,7 +741,14 @@ def query(
 
         :param resource_model: A :class:`~scim2_models.Resource` subtype or :data:`None`
         :param id: The SCIM id of an object to get, or :data:`None`
-        :param search_request: An object detailing the search query parameters.
+        :param query_parameters: A :class:`~scim2_models.ResponseParameters` or
+            :class:`~scim2_models.SearchRequest` detailing the query parameters.
+            Use :class:`~scim2_models.ResponseParameters` when querying a single
+            resource by id, where only ``attributes`` and ``excludedAttributes``
+            are meaningful (:rfc:`RFC 7644 §3.4.1 <7644#section-3.4.1>`).
+            Use :class:`~scim2_models.SearchRequest` when listing resources, to
+            also pass ``filter``, ``sortBy``, ``sortOrder``, ``startIndex`` and
+            ``count`` (:rfc:`RFC 7644 §3.4.2 <7644#section-3.4.2>`).
         :param check_request_payload: If set, overwrites :paramref:`scim2_client.SCIMClient.check_request_payload`.
         :param check_response_payload: If set, overwrites :paramref:`scim2_client.SCIMClient.check_response_payload`.
         :param expected_status_codes: The list of expected status codes form the response.
@@ -752,13 +782,13 @@ def query(
             from scim2_models import User, SearchRequest
 
             req = SearchRequest(filter='userName sw "john"')
-            response = scim.query(User, search_request=search_request)
+            response = scim.query(User, query_parameters=req)
             # 'response' may be a ListResponse[User] or an Error object
 
         .. code-block:: python
             :caption: Query of all the available resources
 
-            from scim2_models import User, SearchRequest
+            from scim2_models import User
 
             response = scim.query()
             # 'response' may be a ListResponse[Union[User, Group, ...]] or an Error object
@@ -1030,7 +1060,7 @@ async def query(
         self,
         resource_model: type[Resource] | None = None,
         id: str | None = None,
-        search_request: SearchRequest | dict | None = None,
+        query_parameters: ResponseParameters | dict | None = None,
         check_request_payload: bool | None = None,
         check_response_payload: bool | None = None,
         expected_status_codes: list[int]
@@ -1045,7 +1075,14 @@ async def query(
 
         :param resource_model: A :class:`~scim2_models.Resource` subtype or :data:`None`
         :param id: The SCIM id of an object to get, or :data:`None`
-        :param search_request: An object detailing the search query parameters.
+        :param query_parameters: A :class:`~scim2_models.ResponseParameters` or
+            :class:`~scim2_models.SearchRequest` detailing the query parameters.
+            Use :class:`~scim2_models.ResponseParameters` when querying a single
+            resource by id, where only ``attributes`` and ``excludedAttributes``
+            are meaningful (:rfc:`RFC 7644 §3.4.1 <7644#section-3.4.1>`).
+            Use :class:`~scim2_models.SearchRequest` when listing resources, to
+            also pass ``filter``, ``sortBy``, ``sortOrder``, ``startIndex`` and
+            ``count`` (:rfc:`RFC 7644 §3.4.2 <7644#section-3.4.2>`).
         :param check_request_payload: If set, overwrites :paramref:`scim2_client.SCIMClient.check_request_payload`.
         :param check_response_payload: If set, overwrites :paramref:`scim2_client.SCIMClient.check_response_payload`.
         :param expected_status_codes: The list of expected status codes form the response.
@@ -1079,13 +1116,13 @@ async def query(
             from scim2_models import User, SearchRequest
 
             req = SearchRequest(filter='userName sw "john"')
-            response = scim.query(User, search_request=search_request)
+            response = scim.query(User, query_parameters=req)
             # 'response' may be a ListResponse[User] or an Error object
 
         .. code-block:: python
             :caption: Query of all the available resources
 
-            from scim2_models import User, SearchRequest
+            from scim2_models import User
 
             response = scim.query()
             # 'response' may be a ListResponse[Union[User, Group, ...]] or an Error object

scim2_client/engines/httpx.py

@@ -13,6 +13,7 @@
 from scim2_models import ListResponse
 from scim2_models import PatchOp
 from scim2_models import Resource
+from scim2_models import ResponseParameters
 from scim2_models import SearchRequest
 
 from scim2_client.client import BaseAsyncSCIMClient
@@ -105,7 +106,7 @@ def query(
         self,
         resource_model: type[Resource] | None = None,
         id: str | None = None,
-        search_request: SearchRequest | dict | None = None,
+        query_parameters: ResponseParameters | dict | None = None,
         check_request_payload: bool | None = None,
         check_response_payload: bool | None = None,
         expected_status_codes: list[int]
@@ -116,7 +117,7 @@ def query(
         req = self._prepare_query_request(
             resource_model=resource_model,
             id=id,
-            search_request=search_request,
+            query_parameters=query_parameters,
             check_request_payload=check_request_payload,
             expected_status_codes=expected_status_codes,
             **kwargs,
@@ -331,7 +332,7 @@ async def query(
         self,
         resource_model: type[Resource] | None = None,
         id: str | None = None,
-        search_request: SearchRequest | dict | None = None,
+        query_parameters: ResponseParameters | dict | None = None,
         check_request_payload: bool | None = None,
         check_response_payload: bool | None = None,
         expected_status_codes: list[int]
@@ -342,7 +343,7 @@ async def query(
         req = self._prepare_query_request(
             resource_model=resource_model,
             id=id,
-            search_request=search_request,
+            query_parameters=query_parameters,
             check_request_payload=check_request_payload,
             expected_status_codes=expected_status_codes,
             **kwargs,

scim2_client/engines/werkzeug.py

@@ -9,6 +9,7 @@
 from scim2_models import ListResponse
 from scim2_models import PatchOp
 from scim2_models import Resource
+from scim2_models import ResponseParameters
 from scim2_models import SearchRequest
 from werkzeug.test import Client
 
@@ -139,7 +140,7 @@ def query(
         self,
         resource_model: type[Resource] | None = None,
         id: str | None = None,
-        search_request: SearchRequest | dict | None = None,
+        query_parameters: ResponseParameters | dict | None = None,
         check_request_payload: bool | None = None,
         check_response_payload: bool | None = None,
         expected_status_codes: list[int]
@@ -150,7 +151,7 @@ def query(
         req = self._prepare_query_request(
             resource_model=resource_model,
             id=id,
-            search_request=search_request,
+            query_parameters=query_parameters,
             check_request_payload=check_request_payload,
             expected_status_codes=expected_status_codes,
             **kwargs,

tests/test_query.py

@@ -7,6 +7,7 @@
 from scim2_models import Meta
 from scim2_models import Resource
 from scim2_models import ResourceType
+from scim2_models import ResponseParameters
 from scim2_models import SearchRequest
 from scim2_models import ServiceProviderConfig
 from scim2_models import User
@@ -555,8 +556,35 @@ def test_search_request(httpserver, sync_client):
     assert response.id == "with-qs"
 
 
+def test_query_parameters(httpserver, sync_client):
+    """ResponseParameters can be used instead of SearchRequest for single-resource queries."""
+    query_string = "attributes=userName&attributes=displayName"
+
+    httpserver.expect_request(
+        "/Users/with-rp", query_string=query_string
+    ).respond_with_json(
+        {
+            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
+            "id": "with-rp",
+            "userName": "bjensen@example.com",
+            "meta": {
+                "resourceType": "User",
+                "created": "2010-01-23T04:56:22Z",
+                "lastModified": "2011-05-13T04:42:34Z",
+                "version": 'W\\/"3694e05e9dff590"',
+                "location": "https://example.com/v2/Users/with-rp",
+            },
+        },
+        status=200,
+    )
+    params = ResponseParameters(attributes=["userName", "displayName"])
+    response = sync_client.query(User, "with-rp", params)
+    assert isinstance(response, User)
+    assert response.id == "with-rp"
+
+
 def test_query_dont_check_request_payload(httpserver, sync_client):
-    """Test the check_request_payload attribute on query."""
+    """Raw dict payloads are forwarded as-is when check_request_payload is False."""
     query_string = "attributes=userName&attributes=displayName&excluded_attributes=timezone&excluded_attributes=phoneNumbers&filter=userName+Eq+%22john%22&sort_by=userName&sort_order=ascending&start_index=1&count=10"
 
     httpserver.expect_request(
@@ -591,6 +619,41 @@ def test_query_dont_check_request_payload(httpserver, sync_client):
     assert response.id == "with-qs"
 
 
+def test_deprecated_search_request_keyword(httpserver, sync_client):
+    """Passing search_request as keyword argument emits a DeprecationWarning."""
+    query_string = "attributes=userName"
+
+    httpserver.expect_request(
+        "/Users/with-dep", query_string=query_string
+    ).respond_with_json(
+        {
+            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
+            "id": "with-dep",
+            "userName": "bjensen@example.com",
+            "meta": {
+                "resourceType": "User",
+                "created": "2010-01-23T04:56:22Z",
+                "lastModified": "2011-05-13T04:42:34Z",
+                "version": 'W\\/"3694e05e9dff590"',
+                "location": "https://example.com/v2/Users/with-dep",
+            },
+        },
+        status=200,
+    )
+    params = ResponseParameters(attributes=["userName"])
+    with pytest.warns(DeprecationWarning, match="search_request.*deprecated"):
+        response = sync_client.query(User, "with-dep", search_request=params)
+    assert isinstance(response, User)
+    assert response.id == "with-dep"
+
+
+def test_both_search_request_and_query_parameters_raises(sync_client):
+    """Passing both search_request and query_parameters raises TypeError."""
+    params = ResponseParameters(attributes=["userName"])
+    with pytest.raises(TypeError, match="Cannot pass both"):
+        sync_client.query(User, "some-id", params, search_request=params)
+
+
 def test_invalid_resource_model(sync_client):
     """Test that resource_models passed to the method must be part of SCIMClient.resource_models."""
     sync_client.resource_models = (User,)