scim2-client 0.1.0__tar.gz

scim2_client-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.1
+Name: scim2-client
+Version: 0.1.0
+Summary: Pythonically build SCIM requests and parse SCIM responses
+License: MIT
+Keywords: scim,scim2,provisioning,httpx,api
+Author: Yaal Coop
+Author-email: contact@yaal.coop
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+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)
+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.
+## Installation
+
+```shell
+pip install scim2-client
+```
+
+## Usage
+
+Check the [tutorial](https://scim2-client.readthedocs.io/en/latest/tutorial.html) and the [reference](https://scim2-client.readthedocs.io/en/latest/reference.html) for more details.
+
+Here is an example of usage:
+
+```python
+import datetime
+from httpx impont Client
+from scim2_models import User, EnterpriseUserUser, Group, Error
+from scim2_client import SCIMClient
+
+client = Client(base_url=f"https://auth.example/scim/v2", headers={"Authorization": "Bearer foobar"})
+scim = SCIMClient(client, resource_types=(User[EnterpriseUser], Group))
+
+# Query resources
+user = scim.query(User, "2819c223-7f76-453a-919d-413861904646")
+assert user.user_name == "bjensen@example.com"
+assert user.meta.last_updated == datetime.datetime(
+    2024, 4, 13, 12, 0, 0, tzinfo=datetime.timezone.utc
+)
+
+# Update resources
+user.display_name = "Babes Jensen"
+user = scim.replace(user)
+assert user.display_name == "Babes Jensen"
+assert user.meta.last_updated == datetime.datetime(
+    2024, 4, 13, 12, 0, 30, tzinfo=datetime.timezone.utc
+)
+
+# Create resources
+response = scim.create(User, "2819c223-7f76-453a-919d-413861904646")
+assert isinstance(response, Error)
+assert response.detail == "One or more of the attribute values are already in use or are reserved."
+```
+

scim2_client-0.1.0/README.md

@@ -0,0 +1,44 @@
+# 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.
+## Installation
+
+```shell
+pip install scim2-client
+```
+
+## Usage
+
+Check the [tutorial](https://scim2-client.readthedocs.io/en/latest/tutorial.html) and the [reference](https://scim2-client.readthedocs.io/en/latest/reference.html) for more details.
+
+Here is an example of usage:
+
+```python
+import datetime
+from httpx impont Client
+from scim2_models import User, EnterpriseUserUser, Group, Error
+from scim2_client import SCIMClient
+
+client = Client(base_url=f"https://auth.example/scim/v2", headers={"Authorization": "Bearer foobar"})
+scim = SCIMClient(client, resource_types=(User[EnterpriseUser], Group))
+
+# Query resources
+user = scim.query(User, "2819c223-7f76-453a-919d-413861904646")
+assert user.user_name == "bjensen@example.com"
+assert user.meta.last_updated == datetime.datetime(
+    2024, 4, 13, 12, 0, 0, tzinfo=datetime.timezone.utc
+)
+
+# Update resources
+user.display_name = "Babes Jensen"
+user = scim.replace(user)
+assert user.display_name == "Babes Jensen"
+assert user.meta.last_updated == datetime.datetime(
+    2024, 4, 13, 12, 0, 30, tzinfo=datetime.timezone.utc
+)
+
+# Create resources
+response = scim.create(User, "2819c223-7f76-453a-919d-413861904646")
+assert isinstance(response, Error)
+assert response.detail == "One or more of the attribute values are already in use or are reserved."
+```

scim2_client-0.1.0/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "scim2-client"
+version = "0.1.0"
+description = "Pythonically build SCIM requests and parse SCIM responses"
+authors = ["Yaal Coop <contact@yaal.coop>"]
+license = "MIT"
+readme = "README.md"
+keywords = ["scim", "scim2", "provisioning", "httpx", "api"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Web Environment",
+    "Programming Language :: Python",
+    "Operating System :: OS Independent",
+]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+httpx = "^0.27.0"
+scim2-models = "^0.1.0"
+
+[tool.poetry.group.doc]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.2.1"
+pytest-coverage = "^0.0"
+pytest-httpserver = "^1.0.10"
+
+[tool.poetry.group.doc.dependencies]
+shibuya = "^2024.5.15"
+sphinx = "^7.3.7"
+myst-parser = "^3.0.1"
+
+[tool.coverage.run]
+source = [
+    "scim2_client",
+    "tests",
+]
+omit = [".tox/*"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "@pytest.mark.skip",
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "\\.\\.\\.\\s*$", # ignore ellipsis
+]
+
+[tool.ruff.lint]
+select = [
+    "E", # pycodestyle
+    "F", # pyflakes
+    "I", # isort
+    "UP", # pyupgrade
+]
+ignore = [
+    "E501", # line-too-long
+    "E722", # bare-except
+]
+
+[tool.ruff.lint.isort]
+force-single-line = true
+
+[too.ruff.format]
+docstring-code-format = true
+
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+isolated_build = true
+skipsdist = true
+envlist =
+    style
+    py39
+    py310
+    py311
+    py312
+    doc
+    coverage
+
+[testenv]
+allowlist_externals = poetry
+commands =
+    poetry install
+    poetry run pytest --showlocals --full-trace {posargs}
+
+[testenv:style]
+commands =
+    pip install pre-commit
+    pre-commit run --all-files
+
+[testenv:doc]
+commands =
+    poetry install --with doc --without dev
+    poetry run sphinx-build --builder html doc build/sphinx/html
+    poetry run sphinx-build --builder man doc build/sphinx/html
+
+[testenv:coverage]
+commands =
+    poetry install
+    poetry run pytest --cov --cov-fail-under=100 --cov-report term:skip-covered {posargs}
+    poetry run coverage html
+"""

scim2_client-0.1.0/scim2_client/__init__.py

@@ -0,0 +1,13 @@
+from .client import SCIMClient
+from .errors import SCIMClientError
+from .errors import UnexpectedContentFormat
+from .errors import UnexpectedContentType
+from .errors import UnexpectedStatusCode
+
+__all__ = [
+    "SCIMClient",
+    "SCIMClientError",
+    "UnexpectedStatusCode",
+    "UnexpectedContentType",
+    "UnexpectedContentFormat",
+]

scim2_client-0.1.0/scim2_client/client.py

@@ -0,0 +1,352 @@
+import json
+import json.decoder
+from typing import List
+from typing import Optional
+from typing import Tuple
+from typing import Type
+from typing import Union
+
+from httpx import Client
+from httpx import Response
+from pydantic import ValidationError
+from scim2_models import AnyResource
+from scim2_models import Error
+from scim2_models import ListResponse
+from scim2_models import PatchOp
+from scim2_models import SearchRequest
+
+from .errors import UnexpectedContentFormat
+from .errors import UnexpectedContentType
+from .errors import UnexpectedStatusCode
+
+BASE_HEADERS = {
+    "Accept": "application/scim+json",
+    "Content-Type": "application/scim+json",
+}
+
+
+class SCIMClient:
+    """An object that perform SCIM requests and validate responses."""
+
+    def __init__(self, client: Client, resource_types: Optional[Tuple[Type]] = None):
+        self.client = client
+        self.resource_types = resource_types or ()
+
+    def check_resource_type(self, resource_type):
+        if resource_type not in self.resource_types:
+            raise ValueError(f"Unknown resource type: '{resource_type}'")
+
+    def resource_endpoint(self, resource_type: Type):
+        return f"/{resource_type.__name__}s"
+
+    def check_response(
+        self,
+        response: Response,
+        expected_status_codes: List[int],
+        expected_type: Optional[Type] = None,
+    ):
+        if response.status_code not in expected_status_codes:
+            raise UnexpectedStatusCode(response)
+
+        # Interoperability considerations:  The "application/scim+json" media
+        # type is intended to identify JSON structure data that conforms to
+        # the SCIM protocol and schema specifications.  Older versions of
+        # SCIM are known to informally use "application/json".
+        # https://datatracker.ietf.org/doc/html/rfc7644.html#section-8.1
+
+        expected_response_content_types = ("application/scim+json", "application/json")
+        if response.headers.get("content-type") not in expected_response_content_types:
+            raise UnexpectedContentType(response)
+
+        # 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
+
+        if response.status_code in (204, 205):
+            response_payload = None
+
+        else:
+            try:
+                response_payload = response.json()
+            except json.decoder.JSONDecodeError as exc:
+                raise UnexpectedContentFormat(response) from exc
+
+        try:
+            return Error.model_validate(response_payload)
+        except ValidationError:
+            pass
+
+        if expected_type:
+            return expected_type.model_validate(response_payload)
+        return response_payload
+
+    def create(self, resource: AnyResource, **kwargs) -> Union[AnyResource, Error]:
+        """Perform a POST request to create, as defined in :rfc:`RFC7644 §3.3
+        <7644#section-3.3>`.
+
+        :param resource: The resource to create
+        :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.
+        """
+
+        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__)
+
+    def query(
+        self,
+        resource_type: Type,
+        id: Optional[str] = None,
+        search_request: Optional[SearchRequest] = None,
+        **kwargs,
+    ) -> Union[AnyResource, ListResponse[AnyResource], Error]:
+        """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_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 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)
+        payload = (
+            search_request.model_dump(
+                by_alias=True, exclude_none=True, exclude_unset=True, mode="json"
+            )
+            if search_request
+            else None
+        )
+
+        if not id:
+            expected_type = ListResponse[resource_type]
+            url = self.resource_endpoint(resource_type)
+
+        else:
+            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)
+
+    def query_all(
+        self,
+        search_request: Optional[SearchRequest] = None,
+        **kwargs,
+    ) -> Union[AnyResource, ListResponse[AnyResource], Error]:
+        """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 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.
+        """
+
+        # 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
+
+        payload = (
+            search_request.model_dump(
+                by_alias=True, exclude_none=True, exclude_unset=True, mode="json"
+            )
+            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,
+        ]
+
+        return self.check_response(
+            response, expected_status_codes, ListResponse[Union[self.resource_types]]
+        )
+
+    def search(
+        self,
+        search_request: Optional[SearchRequest] = None,
+        **kwargs,
+    ) -> Union[AnyResource, ListResponse[AnyResource], Error]:
+        """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 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.
+        """
+
+        payload = (
+            search_request.model_dump(
+                by_alias=True, exclude_none=True, exclude_unset=True, mode="json"
+            )
+            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]]
+        )
+
+    def delete(self, resource_type: Type, id: str, **kwargs) -> Optional[Error]:
+        """Perform a DELETE request to create, as defined in :rfc:`RFC7644 §3.6
+        <7644#section-3.6>`.
+
+        :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.
+        """
+
+        self.check_resource_type(resource_type)
+        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]:
+        """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 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.
+        """
+
+        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__)
+
+    def modify(
+        self, resource: AnyResource, op: PatchOp, **kwargs
+    ) -> Optional[AnyResource]:
+        raise NotImplementedError()

scim2_client-0.1.0/scim2_client/errors.py

@@ -0,0 +1,43 @@
+from httpx import Response
+
+
+class SCIMClientError(Exception):
+    def __init__(self, response: Response, *args, **kwargs):
+        self.response = response
+        super().__init__(*args, **kwargs)
+
+
+class UnexpectedStatusCode(SCIMClientError):
+    def __init__(
+        self,
+        response: Response,
+        *args,
+        **kwargs,
+    ):
+        message = kwargs.pop(
+            "message", f"Unexpected response status code: {response.status_code}"
+        )
+        super().__init__(response, message, *args, **kwargs)
+
+
+class UnexpectedContentType(SCIMClientError):
+    def __init__(
+        self,
+        response: Response,
+        *args,
+        **kwargs,
+    ):
+        content_type = response.headers.get("content-type", "")
+        message = kwargs.pop("message", f"Unexpected content type: {content_type}")
+        super().__init__(response, message, *args, **kwargs)
+
+
+class UnexpectedContentFormat(SCIMClientError):
+    def __init__(
+        self,
+        response: Response,
+        *args,
+        **kwargs,
+    ):
+        message = kwargs.pop("message", "Unexpected response content format")
+        super().__init__(response, message, *args, **kwargs)