list operations

Author: pcrespov

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

@@ -0,0 +1,67 @@
+"""API List operation
+
+- Ordering: https://google.aip.dev/132#ordering
+
+
+SEE ALSO:
+    - batch_operations.py
+"""
+
+from enum import Enum
+from typing import TYPE_CHECKING, Annotated, Generic, TypeVar
+
+from annotated_types import doc
+from pydantic import BaseModel
+
+
+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(BaseModel, Generic[TField]):
+    field: TField
+    direction: OrderDirection = OrderDirection.ASC
+
+
+def check_ordering_list(
+    order_by: list[tuple[TField, OrderDirection]]
+) -> Annotated[
+    list[tuple[TField, OrderDirection]],
+    doc("Validated list with duplicates removed and preserving first occurrence order"),
+]:
+    """Validates ordering list and removes duplicate entries.
+
+    Raises:
+        ValueError: If a field appears with conflicting directions
+    """
+    seen_fields: dict[TField, OrderDirection] = {}
+    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,70 @@
+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