doc: order resources by the entry a multi-valued sortBy picks

sort_resources read the primary flag off whatever get() returned, which holds
entries for sortBy=emails but projected sub-attributes for sortBy=emails.value,
so any path naming a sub-attribute raised an AttributeError. RFC7644 §3.4.2.3
picks the entry first, primary or else the first, and the sub-attribute is read
from it, which turns sortBy=emails into the case where that sub-attribute is the
value RFC7643 §2.4 reserves for it. A scalar entry is that value itself, and an
extension left unset holds none.

Author: azmeuk

doc/guides/_examples/integrations.py

@@ -8,7 +8,7 @@
 from scim2_models import AuthenticationScheme
 from scim2_models import Bulk
 from scim2_models import ChangePassword
-from scim2_models import CaseExact
+from scim2_models import ComplexAttribute
 from scim2_models import ETag
 from scim2_models import Filter
 from scim2_models import InvalidPathException
@@ -22,6 +22,7 @@
 from scim2_models import Sort
 from scim2_models import UniquenessException
 from scim2_models import User
+from scim2_models.filters import attribute_host
 
 # -- storage-start --
 records = {}
@@ -72,32 +73,58 @@ 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_by.get(resource, strict=False)
-        if isinstance(value, list):
-            # "resources are sorted by the value of the primary attribute, if
-            # any, or else the first value in the list, if any."
-            primary = next((each for each in value if each.primary), None)
-            entry = primary or (value[0] if value else None)
-            value = entry.value if entry else None
-        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
         # and first if descending", which reversing the whole key achieves.
         return (value is None, value if value is not None else "")
 
     return sorted(resources, key=key, reverse=descending)
+
+
+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 resolved: The attribute the ``sortBy`` designates.
+    """
+    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 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."
+        primary = next(
+            (entry for entry in entries if getattr(entry, "primary", None)), None
+        )
+        value = primary if primary is not None else (entries[0] if entries else None)
+        if sub_field_name is None and isinstance(value, ComplexAttribute):
+            # RFC7643 §2.4 holds the significant value of a complex entry in a
+            # ``value`` sub-attribute, where a scalar entry is the value itself.
+            sub_field_name = "value"
+
+    if value is None or sub_field_name is None:
+        return value
+    return getattr(value, sub_field_name, None)
 # -- sorting-end --
 
 

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.ResolvedAttribute` 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 the helper
@@ -85,6 +85,12 @@ follows: a string attribute is compared without its case unless it is annotated
 the value of its ``primary`` entry, or the first one; and a resource with no value for the
 attribute comes last when ascending, first when descending.
 
+The second is why the value is not read straight off the path. ``emails.value`` designates the
+value of *every* entry, where an order wants one value per resource, so ``sort_value`` picks
+the entry before reading the sub-attribute from it. That makes ``sortBy=emails`` the same query
+as ``sortBy=emails.value``, :rfc:`RFC7643 §2.4 <7643#section-2.4>` holding the significant value
+of a complex entry in its ``value`` sub-attribute, where a scalar entry is that value itself.
+
 .. literalinclude:: _examples/integrations.py
    :language: python
    :caption: Ordering a collection

tests/test_doc_examples.py

@@ -11,12 +11,14 @@
 from datetime import timezone  # noqa: E402
 
 from doc.guides._examples.integrations import sort_resources  # noqa: E402
+from doc.guides._examples.integrations import sort_value  # noqa: E402
 from doc.guides._examples.sqlalchemy_example import EmailRecord  # noqa: E402
 from doc.guides._examples.sqlalchemy_example import GroupRecord  # noqa: E402
 from doc.guides._examples.sqlalchemy_example import UserRecord  # noqa: E402
 from doc.guides._examples.sqlalchemy_example import create_session_factory  # noqa: E402
 from doc.guides._examples.sqlalchemy_example import query_users  # noqa: E402
 from doc.guides._examples.sqlalchemy_example import to_scim_user  # noqa: E402
+from scim2_models import EnterpriseUser  # noqa: E402
 from scim2_models import InvalidFilterException  # noqa: E402
 from scim2_models import InvalidPathException  # noqa: E402
 from scim2_models import ScimFilter  # noqa: E402
@@ -218,6 +220,116 @@ def sorted_names(query):
     ]
 
 
+def sorting_users(emails_by_id):
+    """Build users carrying the emails each id maps to."""
+    return [
+        User[EnterpriseUser](id=user_id, user_name=user_id, emails=emails)
+        for user_id, emails in emails_by_id.items()
+    ]
+
+
+def sorting_order(resources, attribute, sort_order=None):
+    """Return the ids a ``sortBy`` puts the resources in."""
+    request = SearchRequest[User[EnterpriseUser]](
+        sort_by=attribute, sort_order=sort_order
+    )
+    return [
+        resource.id
+        for resource in sort_resources(resources, request.sort_by, sort_order)
+    ]
+
+
+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.resolve())
+
+
+@pytest.mark.parametrize("attribute", ["emails", "emails.value"])
+def test_sorting_reads_the_primary_entry_of_a_multivalued_attribute(attribute):
+    """The entry marked ``primary`` decides the order, not the first one.
+
+    Ordering on the first entry instead would put ``1`` ahead of ``2``, since
+    ``a@example.com`` precedes ``m@example.com``.
+    """
+    resources = sorting_users(
+        {
+            "1": [
+                User.Emails(value="a@example.com"),
+                User.Emails(value="z@example.com", primary=True),
+            ],
+            "2": [User.Emails(value="m@example.com")],
+        }
+    )
+    assert sorting_order(resources, attribute) == ["2", "1"]
+
+
+def test_sorting_reads_a_sub_attribute_from_the_primary_entry():
+    """A path naming a sub-attribute reads it from the entry the order picked.
+
+    Reading the first entry instead would put ``2`` ahead of ``1``, ``other``
+    preceding ``work``.
+    """
+    resources = sorting_users(
+        {
+            "1": [
+                User.Emails(value="a@example.com", type="work"),
+                User.Emails(value="z@example.com", type="home", primary=True),
+            ],
+            "2": [User.Emails(value="m@example.com", type="other")],
+        }
+    )
+    assert sorting_order(resources, "emails.type") == ["1", "2"]
+
+
+def test_sorting_falls_back_to_the_first_entry_without_a_primary():
+    """An attribute marking no entry primary is ordered by its first one."""
+    resources = sorting_users(
+        {
+            "1": [
+                User.Emails(value="z@example.com"),
+                User.Emails(value="a@example.com"),
+            ],
+            "2": [User.Emails(value="m@example.com")],
+        }
+    )
+    assert sorting_order(resources, "emails.value") == ["2", "1"]
+
+
+def test_sorting_an_unassigned_multivalued_attribute():
+    """A resource carrying no entry comes last ascending and first descending."""
+    resources = sorting_users({"1": None, "2": [User.Emails(value="m@example.com")]})
+    assert sorting_order(resources, "emails.value") == ["2", "1"]
+    assert sorting_order(resources, "emails.value", "descending") == ["1", "2"]
+
+
+def test_sorting_a_scalar_multivalued_attribute_reads_the_entry_itself():
+    """A scalar entry is the value, where a complex one holds it in a sub-attribute."""
+    resource = sorting_users({"1": [User.Emails(value="m@example.com")]})[0]
+    assert sorting_key(resource, "schemas") == User.__schema__
+
+
+def test_sorting_an_attribute_of_an_extension_left_unset():
+    """An extension that is not set holds no value to order by."""
+    resource = sorting_users({"1": None})[0]
+    urn = "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department"
+    assert sorting_key(resource, urn) is None
+
+    resource[EnterpriseUser] = EnterpriseUser(department="Tour Operations")
+    assert sorting_key(resource, urn) == "Tour Operations"
+
+
+def test_sorting_a_request_that_named_no_resource_type():
+    """The helper orders by a resolved attribute, which an unparameterised request has none of.
+
+    A request naming the type it serves cannot reach here: an attribute the
+    model does not declare is refused when the request is built.
+    """
+    resources = sorting_users({"1": None})
+    with pytest.raises(InvalidPathException):
+        sort_resources(resources, SearchRequest(sort_by="userName").sort_by)
+
+
 def test_django_example_smoke():
     from django.conf import settings