scim2-client 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

scim2_client/__init__.py

@@ -1,5 +1,11 @@
 from .client import SCIMClient
+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
@@ -7,7 +13,13 @@ from .errors import UnexpectedStatusCode
 __all__ = [
     "SCIMClient",
     "SCIMClientError",
-    "UnexpectedStatusCode",
-    "UnexpectedContentType",
+    "SCIMRequestError",
+    "SCIMResponseError",
+    "SCIMResponseErrorObject",
     "UnexpectedContentFormat",
+    "UnexpectedContentType",
+    "UnexpectedStatusCode",
+    "RequestPayloadValidationError",
+    "RequestNetworkError",
+    "ResponsePayloadValidationError",
 ]

scim2_client/client.py

@@ -8,6 +8,7 @@ from typing import Type
 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
@@ -16,9 +17,18 @@ from scim2_models import Error
 from scim2_models import ListResponse
 from scim2_models import PatchOp
 from scim2_models import Resource
+from scim2_models import ResourceType
+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
@@ -30,7 +40,16 @@ BASE_HEADERS = {
 
 
 class SCIMClient:
-    """An object that perform SCIM requests and validate responses."""
+    """An object that perform SCIM requests and validate responses.
+
+    :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.
+        If a request payload describe a resource that is not in this list, an exception will be raised.
+
+    .. note::
+
+        :class:`~scim2_models.ResourceType`, :class:`~scim2_models.Schema` and :class:`scim2_models.ServiceProviderConfig` are pre-loaded by default.
+    """
 
     CREATION_RESPONSE_STATUS_CODES: List[int] = [
         201,
@@ -99,13 +118,22 @@ class SCIMClient:
 
     def __init__(self, client: Client, resource_types: Optional[Tuple[Type]] = None):
         self.client = client
-        self.resource_types = resource_types or ()
+        self.resource_types = tuple(
+            set(resource_types or []) | {ResourceType, Schema, ServiceProviderConfig}
+        )
 
     def check_resource_type(self, resource_type):
         if resource_type not in self.resource_types:
-            raise ValueError(f"Unknown resource type: '{resource_type}'")
+            raise SCIMRequestError(f"Unknown resource type: '{resource_type}'")
 
     def resource_endpoint(self, resource_type: Type):
+        if resource_type is None:
+            return "/"
+
+        # This one takes no final 's'
+        if resource_type is ServiceProviderConfig:
+            return "/ServiceProviderConfig"
+
         try:
             first_bracket_index = resource_type.__name__.index("[")
             root_name = resource_type.__name__[:first_bracket_index]
@@ -117,11 +145,13 @@ class SCIMClient:
         self,
         response: Response,
         expected_status_codes: List[int],
-        expected_type: Optional[Type] = None,
+        expected_types: Optional[Type] = None,
+        check_response_payload: bool = True,
+        raise_scim_errors: bool = False,
         scim_ctx: Optional[Context] = None,
     ):
         if expected_status_codes and response.status_code not in expected_status_codes:
-            raise UnexpectedStatusCode(response)
+            raise UnexpectedStatusCode(source=response)
 
         # Interoperability considerations:  The "application/scim+json" media
         # type is intended to identify JSON structure data that conforms to
@@ -131,7 +161,7 @@ class SCIMClient:
 
         expected_response_content_types = ("application/scim+json", "application/json")
         if response.headers.get("content-type") not in expected_response_content_types:
-            raise UnexpectedContentType(response)
+            raise UnexpectedContentType(source=response)
 
         # In addition to returning an HTTP response code, implementers MUST return
         # the errors in the body of the response in a JSON format
@@ -145,21 +175,45 @@ class SCIMClient:
             try:
                 response_payload = response.json()
             except json.decoder.JSONDecodeError as exc:
-                raise UnexpectedContentFormat(response) from exc
+                raise UnexpectedContentFormat(source=response) from exc
+
+        if not check_response_payload:
+            return response_payload
 
         try:
-            return Error.model_validate(response_payload)
+            error = Error.model_validate(response_payload)
+            if raise_scim_errors:
+                raise SCIMResponseErrorObject(source=error)
+            return error
         except ValidationError:
             pass
 
-        if expected_type:
+        if not expected_types:
+            return response_payload
+
+        actual_type = Resource.get_by_payload(
+            expected_types, response_payload, with_extensions=False
+        )
+
+        if not actual_type:
+            expected = ", ".join([type.__name__ for type in expected_types])
             try:
-                return expected_type.model_validate(response_payload, scim_ctx=scim_ctx)
-            except ValidationError as exc:
-                exc.response_payload = response_payload
-                raise exc
+                schema = ", ".join(response_payload["schemas"])
+                message = f"Expected type {expected} but got unknow resource with schemas: {schema}"
+            except KeyError:
+                message = (
+                    f"Expected type {expected} but got undefined object with no schema"
+                )
 
-        return response_payload
+            raise SCIMResponseError(message, source=response)
+
+        try:
+            return actual_type.model_validate(response_payload, scim_ctx=scim_ctx)
+        except ValidationError as exc:
+            scim_exc = ResponsePayloadValidationError(source=response)
+            if hasattr(scim_exc, "add_note"):  # pragma: no cover
+                scim_exc.add_note(str(exc))
+            raise scim_exc from exc
 
     def create(
         self,
@@ -167,6 +221,7 @@ class SCIMClient:
         check_request_payload: bool = True,
         check_response_payload: bool = True,
         check_status_code: bool = True,
+        raise_scim_errors: bool = False,
         **kwargs,
     ) -> Union[AnyResource, Error, Dict]:
         """Perform a POST request to create, as defined in :rfc:`RFC7644 §3.3
@@ -179,12 +234,32 @@ class SCIMClient:
         :param check_response_payload: Whether to validate that the response payload is valid.
             If set, the raw payload will be returned.
         :param check_status_code: Whether to validate that the response status code is valid.
+        :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 created object as returned by the server in case of success.
+            - 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`.
+
+        .. code-block:: python
+            :caption: Creation of a `User` resource
+
+            from scim2_models import User
+
+            request = User(user_name="bjensen@example.com")
+            response = scim.create(request)
+            # 'response' may be a User or an Error object
+
+        .. tip::
+
+            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.
         """
 
         if not check_request_payload:
@@ -198,35 +273,50 @@ class SCIMClient:
             else:
                 resource_type = Resource.get_by_payload(self.resource_types, resource)
                 if not resource_type:
-                    raise SCIMClientError(
-                        None, "Cannot guess resource type from the payload"
+                    raise SCIMRequestError(
+                        "Cannot guess resource type from the payload"
                     )
 
-                resource = resource_type.model_validate(resource)
+                try:
+                    resource = resource_type.model_validate(resource)
+                except ValidationError as exc:
+                    scim_exc = RequestPayloadValidationError(source=resource)
+                    if hasattr(scim_exc, "add_note"):  # 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)
 
-        response = self.client.post(url, json=payload, **kwargs)
+        try:
+            response = self.client.post(url, json=payload, **kwargs)
+        except RequestError as exc:
+            scim_exc = RequestNetworkError(source=payload)
+            if hasattr(scim_exc, "add_note"):  # pragma: no cover
+                scim_exc.add_note(str(exc))
+            raise scim_exc from exc
 
         return self.check_response(
-            response,
-            self.CREATION_RESPONSE_STATUS_CODES if check_status_code else None,
-            resource.__class__
-            if check_request_payload and check_response_payload
-            else None,
+            response=response,
+            expected_status_codes=(
+                self.CREATION_RESPONSE_STATUS_CODES if check_status_code else None
+            ),
+            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,
         )
 
     def query(
         self,
-        resource_type: Type,
+        resource_type: Optional[Type] = None,
         id: Optional[str] = None,
         search_request: Optional[Union[SearchRequest, Dict]] = None,
         check_request_payload: bool = True,
         check_response_payload: bool = True,
         check_status_code: bool = True,
+        raise_scim_errors: bool = False,
         **kwargs,
     ) -> Union[AnyResource, ListResponse[AnyResource], Error, Dict]:
         """Perform a GET request to read resources, as defined in :rfc:`RFC7644
@@ -243,72 +333,58 @@ class SCIMClient:
         :param check_response_payload: Whether to validate that the response payload is valid.
             If set, the raw payload will be returned.
         :param check_status_code: Whether to validate that the response status code is valid.
+        :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_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`
-        """
 
-        self.check_resource_type(resource_type)
-        if not check_request_payload:
-            payload = search_request
+        .. note::
 
-        else:
-            payload = (
-                search_request.model_dump(
-                    exclude_unset=True,
-                    scim_ctx=Context.RESOURCE_QUERY_REQUEST,
-                )
-                if search_request
-                else None
-            )
+            Querying a :class:`~scim2_models.ServiceProviderConfig` will return a
+            single object, and not a :class:`~scim2_models.ListResponse`.
 
-        if not id:
-            expected_type = ListResponse[resource_type]
-            url = self.resource_endpoint(resource_type)
+        :usage:
 
-        else:
-            expected_type = resource_type
-            url = self.resource_endpoint(resource_type) + f"/{id}"
+        .. code-block:: python
+            :caption: Query of a `User` resource knowing its id
 
-        response = self.client.get(url, params=payload, **kwargs)
-        return self.check_response(
-            response,
-            self.QUERY_RESPONSE_STATUS_CODES if check_status_code else None,
-            expected_type if check_response_payload else None,
-            scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
-        )
+            from scim2_models import User
 
-    def query_all(
-        self,
-        search_request: Optional[SearchRequest] = None,
-        check_request_payload: bool = True,
-        check_response_payload: bool = True,
-        check_status_code: bool = True,
-        **kwargs,
-    ) -> Union[AnyResource, ListResponse[AnyResource], Error, Dict]:
-        """Perform a GET request to read all available resources, as defined in
-        :rfc:`RFC7644 §3.4.2.1 <7644#section-3.4.2.1>`.
+            response = scim.query(User, "my-user-id)
+            # 'response' may be a User or an Error object
 
-        :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 check_status_code: Whether to validate that the response status code is valid.
-        :param kwargs: Additional parameters passed to the underlying
-            HTTP request library.
+        .. code-block:: python
+            :caption: Query of all the `User` resources filtering the ones with `userName` starts with `john`
 
-        :return:
-            - A :class:`~scim2_models.Error` object in case of error.
-            - A :class:`~scim2_models.ListResponse[resource_type]` object in case of success.
+            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.
         """
 
-        # A query against a server root indicates that all resources within the
-        # server SHALL be included, subject to filtering.
-        # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.4.2.1
+        if resource_type and check_request_payload:
+            self.check_resource_type(resource_type)
 
         if not check_request_payload:
             payload = search_request
@@ -316,20 +392,49 @@ class SCIMClient:
         else:
             payload = (
                 search_request.model_dump(
-                    exclude_unset=True, scim_ctx=Context.RESOURCE_QUERY_REQUEST
+                    exclude_unset=True,
+                    scim_ctx=Context.RESOURCE_QUERY_REQUEST,
                 )
                 if search_request
                 else None
             )
 
-        response = self.client.get("/", params=payload)
+        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 hasattr(scim_exc, "add_note"):  # pragma: no cover
+                scim_exc.add_note(str(exc))
+            raise scim_exc from exc
 
         return self.check_response(
-            response,
-            self.QUERY_RESPONSE_STATUS_CODES if check_status_code else None,
-            ListResponse[Union[self.resource_types]]
-            if check_response_payload
-            else None,
+            response=response,
+            expected_status_codes=(
+                self.QUERY_RESPONSE_STATUS_CODES if check_status_code else None
+            ),
+            expected_types=expected_types,
+            check_response_payload=check_response_payload,
+            raise_scim_errors=raise_scim_errors,
             scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
         )
 
@@ -339,6 +444,7 @@ class SCIMClient:
         check_request_payload: bool = True,
         check_response_payload: bool = True,
         check_status_code: bool = True,
+        raise_scim_errors: bool = False,
         **kwargs,
     ) -> Union[AnyResource, ListResponse[AnyResource], Error, Dict]:
         """Perform a POST search request to read all available resources, as
@@ -352,12 +458,33 @@ class SCIMClient:
         :param check_response_payload: Whether to validate that the response payload is valid.
             If set, the raw payload will be returned.
         :param check_status_code: Whether to validate that the response status code is valid.
+        :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_type]` 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.
         """
 
         if not check_request_payload:
@@ -372,38 +499,84 @@ class SCIMClient:
                 else None
             )
 
-        response = self.client.post("/.search", json=payload)
+        url = kwargs.pop("url", "/.search")
+
+        try:
+            response = self.client.post(url, json=payload)
+        except RequestError as exc:
+            scim_exc = RequestNetworkError(source=payload)
+            if hasattr(scim_exc, "add_note"):  # pragma: no cover
+                scim_exc.add_note(str(exc))
+            raise scim_exc from exc
 
         return self.check_response(
-            response,
-            self.SEARCH_RESPONSE_STATUS_CODES if check_status_code else None,
-            ListResponse[Union[self.resource_types]]
-            if check_response_payload
-            else None,
+            response=response,
+            expected_status_codes=(
+                self.SEARCH_RESPONSE_STATUS_CODES if check_status_code else None
+            ),
+            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,
         )
 
     def delete(
-        self, resource_type: Type, id: str, check_status_code: bool = True, **kwargs
+        self,
+        resource_type: Type,
+        id: str,
+        check_response_payload: bool = True,
+        check_status_code: bool = True,
+        raise_scim_errors: bool = False,
+        **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 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 check_status_code: Whether to validate that the response status code is valid.
+        :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
         """
 
         self.check_resource_type(resource_type)
-        url = self.resource_endpoint(resource_type) + f"/{id}"
-        response = self.client.delete(url, **kwargs)
+        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 hasattr(scim_exc, "add_note"):  # pragma: no cover
+                scim_exc.add_note(str(exc))
+            raise scim_exc from exc
 
         return self.check_response(
-            response, self.DELETION_RESPONSE_STATUS_CODES if check_status_code else None
+            response=response,
+            expected_status_codes=(
+                self.DELETION_RESPONSE_STATUS_CODES if check_status_code else None
+            ),
+            check_response_payload=check_response_payload,
+            raise_scim_errors=raise_scim_errors,
         )
 
     def replace(
@@ -412,6 +585,7 @@ class SCIMClient:
         check_request_payload: bool = True,
         check_response_payload: bool = True,
         check_status_code: bool = True,
+        raise_scim_errors: bool = False,
         **kwargs,
     ) -> Union[AnyResource, Error, Dict]:
         """Perform a PUT request to replace a resource, as defined in
@@ -424,12 +598,34 @@ class SCIMClient:
         :param check_response_payload: Whether to validate that the response payload is valid.
             If set, the raw payload will be returned.
         :param check_status_code: Whether to validate that the response status code is valid.
+        :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"
+            response = scim.update(user)
+            # 'response' may be a User or an Error object
+
+        .. 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.
         """
 
         if not check_request_payload:
@@ -443,30 +639,45 @@ class SCIMClient:
             else:
                 resource_type = Resource.get_by_payload(self.resource_types, resource)
                 if not resource_type:
-                    raise SCIMClientError(
-                        None, "Cannot guess resource type from the payload"
+                    raise SCIMRequestError(
+                        "Cannot guess resource type from the payload",
+                        source=resource,
                     )
 
-                resource = resource_type.model_validate(resource)
+                try:
+                    resource = resource_type.model_validate(resource)
+                except ValidationError as exc:
+                    scim_exc = RequestPayloadValidationError(source=resource)
+                    if hasattr(scim_exc, "add_note"):  # pragma: no cover
+                        scim_exc.add_note(str(exc))
+                    raise scim_exc from exc
 
             self.check_resource_type(resource_type)
 
             if not resource.id:
-                raise SCIMClientError(None, "Resource must have an id")
+                raise SCIMRequestError("Resource must have an id", source=resource)
 
             payload = resource.model_dump(scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST)
             url = kwargs.pop(
                 "url", self.resource_endpoint(resource.__class__) + f"/{resource.id}"
             )
 
-        response = self.client.put(url, json=payload, **kwargs)
+        try:
+            response = self.client.put(url, json=payload, **kwargs)
+        except RequestError as exc:
+            scim_exc = RequestNetworkError(source=payload)
+            if hasattr(scim_exc, "add_note"):  # pragma: no cover
+                scim_exc.add_note(str(exc))
+            raise scim_exc from exc
 
         return self.check_response(
-            response,
-            self.REPLACEMENT_RESPONSE_STATUS_CODES if check_status_code else None,
-            resource.__class__
-            if check_request_payload and check_response_payload
-            else None,
+            response=response,
+            expected_status_codes=(
+                self.REPLACEMENT_RESPONSE_STATUS_CODES if check_status_code else None
+            ),
+            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,
         )
 

scim2_client/errors.py

@@ -1,43 +1,125 @@
-from httpx import Response
+from typing import Any
 
 
 class SCIMClientError(Exception):
-    def __init__(self, response: Response, *args, **kwargs):
-        self.response = response
+    """Base exception for scim2-client.
+
+    :param message: The exception reason.
+    :param source: The request payload or the response object that have
+        caused the exception.
+    """
+
+    def __init__(self, message: str, source: Any = None, *args, **kwargs):
+        self.message = message
+        self.source = source
         super().__init__(*args, **kwargs)
 
+    def __str__(self):
+        return self.message or "UNKNOWN"
+
+
+class SCIMRequestError(SCIMClientError):
+    """Base exception for errors happening during request payload building."""
+
+
+class RequestNetworkError(SCIMRequestError):
+    """Error raised when a network error happened during request.
+
+    This error is raised when a :class:`httpx.RequestError` has been catched while performing a request.
+    The original :class:`~httpx.RequestError` is available with :attr:`~BaseException.__cause__`.
+    """
+
+    def __init__(self, *args, **kwargs):
+        message = kwargs.pop("message", "Network error happened during request")
+        super().__init__(message, *args, **kwargs)
+
+
+class RequestPayloadValidationError(SCIMRequestError):
+    """Error raised when an invalid request payload has been passed to
+    SCIMClient.
+
+    This error is raised when a :class:`pydantic.ValidationError` has been catched
+    while validating the client request payload.
+    The original :class:`~pydantic.ValidationError` is available with :attr:`~BaseException.__cause__`.
+
+    .. code-block:: python
+
+        try:
+            scim.create({"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "active": "not-a-bool"})
+        except RequestPayloadValidationError as exc:
+            print("Original validation error cause", exc.__cause__)
+    """
+
+    def __init__(self, *args, **kwargs):
+        message = kwargs.pop("message", "Server response payload validation error")
+        super().__init__(message, *args, **kwargs)
+
+
+class SCIMResponseError(SCIMClientError):
+    """Base exception for errors happening during response payload
+    validation."""
 
-class UnexpectedStatusCode(SCIMClientError):
-    def __init__(
-        self,
-        response: Response,
-        *args,
-        **kwargs,
-    ):
+
+class SCIMResponseErrorObject(SCIMResponseError):
+    """The server response returned a :class:`scim2_models.Error` object.
+
+    Those errors are only raised when the :code:`raise_scim_errors` parameter is :data:`True`.
+    """
+
+    def __init__(self, *args, **kwargs):
+        message = kwargs.pop(
+            "message",
+            f"The server returned a SCIM Error object: {kwargs['source'].detail}",
+        )
+        super().__init__(message, *args, **kwargs)
+
+
+class UnexpectedStatusCode(SCIMResponseError):
+    """Error raised when a server returned an unexpected status code for a
+    given :class:`~scim2_models.Context`."""
+
+    def __init__(self, *args, **kwargs):
         message = kwargs.pop(
-            "message", f"Unexpected response status code: {response.status_code}"
+            "message",
+            f"Unexpected response status code: {kwargs['source'].status_code}",
         )
-        super().__init__(response, message, *args, **kwargs)
+        super().__init__(message, *args, **kwargs)
 
 
-class UnexpectedContentType(SCIMClientError):
-    def __init__(
-        self,
-        response: Response,
-        *args,
-        **kwargs,
-    ):
-        content_type = response.headers.get("content-type", "")
+class UnexpectedContentType(SCIMResponseError):
+    """Error raised when a server returned an unexpected `Content-Type` header
+    in a response."""
+
+    def __init__(self, *args, **kwargs):
+        content_type = kwargs["source"].headers.get("content-type", "")
         message = kwargs.pop("message", f"Unexpected content type: {content_type}")
-        super().__init__(response, message, *args, **kwargs)
+        super().__init__(message, *args, **kwargs)
+
 
+class UnexpectedContentFormat(SCIMResponseError):
+    """Error raised when a server returned a response in a non-JSON format."""
 
-class UnexpectedContentFormat(SCIMClientError):
-    def __init__(
-        self,
-        response: Response,
-        *args,
-        **kwargs,
-    ):
+    def __init__(self, *args, **kwargs):
         message = kwargs.pop("message", "Unexpected response content format")
-        super().__init__(response, message, *args, **kwargs)
+        super().__init__(message, *args, **kwargs)
+
+
+class ResponsePayloadValidationError(SCIMResponseError):
+    """Error raised when the server returned a payload that cannot be
+    validated.
+
+    This error is raised when a :class:`pydantic.ValidationError` has been catched
+    while validating the server response payload.
+    The original :class:`~pydantic.ValidationError` is available with :attr:`~BaseException.__cause__`.
+
+    .. code-block:: python
+
+        try:
+            scim.query(User, "foobar")
+        except ResponsePayloadValidationError as exc:
+            print("Original validation error cause", exc.__cause__)
+    """
+
+    def __init__(self, *args, **kwargs):
+        message = kwargs.pop("message", "Server response payload validation error")
+        super().__init__(message, *args, **kwargs)

{scim2_client-0.1.4.dist-info → scim2_client-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: scim2-client
-Version: 0.1.4
+Version: 0.1.6
 Summary: Pythonically build SCIM requests and parse SCIM responses
 License: MIT
 Keywords: scim,scim2,provisioning,httpx,api
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Requires-Dist: httpx (>=0.27.0,<0.28.0)
-Requires-Dist: scim2-models (>=0.1.2,<0.2.0)
+Requires-Dist: scim2-models (>=0.1.5,<0.2.0)
 Description-Content-Type: text/markdown
 
 # scim2-client
@@ -28,6 +28,16 @@ Description-Content-Type: text/markdown
 A SCIM client Python library built upon [scim2-models](https://scim2-models.readthedocs.io) and [httpx](https://github.com/encode/httpx),
 that pythonically build requests and parse responses,
 following the [RFC7643](https://datatracker.ietf.org/doc/html/rfc7643.html) and [RFC7644](https://datatracker.ietf.org/doc/html/rfc7644.html) specifications.
+
+It aims to be used in SCIM client applications, or in unit tests for SCIM server applications.
+
+## What's SCIM anyway?
+
+SCIM stands for System for Cross-domain Identity Management, and it is a provisioning protocol.
+Provisioning is the action of managing a set of resources across different services, usually users and groups.
+SCIM is often used between Identity Providers and applications in completion of standards like OAuth2 and OpenID Connect.
+It allows users and groups creations, modifications and deletions to be synchronized between applications.
+
 ## Installation
 
 ```shell
@@ -71,3 +81,8 @@ assert isinstance(response, Error)
 assert response.detail == "One or more of the attribute values are already in use or are reserved."
 ```
 
+scim2-client belongs in a collection of SCIM tools developed by [Yaal Coop](https://yaal.coop),
+with [scim2-models](https://github.com/yaal-coop/scim2-models),
+[scim2-tester](https://github.com/yaal-coop/scim2-tester) and
+[scim2-cli](https://github.com/yaal-coop/scim2-cli)
+

scim2_client-0.1.6.dist-info/RECORD

@@ -0,0 +1,6 @@
+scim2_client/__init__.py,sha256=vgrTJZIqJLZc72XCJwYKrSCGUDkMZTJjCJiZkHERZGs,780
+scim2_client/client.py,sha256=_nGGGaKhwQSgJU1b56C2O859v-YC4YNDfm3uX5U0c8U,26975
+scim2_client/errors.py,sha256=Lu_4lPlbryqWYGLPmH2iWaVmlay8S4PrH6lUPIvcisA,4430
+scim2_client-0.1.6.dist-info/METADATA,sha256=DCymPPTKmd_PXLRfzblUqgBajOs7N8ZqSrNoANtcyQg,3495
+scim2_client-0.1.6.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+scim2_client-0.1.6.dist-info/RECORD,,

scim2_client-0.1.4.dist-info/RECORD

@@ -1,6 +0,0 @@
-scim2_client/__init__.py,sha256=2UNsl6HNtVUv5LVcnmLaCHyT4SqAUUFOIWW2r5XGv6A,338
-scim2_client/client.py,sha256=HzsOyb4xqUC05-HuhV18g5abYK-00AY0iCni4-XBEtA,17880
-scim2_client/errors.py,sha256=uOOAwsD8rDrC8BQbwPid051YyWtexTcS8b7i6QC6-CM,1175
-scim2_client-0.1.4.dist-info/METADATA,sha256=khpZeya8xou5elKL0lN9VUC2sMS6KgYFyL690kH7GfA,2662
-scim2_client-0.1.4.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-scim2_client-0.1.4.dist-info/RECORD,,