feat: expose the value a search sorts a resource by

SearchRequest.sort_value returns the value that sort orders a resource by. A storage that pages by keyset can keep it to resume after that resource.

Author: azmeuk

doc/changelog.rst

@@ -1,6 +1,15 @@
 Changelog
 =========
 
+[0.13.0] - Unreleased
+---------------------
+
+Added
+^^^^^
+- :meth:`SearchRequest.sort_value <scim2_models.SearchRequest.sort_value>` returns the value
+  :meth:`~scim2_models.SearchRequest.sort` orders a resource by. A storage that pages by keyset
+  can resume after that resource.
+
 [0.12.1] - 2026-10-07
 ---------------------
 

scim2_models/messages/search_request.py

@@ -278,6 +278,30 @@ def sort_binding(self, model: type[BaseModel]) -> AttributeBinding | None:
         value_path = AttrPath(designated.attr, "value", designated.uri)
         return _resolve_attr_path(model, value_path, strict=False)
 
+    def sort_value(self, resource: ResourceT) -> Any:
+        """Return the value :meth:`sort` orders a resource by.
+
+        A storage that pages by keyset can keep it to resume after a resource.
+        It is a :class:`str` for strings and references, in the form the
+        :attr:`~scim2_models.ScimPolicy.comparison_key` of the policy gives.
+        It is a :class:`bool`, :class:`int`, :class:`float` or
+        :class:`~datetime.datetime` for the other SCIM types. A value of an
+        attribute with a custom Python type is returned unchanged.
+        :meth:`sort` puts the resources without a value last when ascending,
+        and first when descending.
+
+        >>> from scim2_models import SearchRequest, User
+        >>> SearchRequest(sort_by="userName").sort_value(User(user_name="BJensen"))
+        'bjensen'
+
+        :param resource: The resource to read the value from.
+        :returns: The value, or :data:`None` when :attr:`sort_by` is not set,
+            when the resource has no value, when its type does not declare the
+            attribute or cannot sort on it, or when the policy cannot prepare
+            the string.
+        """
+        return _sort_value(resource, self.sort_binding(type(resource)))
+
     def sort(self, resources: Iterable[ResourceT]) -> list[ResourceT]:
         """Order resources as :rfc:`RFC7644 §3.4.2.3 <7644#section-3.4.2.3>` describes.
 

tests/test_search_request.py

@@ -1,3 +1,5 @@
+from datetime import UTC
+from datetime import datetime
 from typing import Annotated
 
 import pytest
@@ -7,6 +9,7 @@
 from scim2_models import ComplexAttribute
 from scim2_models import EnterpriseUser
 from scim2_models import Group
+from scim2_models import Meta
 from scim2_models import Mutability
 from scim2_models import Resource
 from scim2_models import Returned
@@ -703,6 +706,48 @@ def test_sort_binding_is_none_when_the_model_cannot_sort_on_the_attribute(
     assert SearchRequest(sort_by=attribute).sort_binding(model) is None
 
 
+def test_sort_value_without_sort_by_is_none():
+    """There is nothing to order the resource by."""
+    assert SearchRequest().sort_value(User(user_name="bjensen")) is None
+
+
+def test_sort_value_is_the_string_sort_compares():
+    """A keyset storage resumes on the same form of the string as sort() orders by."""
+    request = SearchRequest(sort_by="userName")
+    assert request.sort_value(User(user_name="ÉMILE")) == "émile"
+
+
+def test_sort_value_reads_the_primary_entry_of_a_multivalued_attribute():
+    """RFC7644 §3.4.2.3 sorts on "the value of the primary attribute"."""
+    user = User(
+        user_name="bjensen",
+        emails=[
+            User.Emails(value="b@example.com"),
+            User.Emails(value="A@example.com", primary=True),
+        ],
+    )
+    assert SearchRequest(sort_by="emails").sort_value(user) == "a@example.com"
+
+
+def test_sort_value_keeps_the_type_of_a_non_string_value():
+    """A storage gets the boolean or the date as sort() compares it."""
+    when = datetime(2026, 10, 9, tzinfo=UTC)
+    user = User(user_name="bjensen", active=True, meta=Meta(last_modified=when))
+    assert SearchRequest(sort_by="active").sort_value(user) is True
+    assert SearchRequest(sort_by="meta.lastModified").sort_value(user) == when
+
+
+def test_sort_value_is_none_without_a_value():
+    """sort() puts such a resource last when ascending and first when descending."""
+    assert SearchRequest(sort_by="displayName").sort_value(User(user_name="b")) is None
+
+
+def test_sort_value_is_none_when_the_type_cannot_sort_on_the_attribute():
+    """A resource of a union whose type lacks the attribute is ordered as one without a value."""
+    request = SearchRequest[User | Group](sort_by="userName")
+    assert request.sort_value(Group(display_name="admins")) is None
+
+
 def ids(resources):
     """Return the ids of the resources, in their order."""
     return [resource.id for resource in resources]