scim2-client 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

scim2_client/client.py

@@ -1,5 +1,6 @@
 import json
 import json.decoder
+from typing import Dict
 from typing import List
 from typing import Optional
 from typing import Tuple
@@ -10,6 +11,7 @@ from httpx import Client
 from httpx import Response
 from pydantic import ValidationError
 from scim2_models import AnyResource
+from scim2_models import Context
 from scim2_models import Error
 from scim2_models import ListResponse
 from scim2_models import PatchOp
@@ -28,6 +30,71 @@ BASE_HEADERS = {
 class SCIMClient:
     """An object that perform SCIM requests and validate responses."""
 
+    CREATION_RESPONSE_STATUS_CODES: List[int] = [
+        201,
+        409,
+        307,
+        308,
+        400,
+        401,
+        403,
+        404,
+        500,
+    ]
+    """Resource creation HTTP codes defined at :rfc:`RFC7644 §3.3
+    <7644#section-3.3>` and :rfc:`RFC7644 §3.12 <7644#section-3.12>`"""
+
+    QUERY_RESPONSE_STATUS_CODES: List[int] = [200, 400, 307, 308, 401, 403, 404, 500]
+    """Resource querying HTTP codes defined at :rfc:`RFC7644 §3.4.2
+    <7644#section-3.4.2>` and :rfc:`RFC7644 §3.12 <7644#section-3.12>`"""
+
+    SEARCH_RESPONSE_STATUS_CODES: List[int] = [
+        200,
+        307,
+        308,
+        400,
+        401,
+        403,
+        404,
+        409,
+        413,
+        500,
+        501,
+    ]
+    """Resource querying HTTP codes defined at :rfc:`RFC7644 §3.4.3
+    <7644#section-3.4.3>` and :rfc:`RFC7644 §3.12 <7644#section-3.12>`"""
+
+    DELETION_RESPONSE_STATUS_CODES: List[int] = [
+        204,
+        307,
+        308,
+        400,
+        401,
+        403,
+        404,
+        412,
+        500,
+        501,
+    ]
+    """Resource deletion HTTP codes defined at :rfc:`RFC7644 §3.6
+    <7644#section-3.6>` and :rfc:`RFC7644 §3.12 <7644#section-3.12>`"""
+
+    REPLACEMENT_RESPONSE_STATUS_CODES: List[int] = [
+        200,
+        307,
+        308,
+        400,
+        401,
+        403,
+        404,
+        409,
+        412,
+        500,
+        501,
+    ]
+    """Resource querying HTTP codes defined at :rfc:`RFC7644 §3.4.2
+    <7644#section-3.4.2>` and :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 = resource_types or ()
@@ -44,8 +111,9 @@ class SCIMClient:
         response: Response,
         expected_status_codes: List[int],
         expected_type: Optional[Type] = None,
+        scim_ctx: Optional[Context] = None,
     ):
-        if response.status_code not in expected_status_codes:
+        if expected_status_codes and response.status_code not in expected_status_codes:
             raise UnexpectedStatusCode(response)
 
         # Interoperability considerations:  The "application/scim+json" media
@@ -62,7 +130,8 @@ class SCIMClient:
         # the errors in the body of the response in a JSON format
         # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.12
 
-        if response.status_code in (204, 205):
+        no_content_status_codes = [204, 205]
+        if response.status_code in no_content_status_codes:
             response_payload = None
 
         else:
@@ -77,14 +146,31 @@ class SCIMClient:
             pass
 
         if expected_type:
-            return expected_type.model_validate(response_payload)
+            try:
+                return expected_type.model_validate(response_payload, scim_ctx=scim_ctx)
+            except ValidationError as exc:
+                exc.response_payload = response_payload
+                raise exc
+
         return response_payload
 
-    def create(self, resource: AnyResource, **kwargs) -> Union[AnyResource, Error]:
+    def create(
+        self,
+        resource: Union[AnyResource, Dict],
+        check_request_payload: bool = True,
+        check_response_payload: bool = True,
+        check_status_code: 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
+        :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 check_status_code: Whether to validate that the response status code is valid.
         :param kwargs: Additional parameters passed to the underlying HTTP request
             library.
 
@@ -93,35 +179,36 @@ class SCIMClient:
             - The created object as returned by the server in case of success.
         """
 
-        self.check_resource_type(resource.__class__)
-        url = self.resource_endpoint(resource.__class__)
-        dump = resource.model_dump(exclude_none=True, by_alias=True, mode="json")
-        response = self.client.post(url, json=dump, **kwargs)
-
-        expected_status_codes = [
-            # Resource creation HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644#section-3.3
-            201,
-            409,
-            # Default HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.12
-            307,
-            308,
-            400,
-            401,
-            403,
-            404,
-            500,
-        ]
-        return self.check_response(response, expected_status_codes, resource.__class__)
+        if not check_request_payload:
+            payload = resource
+            url = kwargs.pop("url", None)
+
+        else:
+            self.check_resource_type(resource.__class__)
+            url = kwargs.pop("url", self.resource_endpoint(resource.__class__))
+            payload = resource.model_dump(scim_ctx=Context.RESOURCE_CREATION_REQUEST)
+
+        response = self.client.post(url, json=payload, **kwargs)
+
+        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,
+            scim_ctx=Context.RESOURCE_CREATION_RESPONSE,
+        )
 
     def query(
         self,
         resource_type: Type,
         id: Optional[str] = None,
-        search_request: Optional[SearchRequest] = None,
+        search_request: Optional[Union[SearchRequest, Dict]] = None,
+        check_request_payload: bool = True,
+        check_response_payload: bool = True,
+        check_status_code: bool = True,
         **kwargs,
-    ) -> Union[AnyResource, ListResponse[AnyResource], Error]:
+    ) -> 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>`.
 
@@ -131,6 +218,11 @@ class SCIMClient:
         :param resource_type: 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 check_status_code: Whether to validate that the response status code is valid.
         :param kwargs: Additional parameters passed to the underlying HTTP request library.
 
         :return:
@@ -140,13 +232,18 @@ class SCIMClient:
         """
 
         self.check_resource_type(resource_type)
-        payload = (
-            search_request.model_dump(
-                by_alias=True, exclude_none=True, exclude_unset=True, mode="json"
+        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
             )
-            if search_request
-            else None
-        )
 
         if not id:
             expected_type = ListResponse[resource_type]
@@ -156,32 +253,31 @@ class SCIMClient:
             expected_type = resource_type
             url = self.resource_endpoint(resource_type) + f"/{id}"
 
-        expected_status_codes = [
-            # Resource querying HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2
-            200,
-            400,
-            # Default HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.12
-            307,
-            308,
-            401,
-            403,
-            404,
-            500,
-        ]
         response = self.client.get(url, params=payload, **kwargs)
-        return self.check_response(response, expected_status_codes, expected_type)
+        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,
+        )
 
     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]:
+    ) -> 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>`.
 
         :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.
 
@@ -194,46 +290,48 @@ class SCIMClient:
         # server SHALL be included, subject to filtering.
         # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.4.2.1
 
-        payload = (
-            search_request.model_dump(
-                by_alias=True, exclude_none=True, exclude_unset=True, mode="json"
+        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
             )
-            if search_request
-            else None
-        )
-        response = self.client.get("/", params=payload)
 
-        expected_status_codes = [
-            # Resource querying HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2
-            200,
-            400,
-            # Default HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.12
-            307,
-            308,
-            401,
-            403,
-            404,
-            500,
-            501,
-        ]
+        response = self.client.get("/", params=payload)
 
         return self.check_response(
-            response, expected_status_codes, ListResponse[Union[self.resource_types]]
+            response,
+            self.QUERY_RESPONSE_STATUS_CODES if check_status_code else None,
+            ListResponse[Union[self.resource_types]]
+            if check_response_payload
+            else None,
+            scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
         )
 
     def search(
         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]:
+    ) -> 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
             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 check_status_code: Whether to validate that the response status code is valid.
         :param kwargs: Additional parameters passed to the underlying
             HTTP request library.
 
@@ -242,40 +340,36 @@ class SCIMClient:
             - A :class:`~scim2_models.ListResponse[resource_type]` object in case of success.
         """
 
-        payload = (
-            search_request.model_dump(
-                by_alias=True, exclude_none=True, exclude_unset=True, mode="json"
+        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
             )
-            if search_request
-            else None
-        )
+
         response = self.client.post("/.search", params=payload)
 
-        expected_status_codes = [
-            # Resource querying HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.3
-            200,
-            # Default HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.12
-            307,
-            308,
-            400,
-            401,
-            403,
-            404,
-            409,
-            413,
-            500,
-            501,
-        ]
         return self.check_response(
-            response, expected_status_codes, ListResponse[Union[self.resource_types]]
+            response,
+            self.SEARCH_RESPONSE_STATUS_CODES if check_status_code else None,
+            ListResponse[Union[self.resource_types]]
+            if check_response_payload
+            else None,
+            scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
         )
 
-    def delete(self, resource_type: Type, id: str, **kwargs) -> Optional[Error]:
+    def delete(
+        self, resource_type: Type, id: str, check_status_code: 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 check_status_code: Whether to validate that the response status code is valid.
         :param kwargs: Additional parameters passed to the underlying
             HTTP request library.
 
@@ -288,29 +382,27 @@ class SCIMClient:
         url = self.resource_endpoint(resource_type) + f"/{id}"
         response = self.client.delete(url, **kwargs)
 
-        expected_status_codes = [
-            # Resource deletion HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644#section-3.6
-            204,
-            # Default HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.12
-            307,
-            308,
-            400,
-            401,
-            403,
-            404,
-            412,
-            500,
-            501,
-        ]
-        return self.check_response(response, expected_status_codes)
-
-    def replace(self, resource: AnyResource, **kwargs) -> Union[AnyResource, Error]:
+        return self.check_response(
+            response, self.DELETION_RESPONSE_STATUS_CODES if check_status_code else None
+        )
+
+    def replace(
+        self,
+        resource: Union[AnyResource, Dict],
+        check_request_payload: bool = True,
+        check_response_payload: bool = True,
+        check_status_code: 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 state of the resource to replace.
+        :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 check_status_code: Whether to validate that the response status code is valid.
         :param kwargs: Additional parameters passed to the underlying
             HTTP request library.
 
@@ -319,34 +411,32 @@ class SCIMClient:
             - The updated object as returned by the server in case of success.
         """
 
-        self.check_resource_type(resource.__class__)
-        if not resource.id:
-            raise Exception("Resource must have an id")
-
-        dump = resource.model_dump(exclude_none=True, by_alias=True, mode="json")
-        url = self.resource_endpoint(resource.__class__) + f"/{resource.id}"
-        response = self.client.put(url, json=dump, **kwargs)
-
-        expected_status_codes = [
-            # Resource querying HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2
-            200,
-            # Default HTTP codes defined at:
-            # https://datatracker.ietf.org/doc/html/rfc7644.html#section-3.12
-            307,
-            308,
-            400,
-            401,
-            403,
-            404,
-            409,
-            412,
-            500,
-            501,
-        ]
-        return self.check_response(response, expected_status_codes, resource.__class__)
+        if not check_request_payload:
+            payload = resource
+            url = kwargs.pop("url")
+
+        else:
+            self.check_resource_type(resource.__class__)
+            if not resource.id:
+                raise Exception("Resource must have an id")
+
+            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)
+
+        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,
+            scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE,
+        )
 
     def modify(
-        self, resource: AnyResource, op: PatchOp, **kwargs
-    ) -> Optional[AnyResource]:
+        self, resource: Union[AnyResource, Dict], op: PatchOp, **kwargs
+    ) -> Optional[Union[AnyResource, Dict]]:
         raise NotImplementedError()

{scim2_client-0.1.0.dist-info → scim2_client-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: scim2-client
-Version: 0.1.0
+Version: 0.1.2
 Summary: Pythonically build SCIM requests and parse SCIM responses
 License: MIT
 Keywords: scim,scim2,provisioning,httpx,api
@@ -20,12 +20,14 @@ 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.0,<0.2.0)
+Requires-Dist: scim2-models (>=0.1.1,<0.2.0)
 Description-Content-Type: text/markdown
 
 # scim2-client
 
-A SCIM client library built upon [scim2-models](https://scim2-models.readthedocs.io), 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.
+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.
 ## Installation
 
 ```shell
@@ -40,7 +42,7 @@ Here is an example of usage:
 
 ```python
 import datetime
-from httpx impont Client
+from httpx import Client
 from scim2_models import User, EnterpriseUserUser, Group, Error
 from scim2_client import SCIMClient
 

scim2_client-0.1.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+scim2_client/__init__.py,sha256=2UNsl6HNtVUv5LVcnmLaCHyT4SqAUUFOIWW2r5XGv6A,338
+scim2_client/client.py,sha256=_ZjMd6_Kh5SYEcstm5OkMIu0z-N93R4SWdG0lGd4u7s,16538
+scim2_client/errors.py,sha256=uOOAwsD8rDrC8BQbwPid051YyWtexTcS8b7i6QC6-CM,1175
+scim2_client-0.1.2.dist-info/METADATA,sha256=4h7QD3jpYRhSQCBmLX9AFhHJ9R68_ObP45V9_kV51LI,2654
+scim2_client-0.1.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+scim2_client-0.1.2.dist-info/RECORD,,

scim2_client-0.1.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-scim2_client/__init__.py,sha256=2UNsl6HNtVUv5LVcnmLaCHyT4SqAUUFOIWW2r5XGv6A,338
-scim2_client/client.py,sha256=hLrOaXIzPE_4ZlJKAJNqWOEnFAVEo7ctPuns9qSOJ1E,12635
-scim2_client/errors.py,sha256=uOOAwsD8rDrC8BQbwPid051YyWtexTcS8b7i6QC6-CM,1175
-scim2_client-0.1.0.dist-info/METADATA,sha256=HY_uiLBOOMueWBN_bMbi2rq_G6q6iKfJNoCauSHeavQ,2602
-scim2_client-0.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-scim2_client-0.1.0.dist-info/RECORD,,