feat: add a request method to send raw HTTP requests

Author: azmeuk

doc/changelog.rst

@@ -11,6 +11,9 @@ Added
   When the server advertises cursor pagination, a response without ``totalResults`` is accepted.
   A response with an invalid ``nextCursor`` or ``previousCursor`` raises
   :class:`~scim2_client.ResponsePayloadValidationException`.
+- The ``request`` method sends a raw request and returns the response of the HTTP library,
+  without any SCIM processing. This helps to check how a server behaves,
+  for instance with an unsupported HTTP method.
 
 Changed
 ^^^^^^^

doc/conf.py

@@ -64,6 +64,8 @@
     ("py:class", "scim2_client.client.ResourceT"),
     ("py:class", "scim2_client.engines.httpx2.ResourceT"),
     ("py:class", "scim2_client.engines.werkzeug.ResourceT"),
+    # The httpx2 inventory does not publish its Response class.
+    ("py:class", "httpx2.Response"),
 ]
 
 # -- Sibling projects ------------------------------------------------------

doc/reference.rst

@@ -41,6 +41,9 @@ here as class attributes.
 .. autoclass:: scim2_client.client.ResponseHeaders
    :members:
 
+.. autoclass:: scim2_client.client.RawResponse
+   :members:
+
 Errors
 ------
 

scim2_client/client.py

@@ -77,6 +77,22 @@ class ResponseHeaders(Protocol):
     def get(self, key: str, /) -> str | None: ...
 
 
+class RawResponse(Protocol):
+    """A response as returned by the HTTP library of an engine."""
+
+    @property
+    def status_code(self) -> int:
+        """The HTTP status code."""
+
+    @property
+    def headers(self) -> ResponseHeaders:
+        """The HTTP headers."""
+
+    @property
+    def text(self) -> str:
+        """The body, decoded as text."""
+
+
 def describe_resource_models(
     resource_models: Collection[type[Resource[Any]]],
 ) -> tuple[tuple[DescribedModel, ...], tuple[ResourceType, ...]]:
@@ -1776,6 +1792,29 @@ def discover(
             discovered_schemas, discovered_resource_types, config
         )
 
+    def request(self, method: str, url: str, **kwargs: Any) -> RawResponse:
+        """Send a request to the server, without any SCIM processing.
+
+        Neither the request nor the response is checked, so this is fitted to
+        observe how the server behaves, for instance with an unsupported HTTP method.
+
+        :param method: The HTTP method.
+        :param url: The URL, relative to the SCIM server base URL.
+        :param kwargs: Additional parameters passed to the underlying
+            HTTP request library.
+        :return: The response of the underlying HTTP request library.
+        :raises ~scim2_client.RequestNetworkException: When the request cannot be sent.
+
+        :usage:
+
+        .. code-block:: python
+            :caption: Checking that the ``/Schemas`` endpoint refuses ``DELETE``
+
+            response = scim.request("DELETE", "/Schemas")
+            assert response.status_code == 405
+        """
+        raise NotImplementedError()
+
 
 class BaseAsyncSCIMClient(SCIMClient):
     """Base class for asynchronous request clients."""
@@ -2275,3 +2314,26 @@ async def discover(
         self.provider = self._describe_service(
             discovered_schemas, discovered_resource_types, config
         )
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> RawResponse:
+        """Send a request to the server, without any SCIM processing.
+
+        Neither the request nor the response is checked, so this is fitted to
+        observe how the server behaves, for instance with an unsupported HTTP method.
+
+        :param method: The HTTP method.
+        :param url: The URL, relative to the SCIM server base URL.
+        :param kwargs: Additional parameters passed to the underlying
+            HTTP request library.
+        :return: The response of the underlying HTTP request library.
+        :raises ~scim2_client.RequestNetworkException: When the request cannot be sent.
+
+        :usage:
+
+        .. code-block:: python
+            :caption: Checking that the ``/Schemas`` endpoint refuses ``DELETE``
+
+            response = await scim.request("DELETE", "/Schemas")
+            assert response.status_code == 405
+        """
+        raise NotImplementedError()

scim2_client/engines/httpx2.py

@@ -364,6 +364,10 @@ def modify(
                 ),
             )
 
+    def request(self, method: str, url: str, **kwargs: Any) -> Response:
+        with handle_request_error():
+            return self.client.request(method, url, **kwargs)
+
 
 class AsyncSCIMClient(BaseAsyncSCIMClient):
     """Perform SCIM requests over the network and validate responses.
@@ -655,3 +659,7 @@ async def modify(
                     scim_ctx=Context.RESOURCE_PATCH_RESPONSE,
                 ),
             )
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> Response:
+        with handle_request_error():
+            return await self.client.request(method, url, **kwargs)

scim2_client/engines/werkzeug.py

@@ -382,3 +382,7 @@ def modify(
                     scim_ctx=Context.RESOURCE_PATCH_RESPONSE,
                 ),
             )
+
+    def request(self, method: str, url: str, **kwargs: Any) -> TestResponse:
+        environ = {**self.environ, **kwargs}
+        return self.client.open(self._make_url(url), method=method, **environ)

tests/engines/test_httpx2.py

@@ -11,6 +11,7 @@
 from scim2_models import SearchRequest
 from scim2_models import ServiceProviderConfig
 
+from scim2_client import RequestNetworkException
 from scim2_client.engines.httpx2 import AsyncClient
 from scim2_client.engines.httpx2 import AsyncSCIMClient
 from scim2_client.engines.httpx2 import Client
@@ -186,3 +187,41 @@ async def test_async_engine(server):
     assert operation.bulk_id == "qwerty"
     created_user = await scim_client.query(User, operation.location.rsplit("/", 1)[-1])
     assert created_user.user_name == "Bob"
+
+
+def test_sync_engine_request(server):
+    """A raw request reaches the server and returns its response as is."""
+    host, port = server
+    client = Client(base_url=f"http://{host}:{port}")
+    scim_client = SyncSCIMClient(client)
+
+    response = scim_client.request("DELETE", "/Schemas")
+
+    assert response.status_code == 405
+
+
+async def test_async_engine_request(server):
+    """A raw asynchronous request reaches the server and returns its response as is."""
+    host, port = server
+    client = AsyncClient(base_url=f"http://{host}:{port}")
+    scim_client = AsyncSCIMClient(client)
+
+    response = await scim_client.request("DELETE", "/Schemas")
+
+    assert response.status_code == 405
+
+
+def test_sync_engine_request_network_error():
+    """A raw request that cannot be sent raises RequestNetworkException."""
+    scim_client = SyncSCIMClient(Client(base_url="http://invalid.test"))
+
+    with pytest.raises(RequestNetworkException):
+        scim_client.request("GET", "/Schemas")
+
+
+async def test_async_engine_request_network_error():
+    """A raw asynchronous request that cannot be sent raises RequestNetworkException."""
+    scim_client = AsyncSCIMClient(AsyncClient(base_url="http://invalid.test"))
+
+    with pytest.raises(RequestNetworkException):
+        await scim_client.request("GET", "/Schemas")

tests/engines/test_werkzeug.py

@@ -154,3 +154,31 @@ def application(request):
         provider=ScimProvider(models=[User]),
     )
     scim_client.query(url="/Users")
+
+
+def test_request(scim_client):
+    """A raw request reaches the application and returns its response as is."""
+    response = scim_client.request("DELETE", "/Schemas")
+
+    assert response.status_code == 405
+
+
+def test_request_with_prefix_and_environ():
+    """A raw request is sent under the SCIM prefix, with the client environ."""
+
+    @Request.application
+    def application(request):
+        return Response(
+            f"{request.method} {request.path} {request.headers['X-Test']}", status=405
+        )
+
+    scim_client = TestSCIMClient(
+        client=Client(application),
+        environ={"headers": {"X-Test": "foobar"}},
+        scim_prefix="/scim/v2",
+    )
+
+    response = scim_client.request("DELETE", "/Schemas")
+
+    assert response.status_code == 405
+    assert response.text == "DELETE /scim/v2/Schemas foobar"