scim2-client 0.3.3__tar.gz → 0.4.0__tar.gz

{scim2_client-0.3.3 → scim2_client-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: scim2-client
-Version: 0.3.3
+Version: 0.4.0
 Summary: Pythonically build SCIM requests and parse SCIM responses
 Project-URL: documentation, https://scim2-client.readthedocs.io
 Project-URL: repository, https://github.com/python-scim/scim2-client
@@ -234,7 +234,7 @@ Description-Content-Type: text/markdown
 A SCIM client Python 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.
-You can use whatever request engine you prefer to perform network requests, but scim2-models comes with [httpx](https://github.com/encode/httpx) support.
+You can use whatever request engine you prefer to perform network requests, but scim2-client comes with [httpx](https://github.com/encode/httpx) support.
 
 It aims to be used in SCIM client applications, or in unit tests for SCIM server applications.
 
@@ -253,21 +253,24 @@ pip install scim2-client[httpx]
 
 ## 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.
+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 import Client
-from scim2_models import User, EnterpriseUser, Group, Error
+from scim2_models import Error
 from scim2_client.engines.httpx import SyncSCIMClient
 
 client = Client(base_url="https://auth.example/scim/v2", headers={"Authorization": "Bearer foobar"})
-scim = SyncSCIMClient(client, resource_types=(User[EnterpriseUser], Group))
+scim = SyncSCIMClient(client)
+scim.discover()
+User = scim.get_resource_model("User")
 
 # Query resources
-user = scim.query(User[EnterpriseUser], "2819c223-7f76-453a-919d-413861904646")
+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

{scim2_client-0.3.3 → scim2_client-0.4.0}/README.md

@@ -3,7 +3,7 @@
 A SCIM client Python 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.
-You can use whatever request engine you prefer to perform network requests, but scim2-models comes with [httpx](https://github.com/encode/httpx) support.
+You can use whatever request engine you prefer to perform network requests, but scim2-client comes with [httpx](https://github.com/encode/httpx) support.
 
 It aims to be used in SCIM client applications, or in unit tests for SCIM server applications.
 
@@ -22,21 +22,24 @@ pip install scim2-client[httpx]
 
 ## 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.
+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 import Client
-from scim2_models import User, EnterpriseUser, Group, Error
+from scim2_models import Error
 from scim2_client.engines.httpx import SyncSCIMClient
 
 client = Client(base_url="https://auth.example/scim/v2", headers={"Authorization": "Bearer foobar"})
-scim = SyncSCIMClient(client, resource_types=(User[EnterpriseUser], Group))
+scim = SyncSCIMClient(client)
+scim.discover()
+User = scim.get_resource_model("User")
 
 # Query resources
-user = scim.query(User[EnterpriseUser], "2819c223-7f76-453a-919d-413861904646")
+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

{scim2_client-0.3.3 → scim2_client-0.4.0}/doc/changelog.rst

@@ -1,6 +1,20 @@
 Changelog
 =========
 
+[0.4.0] - 2024-12-02
+--------------------
+
+.. warning::
+
+    This version comes with breaking changes:
+
+    - :class:`~scim2_client.SCIMClient` takes a mandatory :paramref:`~scim2_client.SCIMClient.resource_types` parameter.
+
+Added
+^^^^^
+- Implement :meth:`~scim2_client.SCIMClient.register_naive_resource_types`.
+- Implement :meth:`~scim2_client.BaseSyncSCIMClient.discover` methods.
+
 [0.3.3] - 2024-11-29
 --------------------
 
@@ -14,9 +28,9 @@ Added
 
 Added
 ^^^^^
-- Implement :class:`~scim2_client.BaseSCIMClient` :paramref:`~scim2_client.BaseSCIMClient.check_request_payload`,
-  :paramref:`~scim2_client.BaseSCIMClient.check_response_payload` and
-  :paramref:`~scim2_client.BaseSCIMClient.raise_scim_errors` paramibutes,
+- Implement :class:`~scim2_client.SCIMClient` :paramref:`~scim2_client.SCIMClient.check_request_payload`,
+  :paramref:`~scim2_client.SCIMClient.check_response_payload` and
+  :paramref:`~scim2_client.SCIMClient.raise_scim_errors` paramibutes,
   to keep the same values for all the requests.
 
 [0.3.1] - 2024-11-29

{scim2_client-0.3.3 → scim2_client-0.4.0}/doc/tutorial.rst

@@ -7,25 +7,70 @@ Initialization
 scim2-client depends on request engines such as `httpx <https://github.com/encode/httpx>`_ to perform network requests.
 This tutorial demonstrate how to use scim2-client with httpx, and suppose you have installed the `httpx` extra for example with ``pip install scim2-models[httpx]``.
 
-As a start you will need to instantiate a httpx :code:`Client` object that you can parameter as your will, and then pass it to a :class:`SCIM client <scim2_client.BaseSCIMClient>` object.
+As a start you will need to instantiate a httpx :code:`Client` object that you can parameter as your will, and then pass it to a :class:`~scim2_client.SCIMClient` object.
 In addition to your SCIM server root endpoint, you will probably want to provide some authorization headers through the httpx :code:`Client` :code:`headers` parameter:
 
 .. code-block:: python
 
     from httpx import Client
-    from scim2_models import User, EnterpriseUserUser, Group
     from scim2_client.engines.httpx import SyncSCIMClient
 
-    client = Client(base_url="https://auth.example/scim/v2", headers={"Authorization": "Bearer foobar"})
-    scim = SyncSCIMClient(client, resource_models=(User[EnterpriseUser], Group))
+    client = Client(
+        base_url="https://auth.example/scim/v2",
+        headers={"Authorization": "Bearer foobar"},
+    )
+    scim = SyncSCIMClient(client)
 
-You need to give to indicate to :class:`~scim2_client.BaseSCIMClient` all the different :class:`~scim2_models.Resource` types that you will need to manipulate with the :code:`resource_models` parameter.
-This is needed so scim2-client will be able to guess which resource type to instante when an arbitrary payload is met.
+You need to give to indicate to :class:`~scim2_client.SCIMClient` all the different :class:`~scim2_models.Resource` models that you will need to manipulate, and the matching :class:`~scim2_models.ResourceType` objects to let the client know where to look for resources on the server.
 
-.. todo::
+You can either provision those objects manually or automatically.
 
-    We plan to implement the automatic discovery of SCIM server resources,
-    so they can dynamically be used without explicitly passing them with the :code:`resource_models` parameter.
+Automatic provisioning
+~~~~~~~~~~~~~~~~~~~~~~
+
+The easiest way is to let the client discover what configuration and resources are available on the server.
+The :meth:`~scim2_client.BaseSyncSCIMClient.discover` method looks for the server :class:`~scim2_models.ServiceProviderConfig`, :class:`~scim2_models.Schema` and :class:`~scim2_models.ResourceType` endpoints,
+and dynamically generate local Python models based on those schemas.
+They are then available to use with :meth:`~scim2_client.SCIMClient.get_resource_model`.
+
+.. code-block:: python
+    :caption: Dynamically discover models from the server
+
+    scim.discover()
+    User = scim.get_resource_model("User")
+    EnterpriseUser = User.get_extension_model("EnterpriseUser")
+
+Manual provisioning
+~~~~~~~~~~~~~~~~~~~
+To manually register models and resource types, you can simply use the :paramref:`~scim2_client.SCIMClient.resource_models` and :paramref:`~scim2_client.SCIMClient.resource_types` arguments.
+
+
+.. code-block:: python
+    :caption: Manually registering models and resource types
+
+    from scim2_models import User, EnterpriseUserUser, Group, ResourceType
+    scim = SyncSCIMClient(
+        client,
+        resource_models=[User[EnterpriseUser], Group],
+        resource_types=[ResourceType(id="User", ...), ResourceType(id="Group", ...)],
+    )
+
+.. tip::
+
+   If you know that all the resources are hosted at regular server endpoints
+   (for instance `/Users` for :class:`~scim2_models.User` etc.),
+   you can skip passing the :class:`~scim2_models.ResourceType` objects by hand,
+   and simply call :meth:`~scim2_client.SCIMClient.register_naive_resource_types`.
+
+    .. code-block:: python
+        :caption: Manually registering models and resource types
+
+        from scim2_models import User, EnterpriseUserUser, Group, ResourceType
+        scim = SyncSCIMClient(
+            client,
+            resource_models=[User[EnterpriseUser], Group],
+        )
+        scim.register_naive_resource_types()
 
 Performing actions
 ==================
@@ -60,20 +105,20 @@ Have a look at the :doc:`reference` to see usage examples and the exhaustive set
 Request and response validation
 ===============================
 
-By default, the data passed to the :class:`SCIM client <scim2_client.BaseSCIMClient>` as well as the server response will be validated against the SCIM specifications, and will raise an error if they don't respect them.
+By default, the data passed to the :class:`SCIM client <scim2_client.SCIMClient>` as well as the server response will be validated against the SCIM specifications, and will raise an error if they don't respect them.
 However sometimes you want to accept invalid inputs and outputs.
 To achieve this, all the methods provide the following parameters, all are :data:`True` by default:
 
-- :paramref:`~scim2_client.BaseSCIMClient.check_request_payload`:
+- :paramref:`~scim2_client.SCIMClient.check_request_payload`:
   If :data:`True` (the default) a :class:`~pydantic.ValidationError` will be raised if the input does not respect the SCIM standard.
   If :data:`False`, input is expected to be a :data:`dict` that will be passed as-is in the request.
-- :paramref:`~scim2_client.BaseSCIMClient.check_response_payload`:
+- :paramref:`~scim2_client.SCIMClient.check_response_payload`:
   If :data:`True` (the default) a :class:`~pydantic.ValidationError` will be raised if the server response does not respect the SCIM standard.
   If :data:`False` the server response is returned as-is.
 - :code:`expected_status_codes`: The list of expected status codes in the response.
   If :data:`None` any status code is accepted.
   If an unexpected status code is returned, a :class:`~scim2_client.errors.UnexpectedStatusCode` exception is raised.
-- :paramref:`~scim2_client.BaseSCIMClient.raise_scim_errors`: If :data:`True` (the default) and the server returned an :class:`~scim2_models.Error` object, a :class:`~scim2_client.SCIMResponseErrorObject` exception will be raised.
+- :paramref:`~scim2_client.SCIMClient.raise_scim_errors`: If :data:`True` (the default) 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.
 
 
@@ -95,7 +140,7 @@ Currently those engines are shipped:
   It takes a WSGI app and directly execute the server code instead of performing real HTTP requests.
   This is faster in unit test suites, and helpful to catch the server exceptions.
 
-You can easily implement your own engine by inheriting from :class:`~scim2_client.BaseSCIMClient`.
+You can easily implement your own engine by inheriting from :class:`~scim2_client.SCIMClient`.
 
 Additional request parameters
 =============================

{scim2_client-0.3.3 → scim2_client-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "scim2-client"
-version = "0.3.3"
+version = "0.4.0"
 description = "Pythonically build SCIM requests and parse SCIM responses"
 authors = [{name="Yaal Coop", email="contact@yaal.coop"}]
 license = {file = "LICENSE.md"}
@@ -151,6 +151,7 @@ commands = [
 ]
 
 [tool.tox.env.minversions]
+runner = "uv-venv-lock-runner"
 uv_resolution = "lowest-direct"
 
 [tool.tox.env.doc]

{scim2_client-0.3.3 → scim2_client-0.4.0}/scim2_client/__init__.py

@@ -1,5 +1,5 @@
-from .client import BaseSCIMClient
 from .client import BaseSyncSCIMClient
+from .client import SCIMClient
 from .errors import RequestNetworkError
 from .errors import RequestPayloadValidationError
 from .errors import ResponsePayloadValidationError
@@ -12,7 +12,7 @@ from .errors import UnexpectedContentType
 from .errors import UnexpectedStatusCode
 
 __all__ = [
-    "BaseSCIMClient",
+    "SCIMClient",
     "BaseSyncSCIMClient",
     "SCIMClientError",
     "SCIMRequestError",