feat: pass the ScimProvider in the validation/serialization context

Author: azmeuk

doc/changelog.rst

@@ -44,6 +44,15 @@ Added
   :class:`~scim2_models.ResponseParameters` a client sent, instead of its ``attributes`` and
   ``excludedAttributes`` spelled out one by one. A :class:`~scim2_models.SearchRequest` is one,
   so a server answering ``POST /.search`` passes the request it received. :issue:`141`
+- :meth:`~scim2_models.BaseModel.model_validate`,
+  :meth:`~scim2_models.BaseModel.model_validate_json`,
+  :meth:`~scim2_models.BaseModel.model_dump` and
+  :meth:`~scim2_models.BaseModel.model_dump_json` take a ``scim_provider`` and a ``scim_spc``: the
+  :class:`~scim2_models.ScimProvider` describing the service a payload belongs to, and the
+  :class:`~scim2_models.ServiceProviderConfig` its peer publishes. A ``with`` block opened on a
+  provider lends both, as it already lends its policy, and ``scim_spc`` wins over the
+  configuration the provider carries. Rules the specification makes conditional on a declared
+  capability read them. See :doc:`how-to/describe-a-scim-service`.
 - :meth:`~scim2_models.PatchOp.build_from` builds the patch turning one resource state into
   another. Only the attributes the wanted state names take part in the comparison, so what a peer
   maintains and the caller does not model survives the modification — which is what a PATCH

doc/how-to/describe-a-scim-service.rst

@@ -72,6 +72,42 @@ within which bounds (:rfc:`RFC7644 §4 <7644#section-4>`). Pass it alongside the
    >>> provider.config.filter.max_results
    200
 
+Read the description during a validation
+----------------------------------------
+
+A rule the specification makes conditional on a capability needs what the service declares, not
+only the payload. Name the provider at the call, and every validator the pass reaches sees it,
+down to a nested attribute:
+
+.. doctest::
+
+   >>> payload = {"schemas": [str(User.__schema__)], "userName": "bjensen"}
+   >>> user = User.model_validate(payload, scim_provider=provider)
+   >>> user.user_name
+   'bjensen'
+
+A server states it once per request instead, by opening a block on the provider. The block lends
+its policy the same way:
+
+.. doctest::
+
+   >>> with provider:
+   ...     user = User.model_validate(payload)
+
+A client holds the configuration of a peer as soon as it has queried ``/ServiceProviderConfig``,
+before it builds any provider. Pass it alone:
+
+.. doctest::
+
+   >>> user = User.model_validate(payload, scim_spc=config)
+
+``scim_spc`` also wins over the configuration a provider carries, so one provider answers peers
+that declare different capabilities. Both parameters are taken by
+:meth:`~scim2_models.BaseModel.model_validate`,
+:meth:`~scim2_models.BaseModel.model_validate_json`,
+:meth:`~scim2_models.BaseModel.model_dump` and
+:meth:`~scim2_models.BaseModel.model_dump_json`.
+
 Serve two variants of one resource
 ----------------------------------
 

scim2_models/base.py

@@ -43,6 +43,8 @@
 if TYPE_CHECKING:
     from scim2_models.messages.response_parameters import ResponseParameters
     from scim2_models.path import Path
+    from scim2_models.provider import ScimProvider
+    from scim2_models.resources.service_provider_config import ServiceProviderConfig
 
 
 def _short_attr_path(urn: str) -> str:
@@ -810,11 +812,15 @@ def _prepare_model_validate(
         cls,
         scim_ctx: Context | None = Context.DEFAULT,
         scim_policy: ScimPolicy | None = None,
+        scim_provider: "ScimProvider | None" = None,
+        scim_spc: "ServiceProviderConfig | None" = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         context = kwargs.setdefault("context", {})
         context.setdefault("scim", scim_ctx)
         context.setdefault("scim_policy", scim_policy)
+        context.setdefault("scim_provider", scim_provider)
+        context.setdefault("scim_spc", scim_spc)
         return kwargs
 
     @classmethod
@@ -823,15 +829,29 @@ def model_validate(
         *args: Any,
         scim_ctx: Context | None = Context.DEFAULT,
         scim_policy: ScimPolicy | None = None,
+        scim_provider: "ScimProvider | None" = None,
+        scim_spc: "ServiceProviderConfig | None" = None,
         **kwargs: Any,
     ) -> Self:
         """Validate SCIM payloads and generate model representation by using Pydantic :meth:`~pydantic.BaseModel.model_validate`.
 
         :param scim_ctx: The SCIM :class:`~scim2_models.Context` in which the validation happens.
         :param scim_policy: The :class:`~scim2_models.ScimPolicy` the validation
             runs under. Defaults to the strict reading of the specification.
+        :param scim_provider: The :class:`~scim2_models.ScimProvider` describing
+            the service the payload belongs to. Defaults to the provider of the
+            innermost open block, if any.
+        :param scim_spc: The
+            :class:`~scim2_models.ServiceProviderConfig` the peer publishes,
+            which overrides the one *scim_provider* carries.
         """
-        validate_kwargs = cls._prepare_model_validate(scim_ctx, scim_policy, **kwargs)
+        validate_kwargs = cls._prepare_model_validate(
+            scim_ctx,
+            scim_policy,
+            scim_provider=scim_provider,
+            scim_spc=scim_spc,
+            **kwargs,
+        )
         return super().model_validate(*args, **validate_kwargs)
 
     @classmethod
@@ -840,6 +860,8 @@ def model_validate_json(
         *args: Any,
         scim_ctx: Context | None = Context.DEFAULT,
         scim_policy: ScimPolicy | None = None,
+        scim_provider: "ScimProvider | None" = None,
+        scim_spc: "ServiceProviderConfig | None" = None,
         **kwargs: Any,
     ) -> Self:
         """Validate SCIM JSON payloads and generate model representation by using Pydantic :meth:`~pydantic.BaseModel.model_validate_json`.
@@ -850,9 +872,19 @@ def model_validate_json(
         :param scim_ctx: The SCIM :class:`~scim2_models.Context` in which the validation happens.
         :param scim_policy: The :class:`~scim2_models.ScimPolicy` the validation
             runs under. Defaults to the strict reading of the specification.
+        :param scim_provider: The :class:`~scim2_models.ScimProvider` describing
+            the service the payload belongs to. Defaults to the provider of the
+            innermost open block, if any.
+        :param scim_spc: The
+            :class:`~scim2_models.ServiceProviderConfig` the peer publishes,
+            which overrides the one *scim_provider* carries.
         """
         validate_kwargs = cls._prepare_model_validate(
-            scim_ctx, scim_policy=scim_policy, **kwargs
+            scim_ctx,
+            scim_policy=scim_policy,
+            scim_provider=scim_provider,
+            scim_spc=scim_spc,
+            **kwargs,
         )
         return super().model_validate_json(*args, **validate_kwargs)
 
@@ -862,11 +894,15 @@ def _prepare_model_dump(
         attributes: list["str | Path[Any]"] | None = None,
         excluded_attributes: list["str | Path[Any]"] | None = None,
         scim_policy: ScimPolicy | None = None,
+        scim_provider: "ScimProvider | None" = None,
+        scim_spc: "ServiceProviderConfig | None" = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         context = kwargs.setdefault("context", {})
         context.setdefault("scim", scim_ctx)
         context.setdefault("scim_policy", scim_policy)
+        context.setdefault("scim_provider", scim_provider)
+        context.setdefault("scim_spc", scim_spc)
 
         if scim_ctx:
             kwargs.setdefault("exclude_none", True)
@@ -925,6 +961,8 @@ def model_dump(
         attributes: list["str | Path[Any]"] | None = None,
         excluded_attributes: list["str | Path[Any]"] | None = None,
         scim_policy: ScimPolicy | None = None,
+        scim_provider: "ScimProvider | None" = None,
+        scim_spc: "ServiceProviderConfig | None" = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """Create a model representation that can be included in SCIM messages by using Pydantic :code:`BaseModel.model_dump`.
@@ -953,6 +991,12 @@ def model_dump(
         :param scim_policy: The :class:`~scim2_models.ScimPolicy` the
             serialization runs under. Defaults to the strict reading of the
             specification.
+        :param scim_provider: The :class:`~scim2_models.ScimProvider` describing
+            the service the payload belongs to. Defaults to the provider of the
+            innermost open block, if any.
+        :param scim_spc: The
+            :class:`~scim2_models.ServiceProviderConfig` the peer publishes,
+            which overrides the one *scim_provider* carries.
         """
         attributes, excluded_attributes = self._attribute_selection(
             response_parameters, attributes, excluded_attributes
@@ -962,6 +1006,8 @@ def model_dump(
             attributes=attributes,
             excluded_attributes=excluded_attributes,
             scim_policy=scim_policy,
+            scim_provider=scim_provider,
+            scim_spc=scim_spc,
             **kwargs,
         )
         if scim_ctx:
@@ -976,6 +1022,8 @@ def model_dump_json(
         attributes: list["str | Path[Any]"] | None = None,
         excluded_attributes: list["str | Path[Any]"] | None = None,
         scim_policy: ScimPolicy | None = None,
+        scim_provider: "ScimProvider | None" = None,
+        scim_spc: "ServiceProviderConfig | None" = None,
         **kwargs: Any,
     ) -> str:
         """Create a JSON model representation that can be included in SCIM messages by using Pydantic :code:`BaseModel.model_dump_json`.
@@ -1004,6 +1052,12 @@ def model_dump_json(
         :param scim_policy: The :class:`~scim2_models.ScimPolicy` the
             serialization runs under. Defaults to the strict reading of the
             specification.
+        :param scim_provider: The :class:`~scim2_models.ScimProvider` describing
+            the service the payload belongs to. Defaults to the provider of the
+            innermost open block, if any.
+        :param scim_spc: The
+            :class:`~scim2_models.ServiceProviderConfig` the peer publishes,
+            which overrides the one *scim_provider* carries.
         """
         attributes, excluded_attributes = self._attribute_selection(
             response_parameters, attributes, excluded_attributes
@@ -1013,6 +1067,8 @@ def model_dump_json(
             attributes=attributes,
             excluded_attributes=excluded_attributes,
             scim_policy=scim_policy,
+            scim_provider=scim_provider,
+            scim_spc=scim_spc,
             **kwargs,
         )
         return super().model_dump_json(*args, **dump_kwargs)

scim2_models/provider.py

@@ -2,6 +2,7 @@
 
 import operator
 from collections.abc import Iterable
+from contextvars import ContextVar
 from functools import cached_property
 from functools import reduce
 from types import TracebackType
@@ -10,6 +11,9 @@
 from typing import TypeVar
 from typing import cast
 
+from pydantic import SerializationInfo
+from pydantic import ValidationInfo
+
 from .annotations import Required
 from .policy import ScimPolicy
 from .resources.resource import Extension
@@ -60,6 +64,12 @@ def _schema_key(schema: Any) -> str:
 }
 
 
+_AMBIENT_PROVIDERS: ContextVar[tuple["ScimProvider", ...]] = ContextVar(
+    "scim2_models_providers", default=()
+)
+"""The providers of the blocks a call is running inside, innermost last."""
+
+
 class ScimProviderError(ValueError):
     """A provider cannot describe a coherent service.
 
@@ -224,7 +234,8 @@ def policy(self) -> ScimPolicy:
         return self._policy
 
     def __enter__(self) -> "ScimProvider":
-        """Make the policy of this provider the one the block runs under."""
+        """Make this provider, its configuration and its policy the ones the block runs under."""
+        _AMBIENT_PROVIDERS.set(_AMBIENT_PROVIDERS.get() + (self,))
         self._policy.__enter__()
         return self
 
@@ -234,8 +245,9 @@ def __exit__(
         exc_value: BaseException | None,
         traceback: TracebackType | None,
     ) -> None:
-        """Restore the policy the block interrupted."""
+        """Restore the provider and the policy the block interrupted."""
         self._policy.__exit__(exc_type, exc_value, traceback)
+        _AMBIENT_PROVIDERS.set(_AMBIENT_PROVIDERS.get()[:-1])
 
     @cached_property
     def schemas(self) -> tuple[Schema, ...]:
@@ -343,3 +355,35 @@ def from_discovery(
             config=config,
             policy=policy,
         )
+
+
+def _ambient_provider() -> "ScimProvider | None":
+    """Return the provider of the innermost open block, if any."""
+    providers = _AMBIENT_PROVIDERS.get()
+    return providers[-1] if providers else None
+
+
+def _provider(info: ValidationInfo | SerializationInfo) -> "ScimProvider | None":
+    """Return the provider a validation or a serialization runs under.
+
+    Passes that no call of ours started carry no context and fall back on the
+    provider of the innermost open block.
+    """
+    context = getattr(info, "context", None) or {}
+    return context.get("scim_provider") or _ambient_provider()
+
+
+def _spc(info: ValidationInfo | SerializationInfo) -> ServiceProviderConfig | None:
+    """Return the configuration the peer of a pass publishes, if it is known.
+
+    A configuration named at the call site wins over the one the provider
+    carries, so a single provider serves peers that declare different
+    capabilities.
+    """
+    context = getattr(info, "context", None) or {}
+    spc: ServiceProviderConfig | None = context.get("scim_spc")
+    if spc:
+        return spc
+
+    provider = _provider(info)
+    return provider.config if provider else None