Add mapping and validation functions for order fields with literals

Author: pcrespov

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

@@ -77,3 +77,55 @@ def check_ordering_list(
         unique_order_by.append((field, direction))
 
     return unique_order_by
+
+
+def map_order_fields(
+    order_clauses: list[OrderClause[TField]], field_mapping: dict[str, str]
+) -> list[tuple[str, OrderDirection]]:
+    """Map order clause fields using a field mapping dictionary.
+
+    Args:
+        order_clauses: List of OrderClause objects with API field names
+        field_mapping: Dictionary mapping API field names to domain/DB field names
+
+    Returns:
+        List of tuples with mapped field names and directions
+
+    Example:
+        >>> clauses = [OrderClause(field="email", direction=OrderDirection.ASC)]
+        >>> mapping = {"email": "user_email", "created_at": "created"}
+        >>> map_order_fields(clauses, mapping)
+        [("user_email", OrderDirection.ASC)]
+    """
+    return [
+        (field_mapping[str(clause.field)], clause.direction) for clause in order_clauses
+    ]
+
+
+def validate_order_fields_with_literals(
+    order_by: list[tuple[str, str]],
+    valid_fields: set[str],
+) -> None:
+    """Validate order_by list with string field names and directions.
+
+    Args:
+        order_by: List of (field_name, direction) tuples with string values
+        valid_fields: Set of allowed field names
+        valid_directions: Set of allowed direction values
+
+    Raises:
+        ValueError: If any field or direction is invalid
+    """
+    valid_directions = {OrderDirection.ASC.value, OrderDirection.DESC.value}
+
+    invalid_fields = {field for field, _ in order_by if field not in valid_fields}
+    if invalid_fields:
+        msg = f"Invalid order_by field(s): {invalid_fields}. Valid fields are: {valid_fields}"
+        raise ValueError(msg)
+
+    invalid_directions = {
+        direction for _, direction in order_by if direction not in valid_directions
+    }
+    if invalid_directions:
+        msg = f"Invalid order direction(s): {invalid_directions}. Must be one of: {valid_directions}"
+        raise ValueError(msg)

packages/models-library/tests/test_list_operations.py

@@ -1,5 +1,13 @@
+from typing import Literal
+
 import pytest
-from models_library.list_operations import OrderDirection, check_ordering_list
+from models_library.list_operations import (
+    OrderClause,
+    OrderDirection,
+    check_ordering_list,
+    map_order_fields,
+    validate_order_fields_with_literals,
+)
 
 
 def test_check_ordering_list_drops_duplicates_silently():
@@ -65,3 +73,101 @@ def test_check_ordering_list_no_duplicates():
 
     # Should return the same list
     assert result == order_by
+
+
+def test_map_order_fields():
+    """Test that map_order_fields correctly maps field names using provided mapping"""
+
+    ValidField = Literal["email", "created_at", "name"]
+
+    order_clauses = [
+        OrderClause[ValidField](field="email", direction=OrderDirection.ASC),
+        OrderClause[ValidField](field="created_at", direction=OrderDirection.DESC),
+        OrderClause[ValidField](field="name", direction=OrderDirection.ASC),
+    ]
+
+    field_mapping = {
+        "email": "user_email",
+        "created_at": "created_timestamp",
+        "name": "display_name",
+    }
+
+    result = map_order_fields(order_clauses, field_mapping)
+
+    expected = [
+        ("user_email", OrderDirection.ASC),
+        ("created_timestamp", OrderDirection.DESC),
+        ("display_name", OrderDirection.ASC),
+    ]
+
+    assert result == expected
+
+
+def test_map_order_fields_with_unmapped_field():
+    """Test that map_order_fields raises KeyError when field is not in mapping"""
+
+    ValidField = Literal["email", "unknown"]
+
+    order_clauses = [
+        OrderClause[ValidField](field="email", direction=OrderDirection.ASC),
+        OrderClause[ValidField](field="unknown", direction=OrderDirection.DESC),
+    ]
+
+    field_mapping = {
+        "email": "user_email",
+        # "unknown" is missing from mapping
+    }
+
+    with pytest.raises(KeyError):
+        map_order_fields(order_clauses, field_mapping)
+
+
+def test_validate_order_fields_with_literals_valid():
+    """Test that validate_order_fields_with_literals passes with valid fields and directions"""
+
+    order_by = [
+        ("email", "asc"),
+        ("created", "desc"),
+        ("name", "asc"),
+    ]
+
+    valid_fields = {"email", "created", "name"}
+
+    # Should not raise any exception
+    validate_order_fields_with_literals(order_by, valid_fields)
+
+
+def test_validate_order_fields_with_literals_invalid_field():
+    """Test that validate_order_fields_with_literals raises ValueError for invalid fields"""
+
+    order_by = [
+        ("email", "asc"),
+        ("invalid_field", "desc"),
+    ]
+
+    valid_fields = {"email", "created"}
+
+    with pytest.raises(ValueError, match="Invalid order_by field") as exc_info:
+        validate_order_fields_with_literals(order_by, valid_fields)
+
+    error_msg = str(exc_info.value)
+    assert "invalid_field" in error_msg
+    assert "Valid fields are" in error_msg
+
+
+def test_validate_order_fields_with_literals_invalid_direction():
+    """Test that validate_order_fields_with_literals raises ValueError for invalid directions"""
+
+    order_by = [
+        ("email", "ascending"),  # Invalid direction
+        ("created", "desc"),
+    ]
+
+    valid_fields = {"email", "created"}
+
+    with pytest.raises(ValueError, match="Invalid order direction") as exc_info:
+        validate_order_fields_with_literals(order_by, valid_fields)
+
+    error_msg = str(exc_info.value)
+    assert "ascending" in error_msg
+    assert "Must be one of" in error_msg