scim2-client 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

scim2_client/client.py

@@ -1,12 +1,8 @@
-import json
-import json.decoder
 import sys
+from dataclasses import dataclass
 from typing import Optional
 from typing import Union
 
-from httpx import Client
-from httpx import RequestError
-from httpx import Response
 from pydantic import ValidationError
 from scim2_models import AnyResource
 from scim2_models import Context
@@ -19,16 +15,14 @@ from scim2_models import Schema
 from scim2_models import SearchRequest
 from scim2_models import ServiceProviderConfig
 
-from .errors import RequestNetworkError
-from .errors import RequestPayloadValidationError
-from .errors import ResponsePayloadValidationError
-from .errors import SCIMClientError
-from .errors import SCIMRequestError
-from .errors import SCIMResponseError
-from .errors import SCIMResponseErrorObject
-from .errors import UnexpectedContentFormat
-from .errors import UnexpectedContentType
-from .errors import UnexpectedStatusCode
+from scim2_client.errors import RequestPayloadValidationError
+from scim2_client.errors import ResponsePayloadValidationError
+from scim2_client.errors import SCIMClientError
+from scim2_client.errors import SCIMRequestError
+from scim2_client.errors import SCIMResponseError
+from scim2_client.errors import SCIMResponseErrorObject
+from scim2_client.errors import UnexpectedContentType
+from scim2_client.errors import UnexpectedStatusCode
 
 BASE_HEADERS = {
     "Accept": "application/scim+json",
@@ -36,11 +30,23 @@ BASE_HEADERS = {
 }
 
 
-class SCIMClient:
-    """An object that perform SCIM requests and validate responses.
+@dataclass
+class RequestPayload:
+    request_kwargs: dict
+    url: Optional[str] = None
+    payload: Optional[dict] = None
+    expected_types: Optional[list[type[Resource]]] = None
+    expected_status_codes: Optional[list[int]] = None
 
-    :param client: A :class:`httpx.Client` instance that will be used to send requests.
-    :param resource_types: A tuple of :class:`~scim2_models.Resource` types expected to be handled by the SCIMClient.
+
+class BaseSCIMClient:
+    """The base model for request clients.
+
+    It goal is to parse the requests and responses and check if they comply with the SCIM specifications.
+
+    This class can be inherited and used as a basis for request engine integration.
+
+    :param resource_models: A tuple of :class:`~scim2_models.Resource` types expected to be handled by the SCIM client.
         If a request payload describe a resource that is not in this list, an exception will be raised.
 
     .. note::
@@ -128,42 +134,47 @@ class SCIMClient:
     :rfc:`RFC7644 §3.12 <7644#section-3.12>`.
     """
 
-    def __init__(self, client: Client, resource_types: Optional[tuple[type]] = None):
-        self.client = client
-        self.resource_types = tuple(
-            set(resource_types or []) | {ResourceType, Schema, ServiceProviderConfig}
+    def __init__(self, resource_models: Optional[tuple[type[Resource]]] = None):
+        self.resource_models = tuple(
+            set(resource_models or []) | {ResourceType, Schema, ServiceProviderConfig}
         )
 
-    def check_resource_type(self, resource_type):
-        if resource_type not in self.resource_types:
-            raise SCIMRequestError(f"Unknown resource type: '{resource_type}'")
+    def check_resource_model(
+        self, resource_model: type[Resource], payload=None
+    ) -> None:
+        if resource_model not in self.resource_models:
+            raise SCIMRequestError(
+                f"Unknown resource type: '{resource_model}'", source=payload
+            )
 
-    def resource_endpoint(self, resource_type: type):
-        if resource_type is None:
+    def resource_endpoint(self, resource_model: Optional[type[Resource]]) -> str:
+        if resource_model is None:
             return "/"
 
         # This one takes no final 's'
-        if resource_type is ServiceProviderConfig:
+        if resource_model is ServiceProviderConfig:
             return "/ServiceProviderConfig"
 
         try:
-            first_bracket_index = resource_type.__name__.index("[")
-            root_name = resource_type.__name__[:first_bracket_index]
+            first_bracket_index = resource_model.__name__.index("[")
+            root_name = resource_model.__name__[:first_bracket_index]
         except ValueError:
-            root_name = resource_type.__name__
+            root_name = resource_model.__name__
         return f"/{root_name}s"
 
     def check_response(
         self,
-        response: Response,
-        expected_status_codes: list[int],
-        expected_types: Optional[type] = None,
+        payload: Optional[dict],
+        status_code: int,
+        headers: dict,
+        expected_status_codes: Optional[list[int]] = None,
+        expected_types: Optional[list[type[Resource]]] = None,
         check_response_payload: bool = True,
         raise_scim_errors: bool = True,
         scim_ctx: Optional[Context] = None,
-    ):
-        if expected_status_codes and response.status_code not in expected_status_codes:
-            raise UnexpectedStatusCode(source=response)
+    ) -> Union[Error, None, dict, type[Resource]]:
+        if expected_status_codes and status_code not in expected_status_codes:
+            raise UnexpectedStatusCode()
 
         # Interoperability considerations:  The "application/scim+json" media
         # type is intended to identify JSON structure data that conforms to
@@ -171,24 +182,21 @@ class SCIMClient:
         # SCIM are known to informally use "application/json".
         # https://datatracker.ietf.org/doc/html/rfc7644.html#section-8.1
 
-        actual_content_type = response.headers.get("content-type", "").split(";").pop(0)
+        actual_content_type = headers.get("content-type", "").split(";").pop(0)
         expected_response_content_types = ("application/scim+json", "application/json")
         if actual_content_type not in expected_response_content_types:
-            raise UnexpectedContentType(source=response)
+            raise UnexpectedContentType(content_type=actual_content_type)
 
         # In addition to returning an HTTP response code, implementers MUST return
         # the errors in the body of the response in a JSON format
         # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.12
 
         no_content_status_codes = [204, 205]
-        if response.status_code in no_content_status_codes:
+        if status_code in no_content_status_codes:
             response_payload = None
 
         else:
-            try:
-                response_payload = response.json()
-            except json.decoder.JSONDecodeError as exc:
-                raise UnexpectedContentFormat(source=response) from exc
+            response_payload = payload
 
         if not check_response_payload:
             return response_payload
@@ -209,8 +217,8 @@ class SCIMClient:
             expected_types, response_payload, with_extensions=False
         )
 
-        if not actual_type:
-            expected = ", ".join([type.__name__ for type in expected_types])
+        if response_payload and not actual_type:
+            expected = ", ".join([type_.__name__ for type_ in expected_types])
             try:
                 schema = ", ".join(response_payload["schemas"])
                 message = f"Expected type {expected} but got unknown resource with schemas: {schema}"
@@ -219,22 +227,233 @@ class SCIMClient:
                     f"Expected type {expected} but got undefined object with no schema"
                 )
 
-            raise SCIMResponseError(message, source=response)
+            raise SCIMResponseError(message)
 
         try:
             return actual_type.model_validate(response_payload, scim_ctx=scim_ctx)
         except ValidationError as exc:
-            scim_exc = ResponsePayloadValidationError(source=response)
+            scim_exc = ResponsePayloadValidationError()
             if sys.version_info >= (3, 11):  # pragma: no cover
                 scim_exc.add_note(str(exc))
             raise scim_exc from exc
 
+    def prepare_create_request(
+        self,
+        resource: Union[AnyResource, dict],
+        check_request_payload: bool = True,
+        expected_status_codes: Optional[list[int]] = None,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> RequestPayload:
+        req = RequestPayload(
+            expected_status_codes=expected_status_codes,
+            request_kwargs=kwargs,
+        )
+
+        if not check_request_payload:
+            req.payload = resource
+            req.url = req.request_kwargs.pop("url", None)
+
+        else:
+            if isinstance(resource, Resource):
+                resource_model = resource.__class__
+
+            else:
+                resource_model = Resource.get_by_payload(self.resource_models, resource)
+                if not resource_model:
+                    raise SCIMRequestError(
+                        "Cannot guess resource type from the payload"
+                    )
+
+                try:
+                    resource = resource_model.model_validate(resource)
+                except ValidationError as exc:
+                    scim_validation_exc = RequestPayloadValidationError(source=resource)
+                    if sys.version_info >= (3, 11):  # pragma: no cover
+                        scim_validation_exc.add_note(str(exc))
+                    raise scim_validation_exc from exc
+
+            self.check_resource_model(resource_model, resource)
+            req.expected_types = [resource.__class__]
+            req.url = req.request_kwargs.pop(
+                "url", self.resource_endpoint(resource_model)
+            )
+            req.payload = resource.model_dump(
+                scim_ctx=Context.RESOURCE_CREATION_REQUEST
+            )
+
+        return req
+
+    def prepare_query_request(
+        self,
+        resource_model: Optional[type[Resource]] = None,
+        id: Optional[str] = None,
+        search_request: Optional[Union[SearchRequest, dict]] = None,
+        check_request_payload: bool = True,
+        expected_status_codes: Optional[list[int]] = None,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> RequestPayload:
+        req = RequestPayload(
+            expected_status_codes=expected_status_codes,
+            request_kwargs=kwargs,
+        )
+
+        if resource_model and check_request_payload:
+            self.check_resource_model(resource_model)
+
+        payload: Optional[SearchRequest]
+        if not check_request_payload:
+            payload = search_request
+
+        elif isinstance(search_request, SearchRequest):
+            payload = search_request.model_dump(
+                exclude_unset=True,
+                scim_ctx=Context.RESOURCE_QUERY_REQUEST,
+            )
+
+        else:
+            payload = None
+
+        req.payload = payload
+        req.url = req.request_kwargs.pop("url", self.resource_endpoint(resource_model))
+
+        if resource_model is None:
+            req.expected_types = [
+                *self.resource_models,
+                ListResponse[Union[self.resource_models]],
+            ]
+
+        elif resource_model == ServiceProviderConfig:
+            req.expected_types = [resource_model]
+            if id:
+                raise SCIMClientError("ServiceProviderConfig cannot have an id")
+
+        elif id:
+            req.expected_types = [resource_model]
+            req.url = f"{req.url}/{id}"
+
+        else:
+            req.expected_types = [ListResponse[resource_model]]
+
+        return req
+
+    def prepare_search_request(
+        self,
+        search_request: Optional[SearchRequest] = None,
+        check_request_payload: bool = True,
+        expected_status_codes: Optional[list[int]] = None,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> RequestPayload:
+        req = RequestPayload(
+            expected_status_codes=expected_status_codes,
+            request_kwargs=kwargs,
+        )
+
+        if not check_request_payload:
+            req.payload = search_request
+
+        else:
+            req.payload = (
+                search_request.model_dump(
+                    exclude_unset=True, scim_ctx=Context.RESOURCE_QUERY_RESPONSE
+                )
+                if search_request
+                else None
+            )
+
+        req.url = req.request_kwargs.pop("url", "/.search")
+        req.expected_types = [ListResponse[Union[self.resource_models]]]
+        return req
+
+    def prepare_delete_request(
+        self,
+        resource_model: type,
+        id: str,
+        expected_status_codes: Optional[list[int]] = None,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> RequestPayload:
+        req = RequestPayload(
+            expected_status_codes=expected_status_codes,
+            request_kwargs=kwargs,
+        )
+
+        self.check_resource_model(resource_model)
+        delete_url = self.resource_endpoint(resource_model) + f"/{id}"
+        req.url = req.request_kwargs.pop("url", delete_url)
+        return req
+
+    def prepare_replace_request(
+        self,
+        resource: Union[AnyResource, dict],
+        check_request_payload: bool = True,
+        expected_status_codes: Optional[list[int]] = None,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> RequestPayload:
+        req = RequestPayload(
+            expected_status_codes=expected_status_codes,
+            request_kwargs=kwargs,
+        )
+
+        if not check_request_payload:
+            req.payload = resource
+            req.url = kwargs.pop("url", None)
+
+        else:
+            if isinstance(resource, Resource):
+                resource_model = resource.__class__
+
+            else:
+                resource_model = Resource.get_by_payload(self.resource_models, resource)
+                if not resource_model:
+                    raise SCIMRequestError(
+                        "Cannot guess resource type from the payload",
+                        source=resource,
+                    )
+
+                try:
+                    resource = resource_model.model_validate(resource)
+                except ValidationError as exc:
+                    scim_validation_exc = RequestPayloadValidationError(source=resource)
+                    if sys.version_info >= (3, 11):  # pragma: no cover
+                        scim_validation_exc.add_note(str(exc))
+                    raise scim_validation_exc from exc
+
+            self.check_resource_model(resource_model, resource)
+
+            if not resource.id:
+                raise SCIMRequestError("Resource must have an id", source=resource)
+
+            req.expected_types = [resource.__class__]
+            req.payload = resource.model_dump(
+                scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST
+            )
+            req.url = req.request_kwargs.pop(
+                "url", self.resource_endpoint(resource.__class__) + f"/{resource.id}"
+            )
+
+        return req
+
+    def modify(
+        self, resource: Union[AnyResource, dict], op: PatchOp, **kwargs
+    ) -> Optional[Union[AnyResource, dict]]:
+        raise NotImplementedError()
+
+
+class BaseSyncSCIMClient(BaseSCIMClient):
+    """Base class for synchronous request clients."""
+
     def create(
         self,
         resource: Union[AnyResource, dict],
         check_request_payload: bool = True,
         check_response_payload: bool = True,
-        expected_status_codes: Optional[list[int]] = CREATION_RESPONSE_STATUS_CODES,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.CREATION_RESPONSE_STATUS_CODES,
         raise_scim_errors: bool = True,
         **kwargs,
     ) -> Union[AnyResource, Error, dict]:
@@ -275,58 +494,18 @@ class SCIMClient:
             which value will excluded from the request payload, and which values are expected in
             the response payload.
         """
-        if not check_request_payload:
-            payload = resource
-            url = kwargs.pop("url", None)
-
-        else:
-            if isinstance(resource, Resource):
-                resource_type = resource.__class__
-
-            else:
-                resource_type = Resource.get_by_payload(self.resource_types, resource)
-                if not resource_type:
-                    raise SCIMRequestError(
-                        "Cannot guess resource type from the payload"
-                    )
-
-                try:
-                    resource = resource_type.model_validate(resource)
-                except ValidationError as exc:
-                    scim_exc = RequestPayloadValidationError(source=resource)
-                    if sys.version_info >= (3, 11):  # pragma: no cover
-                        scim_exc.add_note(str(exc))
-                    raise scim_exc from exc
-
-            self.check_resource_type(resource_type)
-            url = kwargs.pop("url", self.resource_endpoint(resource_type))
-            payload = resource.model_dump(scim_ctx=Context.RESOURCE_CREATION_REQUEST)
-
-        try:
-            response = self.client.post(url, json=payload, **kwargs)
-        except RequestError as exc:
-            scim_exc = RequestNetworkError(source=payload)
-            if sys.version_info >= (3, 11):  # pragma: no cover
-                scim_exc.add_note(str(exc))
-            raise scim_exc from exc
-
-        return self.check_response(
-            response=response,
-            expected_status_codes=expected_status_codes,
-            expected_types=([resource.__class__] if check_request_payload else None),
-            check_response_payload=check_response_payload,
-            raise_scim_errors=raise_scim_errors,
-            scim_ctx=Context.RESOURCE_CREATION_RESPONSE,
-        )
+        raise NotImplementedError()
 
     def query(
         self,
-        resource_type: Optional[type] = None,
+        resource_model: Optional[type[Resource]] = None,
         id: Optional[str] = None,
         search_request: Optional[Union[SearchRequest, dict]] = None,
         check_request_payload: bool = True,
         check_response_payload: bool = True,
-        expected_status_codes: Optional[list[int]] = QUERY_RESPONSE_STATUS_CODES,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.QUERY_RESPONSE_STATUS_CODES,
         raise_scim_errors: bool = True,
         **kwargs,
     ) -> Union[AnyResource, ListResponse[AnyResource], Error, dict]:
@@ -335,7 +514,7 @@ class SCIMClient:
         - If `id` is not :data:`None`, the resource with the exact id will be reached.
         - If `id` is :data:`None`, all the resources with the given type will be reached.
 
-        :param resource_type: A :class:`~scim2_models.Resource` subtype or :data:`None`
+        :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 check_request_payload: If :data:`False`,
@@ -351,8 +530,8 @@ class SCIMClient:
 
         :return:
             - A :class:`~scim2_models.Error` object in case of error.
-            - A `resource_type` object in case of success if `id` is not :data:`None`
-            - A :class:`~scim2_models.ListResponse[resource_type]` object in case of success if `id` is :data:`None`
+            - A `resource_model` object in case of success if `id` is not :data:`None`
+            - A :class:`~scim2_models.ListResponse[resource_model]` object in case of success if `id` is :data:`None`
 
         .. note::
 
@@ -393,71 +572,22 @@ class SCIMClient:
             which value will excluded from the request payload, and which values are expected in
             the response payload.
         """
-        if resource_type and check_request_payload:
-            self.check_resource_type(resource_type)
-
-        if not check_request_payload:
-            payload = search_request
-
-        else:
-            payload = (
-                search_request.model_dump(
-                    exclude_unset=True,
-                    scim_ctx=Context.RESOURCE_QUERY_REQUEST,
-                )
-                if search_request
-                else None
-            )
-
-        url = kwargs.pop("url", self.resource_endpoint(resource_type))
-
-        if resource_type is None:
-            expected_types = [
-                *self.resource_types,
-                ListResponse[Union[self.resource_types]],
-            ]
-
-        elif resource_type == ServiceProviderConfig:
-            expected_types = [resource_type]
-            if id:
-                raise SCIMClientError("ServiceProviderConfig cannot have an id")
-
-        elif id:
-            expected_types = [resource_type]
-            url = f"{url}/{id}"
-
-        else:
-            expected_types = [ListResponse[resource_type]]
-
-        try:
-            response = self.client.get(url, params=payload, **kwargs)
-        except RequestError as exc:
-            scim_exc = RequestNetworkError(source=payload)
-            if sys.version_info >= (3, 11):  # pragma: no cover
-                scim_exc.add_note(str(exc))
-            raise scim_exc from exc
-
-        return self.check_response(
-            response=response,
-            expected_status_codes=expected_status_codes,
-            expected_types=expected_types,
-            check_response_payload=check_response_payload,
-            raise_scim_errors=raise_scim_errors,
-            scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
-        )
+        raise NotImplementedError()
 
     def search(
         self,
         search_request: Optional[SearchRequest] = None,
         check_request_payload: bool = True,
         check_response_payload: bool = True,
-        expected_status_codes: Optional[list[int]] = SEARCH_RESPONSE_STATUS_CODES,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.SEARCH_RESPONSE_STATUS_CODES,
         raise_scim_errors: bool = True,
         **kwargs,
     ) -> Union[AnyResource, ListResponse[AnyResource], Error, dict]:
         """Perform a POST search request to read all available resources, as defined in :rfc:`RFC7644 §3.4.3 <7644#section-3.4.3>`.
 
-        :param resource_types: Resource type or union of types expected
+        :param resource_models: Resource type or union of types expected
             to be read from the response.
         :param search_request: An object detailing the search query parameters.
         :param check_request_payload: If :data:`False`,
@@ -474,7 +604,7 @@ class SCIMClient:
 
         :return:
             - A :class:`~scim2_models.Error` object in case of error.
-            - A :class:`~scim2_models.ListResponse[resource_type]` object in case of success.
+            - A :class:`~scim2_models.ListResponse[resource_model]` object in case of success.
 
         :usage:
 
@@ -494,49 +624,22 @@ class SCIMClient:
             which value will excluded from the request payload, and which values are expected in
             the response payload.
         """
-        if not check_request_payload:
-            payload = search_request
-
-        else:
-            payload = (
-                search_request.model_dump(
-                    exclude_unset=True, scim_ctx=Context.RESOURCE_QUERY_RESPONSE
-                )
-                if search_request
-                else None
-            )
-
-        url = kwargs.pop("url", "/.search")
-
-        try:
-            response = self.client.post(url, json=payload)
-        except RequestError as exc:
-            scim_exc = RequestNetworkError(source=payload)
-            if sys.version_info >= (3, 11):  # pragma: no cover
-                scim_exc.add_note(str(exc))
-            raise scim_exc from exc
-
-        return self.check_response(
-            response=response,
-            expected_status_codes=expected_status_codes,
-            expected_types=[ListResponse[Union[self.resource_types]]],
-            check_response_payload=check_response_payload,
-            raise_scim_errors=raise_scim_errors,
-            scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
-        )
+        raise NotImplementedError()
 
     def delete(
         self,
-        resource_type: type,
+        resource_model: type,
         id: str,
         check_response_payload: bool = True,
-        expected_status_codes: Optional[list[int]] = DELETION_RESPONSE_STATUS_CODES,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.DELETION_RESPONSE_STATUS_CODES,
         raise_scim_errors: bool = True,
         **kwargs,
     ) -> Optional[Union[Error, dict]]:
         """Perform a DELETE request to create, as defined in :rfc:`RFC7644 §3.6 <7644#section-3.6>`.
 
-        :param resource_type: The type of the resource to delete.
+        :param resource_model: The type of the resource to delete.
         :param id: The type id the resource to delete.
         :param check_response_payload: Whether to validate that the response payload is valid.
             If set, the raw payload will be returned.
@@ -562,31 +665,16 @@ class SCIMClient:
             response = scim.delete(User, "foobar")
             # 'response' may be None, or an Error object
         """
-        self.check_resource_type(resource_type)
-        delete_url = self.resource_endpoint(resource_type) + f"/{id}"
-        url = kwargs.pop("url", delete_url)
-
-        try:
-            response = self.client.delete(url, **kwargs)
-        except RequestError as exc:
-            scim_exc = RequestNetworkError()
-            if sys.version_info >= (3, 11):  # pragma: no cover
-                scim_exc.add_note(str(exc))
-            raise scim_exc from exc
-
-        return self.check_response(
-            response=response,
-            expected_status_codes=expected_status_codes,
-            check_response_payload=check_response_payload,
-            raise_scim_errors=raise_scim_errors,
-        )
+        raise NotImplementedError()
 
     def replace(
         self,
         resource: Union[AnyResource, dict],
         check_request_payload: bool = True,
         check_response_payload: bool = True,
-        expected_status_codes: Optional[list[int]] = REPLACEMENT_RESPONSE_STATUS_CODES,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.REPLACEMENT_RESPONSE_STATUS_CODES,
         raise_scim_errors: bool = True,
         **kwargs,
     ) -> Union[AnyResource, Error, dict]:
@@ -628,58 +716,280 @@ class SCIMClient:
             which value will excluded from the request payload, and which values are expected in
             the response payload.
         """
-        if not check_request_payload:
-            payload = resource
-            url = kwargs.pop("url", None)
+        raise NotImplementedError()
 
-        else:
-            if isinstance(resource, Resource):
-                resource_type = resource.__class__
 
-            else:
-                resource_type = Resource.get_by_payload(self.resource_types, resource)
-                if not resource_type:
-                    raise SCIMRequestError(
-                        "Cannot guess resource type from the payload",
-                        source=resource,
-                    )
+class BaseAsyncSCIMClient(BaseSCIMClient):
+    """Base class for asynchronous request clients."""
 
-                try:
-                    resource = resource_type.model_validate(resource)
-                except ValidationError as exc:
-                    scim_exc = RequestPayloadValidationError(source=resource)
-                    if sys.version_info >= (3, 11):  # pragma: no cover
-                        scim_exc.add_note(str(exc))
-                    raise scim_exc from exc
+    async def create(
+        self,
+        resource: Union[AnyResource, dict],
+        check_request_payload: bool = True,
+        check_response_payload: bool = True,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.CREATION_RESPONSE_STATUS_CODES,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> Union[AnyResource, Error, dict]:
+        """Perform a POST request to create, as defined in :rfc:`RFC7644 §3.3 <7644#section-3.3>`.
+
+        :param resource: The resource to create
+            If is a :data:`dict`, the resource type will be guessed from the schema.
+        :param check_request_payload: If :data:`False`,
+            :code:`resource` is expected to be a dict that will be passed as-is in the request.
+        :param check_response_payload: Whether to validate that the response payload is valid.
+            If set, the raw payload will be returned.
+        :param expected_status_codes: The list of expected status codes form the response.
+            If :data:`None` any status code is accepted.
+        :param raise_scim_errors: If :data:`True` and the server returned an
+            :class:`~scim2_models.Error` object, a :class:`~scim2_client.SCIMResponseErrorObject`
+            exception will be raised. If :data:`False` the error object is returned.
+        :param kwargs: Additional parameters passed to the underlying HTTP request
+            library.
 
-            self.check_resource_type(resource_type)
+        :return:
+            - An :class:`~scim2_models.Error` object in case of error.
+            - The created object as returned by the server in case of success and :code:`check_response_payload` is :data:`True`.
+            - The created object payload as returned by the server in case of success and :code:`check_response_payload` is :data:`False`.
 
-            if not resource.id:
-                raise SCIMRequestError("Resource must have an id", source=resource)
+        .. code-block:: python
+            :caption: Creation of a `User` resource
 
-            payload = resource.model_dump(scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST)
-            url = kwargs.pop(
-                "url", self.resource_endpoint(resource.__class__) + f"/{resource.id}"
-            )
+            from scim2_models import User
 
-        try:
-            response = self.client.put(url, json=payload, **kwargs)
-        except RequestError as exc:
-            scim_exc = RequestNetworkError(source=payload)
-            if sys.version_info >= (3, 11):  # pragma: no cover
-                scim_exc.add_note(str(exc))
-            raise scim_exc from exc
+            request = User(user_name="bjensen@example.com")
+            response = scim.create(request)
+            # 'response' may be a User or an Error object
 
-        return self.check_response(
-            response=response,
-            expected_status_codes=expected_status_codes,
-            expected_types=([resource.__class__] if check_request_payload else None),
-            check_response_payload=check_response_payload,
-            raise_scim_errors=raise_scim_errors,
-            scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE,
-        )
+        .. tip::
 
-    def modify(
-        self, resource: Union[AnyResource, dict], op: PatchOp, **kwargs
-    ) -> Optional[Union[AnyResource, dict]]:
+            Check the :attr:`~scim2_models.Context.RESOURCE_CREATION_REQUEST`
+            and :attr:`~scim2_models.Context.RESOURCE_CREATION_RESPONSE` contexts to understand
+            which value will excluded from the request payload, and which values are expected in
+            the response payload.
+        """
+        raise NotImplementedError()
+
+    async def query(
+        self,
+        resource_model: Optional[type[Resource]] = None,
+        id: Optional[str] = None,
+        search_request: Optional[Union[SearchRequest, dict]] = None,
+        check_request_payload: bool = True,
+        check_response_payload: bool = True,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.QUERY_RESPONSE_STATUS_CODES,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> Union[AnyResource, ListResponse[AnyResource], Error, dict]:
+        """Perform a GET request to read resources, as defined in :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2>`.
+
+        - If `id` is not :data:`None`, the resource with the exact id will be reached.
+        - If `id` is :data:`None`, all the resources with the given type will be reached.
+
+        :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 check_request_payload: If :data:`False`,
+            :code:`search_request` is expected to be a dict that will be passed as-is in the request.
+        :param check_response_payload: Whether to validate that the response payload is valid.
+            If set, the raw payload will be returned.
+        :param expected_status_codes: The list of expected status codes form the response.
+            If :data:`None` any status code is accepted.
+        :param raise_scim_errors: If :data:`True` and the server returned an
+            :class:`~scim2_models.Error` object, a :class:`~scim2_client.SCIMResponseErrorObject`
+            exception will be raised. If :data:`False` the error object is returned.
+        :param kwargs: Additional parameters passed to the underlying HTTP request library.
+
+        :return:
+            - A :class:`~scim2_models.Error` object in case of error.
+            - A `resource_model` object in case of success if `id` is not :data:`None`
+            - A :class:`~scim2_models.ListResponse[resource_model]` object in case of success if `id` is :data:`None`
+
+        .. note::
+
+            Querying a :class:`~scim2_models.ServiceProviderConfig` will return a
+            single object, and not a :class:`~scim2_models.ListResponse`.
+
+        :usage:
+
+        .. code-block:: python
+            :caption: Query of a `User` resource knowing its id
+
+            from scim2_models import User
+
+            response = scim.query(User, "my-user-id)
+            # 'response' may be a User or an Error object
+
+        .. code-block:: python
+            :caption: Query of all the `User` resources filtering the ones with `userName` starts with `john`
+
+            from scim2_models import User, SearchRequest
+
+            req = SearchRequest(filter='userName sw "john"')
+            response = scim.query(User, search_request=search_request)
+            # '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
+
+            response = scim.query()
+            # 'response' may be a ListResponse[Union[User, Group, ...]] or an Error object
+
+        .. tip::
+
+            Check the :attr:`~scim2_models.Context.RESOURCE_QUERY_REQUEST`
+            and :attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE` contexts to understand
+            which value will excluded from the request payload, and which values are expected in
+            the response payload.
+        """
+        raise NotImplementedError()
+
+    async def search(
+        self,
+        search_request: Optional[SearchRequest] = None,
+        check_request_payload: bool = True,
+        check_response_payload: bool = True,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.SEARCH_RESPONSE_STATUS_CODES,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> Union[AnyResource, ListResponse[AnyResource], Error, dict]:
+        """Perform a POST search request to read all available resources, as defined in :rfc:`RFC7644 §3.4.3 <7644#section-3.4.3>`.
+
+        :param resource_models: Resource type or union of types expected
+            to be read from the response.
+        :param search_request: An object detailing the search query parameters.
+        :param check_request_payload: If :data:`False`,
+            :code:`search_request` is expected to be a dict that will be passed as-is in the request.
+        :param check_response_payload: Whether to validate that the response payload is valid.
+            If set, the raw payload will be returned.
+        :param expected_status_codes: The list of expected status codes form the response.
+            If :data:`None` any status code is accepted.
+        :param raise_scim_errors: If :data:`True` and the server returned an
+            :class:`~scim2_models.Error` object, a :class:`~scim2_client.SCIMResponseErrorObject`
+            exception will be raised. If :data:`False` the error object is returned.
+        :param kwargs: Additional parameters passed to the underlying
+            HTTP request library.
+
+        :return:
+            - A :class:`~scim2_models.Error` object in case of error.
+            - A :class:`~scim2_models.ListResponse[resource_model]` object in case of success.
+
+        :usage:
+
+        .. code-block:: python
+            :caption: Searching for all the resources filtering the ones with `id` contains with `admin`
+
+            from scim2_models import User, SearchRequest
+
+            req = SearchRequest(filter='id co "john"')
+            response = scim.search(search_request=search_request)
+            # 'response' may be a ListResponse[User] or an Error object
+
+        .. tip::
+
+            Check the :attr:`~scim2_models.Context.SEARCH_REQUEST`
+            and :attr:`~scim2_models.Context.SEARCH_RESPONSE` contexts to understand
+            which value will excluded from the request payload, and which values are expected in
+            the response payload.
+        """
+        raise NotImplementedError()
+
+    async def delete(
+        self,
+        resource_model: type,
+        id: str,
+        check_response_payload: bool = True,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.DELETION_RESPONSE_STATUS_CODES,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> Optional[Union[Error, dict]]:
+        """Perform a DELETE request to create, as defined in :rfc:`RFC7644 §3.6 <7644#section-3.6>`.
+
+        :param resource_model: The type of the resource to delete.
+        :param id: The type id the resource to delete.
+        :param check_response_payload: Whether to validate that the response payload is valid.
+            If set, the raw payload will be returned.
+        :param expected_status_codes: The list of expected status codes form the response.
+            If :data:`None` any status code is accepted.
+        :param raise_scim_errors: If :data:`True` and the server returned an
+            :class:`~scim2_models.Error` object, a :class:`~scim2_client.SCIMResponseErrorObject`
+            exception will be raised. If :data:`False` the error object is returned.
+        :param kwargs: Additional parameters passed to the underlying
+            HTTP request library.
+
+        :return:
+            - A :class:`~scim2_models.Error` object in case of error.
+            - :data:`None` in case of success.
+
+        :usage:
+
+        .. code-block:: python
+            :caption: Deleting an `User` which `id` is `foobar`
+
+            from scim2_models import User, SearchRequest
+
+            response = scim.delete(User, "foobar")
+            # 'response' may be None, or an Error object
+        """
+        raise NotImplementedError()
+
+    async def replace(
+        self,
+        resource: Union[AnyResource, dict],
+        check_request_payload: bool = True,
+        check_response_payload: bool = True,
+        expected_status_codes: Optional[
+            list[int]
+        ] = BaseSCIMClient.REPLACEMENT_RESPONSE_STATUS_CODES,
+        raise_scim_errors: bool = True,
+        **kwargs,
+    ) -> Union[AnyResource, Error, dict]:
+        """Perform a PUT request to replace a resource, as defined in :rfc:`RFC7644 §3.5.1 <7644#section-3.5.1>`.
+
+        :param resource: The new resource to replace.
+            If is a :data:`dict`, the resource type will be guessed from the schema.
+        :param check_request_payload: If :data:`False`,
+            :code:`resource` is expected to be a dict that will be passed as-is in the request.
+        :param check_response_payload: Whether to validate that the response payload is valid.
+            If set, the raw payload will be returned.
+        :param expected_status_codes: The list of expected status codes form the response.
+            If :data:`None` any status code is accepted.
+        :param raise_scim_errors: If :data:`True` and the server returned an
+            :class:`~scim2_models.Error` object, a :class:`~scim2_client.SCIMResponseErrorObject`
+            exception will be raised. If :data:`False` the error object is returned.
+        :param kwargs: Additional parameters passed to the underlying
+            HTTP request library.
+
+        :return:
+            - An :class:`~scim2_models.Error` object in case of error.
+            - The updated object as returned by the server in case of success.
+
+        :usage:
+
+        .. code-block:: python
+            :caption: Replacement of a `User` resource
+
+            from scim2_models import User
+
+            user = scim.query(User, "my-used-id")
+            user.display_name = "Fancy New Name"
+            updated_user = scim.replace(user)
+
+        .. tip::
+
+            Check the :attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`
+            and :attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_RESPONSE` contexts to understand
+            which value will excluded from the request payload, and which values are expected in
+            the response payload.
+        """
         raise NotImplementedError()