doc: sort the SQLAlchemy example with sort_binding

The example resolved sortBy with Path.resolve, so it needed a request bound to User. With sort_binding, a request bound to a union or to no type sorts the same way. Attributes that users cannot be sorted on are refused.

Author: azmeuk

doc/integrations/_examples/sqlalchemy_example.py

@@ -300,18 +300,18 @@ def visit_value_path(self, node):
 
 
 # -- sort-start --
-def sort_expression(sort_by, sort_order=None):
-    """Return the ``ORDER BY`` term a ``sortBy`` parameter names.
+def sort_expression(search_request):
+    """Return the ``ORDER BY`` term of the ``sortBy`` of a search request.
 
     A sub-attribute is looked up under the attribute holding it, the way the
     filter does: ``meta.lastModified`` is stored in ``("meta", "last_modified")``.
 
-    :param sort_by: The ``sortBy`` query parameter.
-    :param sort_order: The ``sortOrder`` query parameter, ascending by default.
-    :raises InvalidPathException: If the attribute is unknown, or is stored in
-        a table an ``ORDER BY`` over users cannot reach.
+    :param search_request: The query, with its ``sortBy`` and ``sortOrder``.
+    :raises InvalidPathException: If users cannot be sorted on the attribute,
+        or if it is stored in a table an ``ORDER BY`` over users cannot reach.
     """
-    resolved = sort_by.resolve()
+    sort_by = search_request.sort_by
+    resolved = search_request.sort_binding(User)
     relationship_, column = None, None
     if resolved is not None:
         relationship_, column = COLUMNS.get(
@@ -329,7 +329,7 @@ def sort_expression(sort_by, sort_order=None):
     # the sortOrder parameter, i.e., they are ordered last if ascending and
     # first if descending", which is the default of PostgreSQL and not of the
     # engines taking NULL for the smallest value.
-    if sort_order == SearchRequest.SortOrder.descending:
+    if search_request.sort_order == SearchRequest.SortOrder.descending:
         return nulls_first(column.desc())
     return nulls_last(column.asc())
 
@@ -361,9 +361,7 @@ def query_users(session, search_request):
 
     order_by = []
     if search_request.sort_by:
-        order_by.append(
-            sort_expression(search_request.sort_by, search_request.sort_order)
-        )
+        order_by.append(sort_expression(search_request))
     # A page is a slice of an ordered result. Rows sharing a sort key, or a
     # query with no sortBy at all, leave OFFSET free to return one row twice
     # and another never, so the primary key always closes the order.

doc/integrations/sqlalchemy.rst

@@ -121,10 +121,13 @@ The test on the case reads the SCIM type and not the Python one: ``emails.value`
 Sorting
 -------
 
-:attr:`SearchRequest.sort_by <scim2_models.SearchRequest.sort_by>` is a
-:class:`~scim2_models.Path`, already resolved against the model on a parameterized request. On a
-union, it resolves against the first resource type declaring the attribute. ``sort_expression``
-looks the path up in the same table of columns as the filter does. A sub-attribute is filed under
+:meth:`SearchRequest.sort_binding <scim2_models.SearchRequest.sort_binding>` binds
+:attr:`~scim2_models.SearchRequest.sort_by` to an attribute of the model passed. Here the model is
+:class:`~scim2_models.User`, the type the table stores, so a request bound to a union or to no
+type at all sorts the same way. The method returns :data:`None` when users cannot be sorted on the
+attribute: unknown, complex, binary or write-only. A multi-valued complex attribute is bound to
+its ``value`` sub-attribute, so ``emails`` sorts as ``emails.value``. ``sort_expression`` looks
+the binding up in the same table of columns as the filter does. A sub-attribute is filed under
 the attribute holding it, so ``meta.lastModified`` is found at ``("meta", "last_modified")``. The
 remaining step turns the column into an ``ORDER BY`` term, and
 :rfc:`RFC7644 §3.4.2.3 <7644#section-3.4.2.3>` sets order rules that a bare ``ORDER BY column``

tests/test_doc_examples.py

@@ -26,6 +26,7 @@
 from doc.integrations._examples.sqlalchemy_example import to_scim_user  # noqa: E402
 from scim2_models import BulkRequest  # noqa: E402
 from scim2_models import Context  # noqa: E402
+from scim2_models import Group  # noqa: E402
 from scim2_models import InvalidPathException  # noqa: E402
 from scim2_models import ScimFilter  # noqa: E402
 from scim2_models import SearchRequest  # noqa: E402
@@ -829,10 +830,23 @@ def test_sqlalchemy_rejects_sorting_on_an_unreachable_attribute(
         query_users(sqlalchemy_session, SearchRequest[User](sort_by=attribute))
 
 
-def test_sqlalchemy_rejects_a_request_that_named_no_resource_type(sqlalchemy_session):
-    """The query orders by a resolved attribute, which an unparameterised request has none of."""
+@pytest.mark.parametrize("request_type", [SearchRequest, SearchRequest[User | Group]])
+def test_sqlalchemy_sorts_a_request_bound_to_any_type_as_users(
+    sqlalchemy_session, request_type
+):
+    """The table stores users, so the sortBy is resolved against User whatever the request names."""
+    expected = query_users(sqlalchemy_session, SearchRequest[User](sort_by="userName"))
+    total, page = query_users(sqlalchemy_session, request_type(sort_by="userName"))
+    assert (total, page) == expected
+
+
+@pytest.mark.parametrize("sort_by", ["password", "name", "nonexistent"])
+def test_sqlalchemy_rejects_an_attribute_users_cannot_be_sorted_on(
+    sqlalchemy_session, sort_by
+):
+    """An unparameterised request is not validated, so the query refuses the order itself."""
     with pytest.raises(InvalidPathException):
-        query_users(sqlalchemy_session, SearchRequest(sort_by="userName"))
+        query_users(sqlalchemy_session, SearchRequest(sort_by=sort_by))
 
 
 USER_SCHEMA = "urn:ietf:params:scim:schemas:core:2.0:User"