refactor: let Path.resolve alone answer for the attribute a path designates

Path carried six properties reading the attribute it designates, written before
AttributeBinding existed and with its words turned around: path.model named the
type holding the sub-attribute where the binding names the one holding the
head. Five of them go, the binding carrying each under a target_ name, and
get_annotation joins it. Path.model keeps the one answer no binding gives, the
model a resource root or a bare schema URN designates, and answers None for a
path that names an attribute.

Author: azmeuk

doc/changelog.rst

@@ -30,6 +30,11 @@ Added
 
 Changed
 ^^^^^^^
+- :attr:`Path.model <scim2_models.Path.model>` answers the model a path designates when it names
+  no attribute: the bound model for the resource root, the resource or the extension for a bare
+  schema URN, and :data:`None` for a path naming an attribute. It used to answer the type holding
+  the attribute, which :meth:`Path.resolve <scim2_models.Path.resolve>` now does through
+  :class:`~scim2_models.AttributeBinding`.
 - :attr:`SearchRequest.sort_by <scim2_models.SearchRequest.sort_by>` is resolved against the
   model a parameterised request names, and an attribute none of its resource types declares
   answers ``invalidPath`` at validation time instead of being carried to the endpoint. Where an
@@ -44,6 +49,12 @@ Changed
 
 Removed
 ^^^^^^^
+- ``Path.field_name``, ``Path.field_type``, ``Path.is_multivalued``, ``Path.get_annotation`` and
+  ``Path.urn``. They read the attribute a path designates with the words of
+  :class:`~scim2_models.AttributeBinding` turned around, ``field_name`` naming the sub-attribute
+  where the binding names the head. :meth:`Path.resolve <scim2_models.Path.resolve>` answers the
+  binding, which carries them as ``target_field_name``, ``target_type``,
+  ``target_is_multivalued``, :meth:`~scim2_models.AttributeBinding.get_annotation` and ``urn``.
 - ``Path.is_prefix_of`` and ``Path.has_prefix``. They compared the text of two paths, which
   anything between brackets defeated, and answered differently from the comparison
   :attr:`~scim2_models.ResponseParameters.attributes` and

doc/guides/_examples/integrations.py

@@ -9,7 +9,6 @@
 from scim2_models import Bulk
 from scim2_models import ChangePassword
 from scim2_models import ComplexAttribute
-from scim2_models import CaseExact
 from scim2_models import ETag
 from scim2_models import Filter
 from scim2_models import InvalidPathException
@@ -23,6 +22,7 @@
 from scim2_models import Sort
 from scim2_models import UniquenessException
 from scim2_models import User
+from scim2_models.path import attribute_host
 
 # -- storage-start --
 records = {}
@@ -73,19 +73,19 @@ def sort_resources(resources, sort_by, sort_order=None):
     :param sort_order: The ``sortOrder`` query parameter, ascending by default.
     :raises InvalidPathException: If the attribute is unknown.
     """
-    if sort_by.field_name is None:
+    resolved = sort_by.resolve()
+    if resolved is None:
         raise InvalidPathException(
             path=str(sort_by), detail=f"Cannot sort on {sort_by!r}"
         )
 
-    # "String type attributes are case insensitive by default, unless the
-    # attribute type is defined as a case-exact string."
-    case_exact = sort_by.model.get_field_annotation(sort_by.field_name, CaseExact)
     descending = sort_order == SearchRequest.SortOrder.descending
 
     def key(resource):
-        value = sort_value(resource, sort_by)
-        if isinstance(value, str) and not case_exact:
+        value = sort_value(resource, resolved)
+        # "String type attributes are case insensitive by default, unless the
+        # attribute type is defined as a case-exact string."
+        if isinstance(value, str) and not resolved.case_exact:
             value = value.casefold()
         # "if there is no data for the specified sortBy value, they are sorted
         # via the sortOrder parameter, i.e., they are ordered last if ascending
@@ -95,23 +95,21 @@ def key(resource):
     return sorted(resources, key=key, reverse=descending)
 
 
-def sort_value(resource, sort_by):
+def sort_value(resource, resolved):
     """Return the single value a resource is ordered by.
 
     A path crossing a multi-valued attribute designates the sub-attribute of
     every entry, where an order needs one value per resource, so the entry is
     picked first and the sub-attribute read from it.
 
     :param resource: The resource to read.
-    :param sort_by: The ``sortBy`` query parameter, resolved by its request.
+    :param resolved: The attribute the ``sortBy`` designates.
     """
-    sub_field_name = sort_by.field_name if len(sort_by.parts) > 1 else None
-    attribute = sort_by
-    if sub_field_name is not None:
-        attribute = type(sort_by)(str(sort_by).rsplit(".", 1)[0])
-    value = attribute.get(resource, strict=False)
+    host = attribute_host(resource, resolved)
+    value = None if host is None else getattr(host, resolved.field_name, None)
+    sub_field_name = resolved.sub_field_name
 
-    if attribute.is_multivalued:
+    if resolved.is_multivalued:
         entries = value or []
         # "resources are sorted by the value of the primary attribute, if any,
         # or else the first value in the list, if any."

doc/guides/index.rst

@@ -75,8 +75,8 @@ Ordering and paging collections
 A collection endpoint answers the ``sortBy``, ``sortOrder``, ``startIndex`` and ``count``
 parameters of :rfc:`RFC7644 §3.4.2 <7644#section-3.4.2>`. Naming the resource type the endpoint
 serves, with :class:`~scim2_models.SearchRequest`\ [:class:`~scim2_models.User`], resolves
-:attr:`~scim2_models.SearchRequest.sort_by` against that model, so the helper below reads
-:attr:`Path.field_name <scim2_models.Path.field_name>` instead of the attribute name a client
+:attr:`~scim2_models.SearchRequest.sort_by` against that model, so the helper below works from
+the :class:`~scim2_models.AttributeBinding` it designates instead of from the name a client
 spelled.
 
 :rfc:`RFC7644 §3.4.2.3 <7644#section-3.4.2.3>` decides the order in three ways, and the helper

scim2_models/messages/search_request.py

@@ -92,7 +92,7 @@ def _resolvable_sort_by(cls, value: Any) -> Any:
         # Parameterising the request names the resource types the endpoint
         # serves, which is what makes an attribute none of them declares a
         # client error rather than something to resolve later.
-        if value is not None and value.models and value.field_name is None:
+        if value is not None and value.models and value.resolve() is None:
             raise InvalidPathException(
                 path=str(value), detail=f"Cannot sort on {str(value)!r}"
             ).as_pydantic_error()

scim2_models/path/path.py

@@ -57,6 +57,33 @@ def _scim_name(model: type[BaseModel], field_name: str) -> str:
 
 
 class Path(_BoundToModels, _Expression, Generic[ResourceT]):
+    """A SCIM attribute path, as defined at :rfc:`RFC7644 §3.5.2 <7644#section-3.5.2>`.
+
+    A path *is* the string it was built from, and designates one of three
+    things:
+
+    - a model, when the path is ``""`` (the resource root) or a bare schema
+      URN, accessible with the :attr:`model` property;
+    - an attribute, such as ``userName`` or ``name.familyName``, accessible
+      with the :meth:`resolve` method as an :class:`~scim2_models.AttributeBinding`;
+    - some values of a multi-valued attribute, when the path selects them as in
+      ``emails[type eq "work"]``: the :attr:`value_filter` property holds the
+      filter, and the :meth:`resolve` method still answers for the attribute
+      they belong to.
+
+    Syntax is checked on creation. Resolving attribute names requires a model
+    to resolve them against, bound with a parameterised type such as
+    ``Path[User]``. The :meth:`get`, :meth:`set` and :meth:`delete` methods
+    read and write a resource through the path.
+
+    On Python 3.14, a path can be written as a t-string, whose interpolated
+    values are quoted as :meth:`ScimFilter.quote <scim2_models.ScimFilter.quote>`
+    does. Another path, or a :class:`~scim2_models.ScimFilter`, is inserted
+    as it stands::
+
+        Path[Group](t"members[value eq {member_id}]")
+    """
+
     _ast: "PathNode | None" = None
     """The parsed path, kept once :attr:`ast` has computed it."""
 
@@ -234,13 +261,24 @@ def value_filter(self) -> "FilterNode | None":
         value_path = self._as_value_path()
         return None if value_path is None else value_path.val_filter
 
-    def _designated_model(self) -> type[BaseModel] | None:
-        """Return the model this path designates when it names no attribute.
+    @property
+    def model(self) -> type[BaseModel] | None:
+        """The model this path designates, when it names no attribute.
+
+        The resource root designates the bound model, and a bare schema URN
+        the resource or the extension it is the schema of. A path naming an
+        attribute designates a model through none of them, and answers
+        :data:`None`: :meth:`resolve` tells which attribute it is.
 
-        The resource root designates the bound model, and a bare schema URN the
-        model it is the schema of, among the bound models and their extensions.
-        Neither can go through attribute resolution, since neither names an
-        attribute.
+        >>> from scim2_models import EnterpriseUser, Path, User
+        >>> Path[User]("").model is User
+        True
+        >>> Path[User[EnterpriseUser]](
+        ...     EnterpriseUser.__schema__
+        ... ).model is EnterpriseUser
+        True
+        >>> Path[User]("userName").model is None
+        True
         """
         if not self.__scim_models__:
             return None
@@ -256,18 +294,16 @@ def _designated_model(self) -> type[BaseModel] | None:
     def resolve(self) -> "AttributeBinding | None":
         """Bind this path to the attribute it designates on the bound model.
 
-        This is the single resolution the model-aware properties are built on.
-
         :returns: The resolved attribute, or :data:`None` when the path is
             unbound, designates a model rather than an attribute, or names an
             attribute the model does not declare.
         """
         model = self._resolving_model()
-        if model is None or self._designated_model() is not None:
+        if model is None or self.model is not None:
             return None
 
         # A path that designates no attribute has already returned above,
-        # since _designated_model answers for the resource root.
+        # since the model property answers for the resource root.
         designated = self._designated_attr_path()
         assert designated is not None
 
@@ -283,93 +319,6 @@ def models(self) -> tuple[type[BaseModel], ...]:
         """
         return self.__scim_models__
 
-    @property
-    def model(self) -> type[BaseModel] | None:
-        """The model holding the attribute this path designates.
-
-        Requires the Path to be bound to a model type via ``Path[Model]``.
-        Returns None if the path is unbound or invalid.
-
-        For "name.familyName" on Path[User], returns Name.
-        For "userName" on Path[User], returns User.
-        """
-        if (designated := self._designated_model()) is not None:
-            return designated
-
-        resolved = self.resolve()
-        return resolved.target_model if resolved is not None else None
-
-    @property
-    def field_name(self) -> str | None:
-        """The Python attribute name (snake_case) for this path.
-
-        Requires the Path to be bound to a model type via ``Path[Model]``.
-        Returns None if the path is unbound, invalid, or designates a model
-        rather than one of its attributes.
-
-        For "name.familyName" on Path[User], returns "family_name".
-        For "userName" on Path[User], returns "user_name".
-        """
-        resolved = self.resolve()
-        return resolved.target_field_name if resolved is not None else None
-
-    @property
-    def field_type(self) -> type | None:
-        """The Python type of the field this path points to.
-
-        Annotated types are unwrapped, so a ``binary`` attribute declared as
-        ``Base64Bytes`` reports :class:`bytes`.
-
-        For "userName" on Path[User], returns str.
-        For "name" on Path[User], returns Name.
-        For "emails" on Path[User], returns Email.
-        """
-        resolved = self.resolve()
-        return resolved.target_type if resolved is not None else None
-
-    @property
-    def is_multivalued(self) -> bool | None:
-        """Whether this path points to a multi-valued attribute.
-
-        For "emails" on Path[User], returns True.
-        For "emails.value" on Path[User], returns False, as the path
-        designates one value per entry.
-        """
-        resolved = self.resolve()
-        return resolved.target_is_multivalued if resolved is not None else None
-
-    def get_annotation(self, annotation_type: type) -> Any:
-        """Get annotation value for this path's field.
-
-        :param annotation_type: The annotation class (e.g., Required, Mutability).
-        :returns: The annotation value, or None when the path designates no
-            attribute.
-
-        For "userName" on Path[User] with Required, returns Required.true.
-        """
-        resolved = self.resolve()
-        if resolved is None or resolved.target_model is None:
-            return None
-        return resolved.target_model.get_field_annotation(
-            resolved.target_field_name, annotation_type
-        )
-
-    @property
-    def urn(self) -> str | None:
-        """The fully qualified URN for this path.
-
-        Requires the Path to be bound to a model type via ``Path[Model]``.
-        Returns None if the path is unbound or invalid.
-
-        For "userName" on Path[User], returns
-        "urn:ietf:params:scim:schemas:core:2.0:User:userName".
-        """
-        if (designated := self._designated_model()) is not None:
-            return getattr(designated, "__schema__", None) or None
-
-        resolved = self.resolve()
-        return resolved.urn if resolved is not None else None
-
     def _as_value_path(self) -> ValuePath | None:
         """Normalise a value-selecting path into a single representation.
 

scim2_models/path/resolution.py

@@ -108,6 +108,22 @@ def target_is_multivalued(self) -> bool | None:
             return None
         return model.get_field_multiplicity(self.target_field_name)
 
+    def get_annotation(self, annotation_type: type) -> Any:
+        """Return an annotation of the attribute the path designates.
+
+        The sub-attribute answers when the path names one, the head attribute
+        otherwise, so ``emails.value`` reports the annotations of ``value``.
+
+        :param annotation_type: The annotation class, such as ``Mutability``.
+        :returns: The annotation value, or :data:`None` when the attribute
+            carries none, or when the head attribute holds no sub-attribute to
+            answer for.
+        """
+        model = self.target_model
+        if model is None:
+            return None
+        return model.get_field_annotation(self.target_field_name, annotation_type)
+
     def nested_in(self, urn: str) -> "AttributeBinding":
         """Return the same attribute, qualified by the URN it was resolved under.
 

tests/test_doc_examples.py

@@ -261,7 +261,7 @@ def sorting_order(resources, attribute, sort_order=None):
 def sorting_key(resource, attribute):
     """Return the single value a ``sortBy`` orders a resource by."""
     request = SearchRequest[User[EnterpriseUser]](sort_by=attribute)
-    return sort_value(resource, request.sort_by)
+    return sort_value(resource, request.sort_by.resolve())
 
 
 @pytest.mark.parametrize("attribute", ["emails", "emails.value"])

tests/test_dynamic_resources.py

@@ -2888,7 +2888,7 @@ def test_a_model_built_at_runtime_is_collected_once_it_is_dropped():
 
     # The assertions are made on values that do not name the model, since
     # pytest keeps the operands of an assertion for as long as the test runs.
-    bound = Path[Model]("label").field_name == "label"
+    bound = Path[Model]("label").resolve().target_field_name == "label"
     matched = ScimFilter[Model]('label eq "x"').match(Model(label="x"))
     assert bound
     assert matched

tests/test_filter_semantics.py

@@ -983,6 +983,7 @@ def test_the_model_of_a_sub_attribute_on_a_simple_attribute_is_unknown():
     )
     assert resolved.target_model is None
     assert resolved.target_is_multivalued is None
+    assert resolved.get_annotation(Required) is None
 
 
 def test_an_extension_attribute_read_from_the_extension_itself():