list operations sorting

Author: pcrespov

packages/models-library/src/models_library/list_operations.py

@@ -0,0 +1,72 @@
+"""List operation models and helpers
+
+- Ordering: https://google.aip.dev/132#ordering
+
+
+"""
+
+from enum import Enum
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+from pydantic.generics import GenericModel
+
+
+class OrderDirection(str, Enum):
+    ASC = "asc"
+    DESC = "desc"
+
+
+if TYPE_CHECKING:
+    from typing import Protocol
+
+    class LiteralField(Protocol):
+        """Protocol for Literal string types"""
+
+        def __str__(self) -> str: ...
+
+    TField = TypeVar("TField", bound=LiteralField)
+else:
+    TField = TypeVar("TField", bound=str)
+
+
+class OrderClause(GenericModel, Generic[TField]):
+    field: TField
+    direction: OrderDirection = OrderDirection.ASC
+
+
+def check_ordering_list(
+    order_by: list[tuple[TField, OrderDirection]],
+) -> list[tuple[TField, OrderDirection]]:
+    """Validates ordering list and removes duplicate entries.
+
+    Ensures that each field appears at most once. If a field is repeated:
+    - With the same direction: silently drops the duplicate
+    - With different directions: raises ValueError
+
+
+    Args:
+        order_by: List of (field, direction) tuples
+
+    Returns:
+        List with duplicates removed, preserving order of first occurrence
+
+    Raises:
+        ValueError: If a field appears with conflicting directions
+    """
+    seen_fields = {}
+    unique_order_by = []
+
+    for field, direction in order_by:
+        if field in seen_fields:
+            # Field already seen - check if direction matches
+            if seen_fields[field] != direction:
+                msg = f"Field '{field}' appears with conflicting directions: {seen_fields[field].value} and {direction.value}"
+                raise ValueError(msg)
+            # Same field and direction - skip duplicate
+            continue
+
+        # First time seeing this field
+        seen_fields[field] = direction
+        unique_order_by.append((field, direction))
+
+    return unique_order_by

packages/models-library/tests/test_list_operations.py

@@ -0,0 +1,67 @@
+import pytest
+from models_library.list_operations import OrderDirection, check_ordering_list
+
+
+def test_check_ordering_list_drops_duplicates_silently():
+    """Test that check_ordering_list silently drops duplicate entries with same field and direction"""
+
+    # Input with duplicates (same field and direction)
+    order_by = [
+        ("email", OrderDirection.ASC),
+        ("created", OrderDirection.DESC),
+        ("email", OrderDirection.ASC),  # Duplicate - should be dropped
+        ("name", OrderDirection.ASC),
+        ("created", OrderDirection.DESC),  # Duplicate - should be dropped
+    ]
+
+    result = check_ordering_list(order_by)
+
+    # Should return unique entries preserving order of first occurrence
+    expected = [
+        ("email", OrderDirection.ASC),
+        ("created", OrderDirection.DESC),
+        ("name", OrderDirection.ASC),
+    ]
+
+    assert result == expected
+
+
+def test_check_ordering_list_raises_for_conflicting_directions():
+    """Test that check_ordering_list raises ValueError when same field has different directions"""
+
+    # Input with same field but different directions
+    order_by = [
+        ("email", OrderDirection.ASC),
+        ("created", OrderDirection.DESC),
+        ("email", OrderDirection.DESC),  # Conflict! Same field, different direction
+    ]
+
+    with pytest.raises(ValueError, match="conflicting directions") as exc_info:
+        check_ordering_list(order_by)
+
+    error_msg = str(exc_info.value)
+    assert "Field 'email' appears with conflicting directions" in error_msg
+    assert "asc" in error_msg
+    assert "desc" in error_msg
+
+
+def test_check_ordering_list_empty_input():
+    """Test that check_ordering_list handles empty input correctly"""
+
+    result = check_ordering_list([])
+    assert result == []
+
+
+def test_check_ordering_list_no_duplicates():
+    """Test that check_ordering_list works correctly when there are no duplicates"""
+
+    order_by = [
+        ("email", OrderDirection.ASC),
+        ("created", OrderDirection.DESC),
+        ("name", OrderDirection.ASC),
+    ]
+
+    result = check_ordering_list(order_by)
+
+    # Should return the same list
+    assert result == order_by