Refactor check_ordering_list to enhance parameter documentation and type annotations; remove unused functions and imports

Author: pcrespov

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

@@ -6,8 +6,9 @@
 """
 
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, get_args, get_origin
+from typing import TYPE_CHECKING, Annotated, Generic, TypeVar
 
+from annotated_types import doc
 from pydantic.generics import GenericModel
 
 
@@ -29,34 +30,24 @@ def __str__(self) -> str: ...
     TField = TypeVar("TField", bound=str)
 
 
-def get_literal_values(tfield: Any) -> tuple[str, ...] | None:
-    """Return Literal values if TField is a Literal, else None."""
-    if get_origin(tfield) is Literal:
-        return get_args(tfield)
-    return None
-
-
 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]]:
+    order_by: Annotated[
+        list[tuple[TField, OrderDirection]],
+        doc(
+            "Duplicates with same direction dropped, conflicting directions raise ValueError"
+        ),
+    ],
+) -> Annotated[
+    list[tuple[TField, OrderDirection]],
+    doc("Duplicates removed, preserving first occurrence order"),
+]:
     """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
     """
@@ -77,55 +68,3 @@ 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,12 +1,7 @@
-from typing import Literal
-
 import pytest
 from models_library.list_operations import (
-    OrderClause,
     OrderDirection,
     check_ordering_list,
-    map_order_fields,
-    validate_order_fields_with_literals,
 )
 
 
@@ -73,101 +68,3 @@ 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

packages/models-library/tests/test_rest_ordering.py

@@ -4,7 +4,6 @@
 import pytest
 from common_library.json_serialization import json_dumps
 from models_library.basic_types import IDStr
-from models_library.list_operations import get_literal_values
 from models_library.rest_ordering import (
     OrderBy,
     OrderClause,
@@ -260,8 +259,6 @@ class TestOrderingParams(OrderingQueryParams[ValidField]):
         OrderClause[ValidField](field="gender", direction=OrderDirection.ASC),
     ]
 
-    assert get_literal_values(ValidField) == ("created_at", "name", "gender")
-
 
 def test_ordering_query_params_validation_error_with_invalid_fields():
     """Test that OrderingQueryParams raises ValidationError when invalid fields are used"""