refactor: update _convert_file_sort_order to use SortKey for improved type safety

Author: kosiew

python/datafusion/context.py

@@ -1176,8 +1176,16 @@ def execute(self, plan: ExecutionPlan, partitions: int) -> RecordBatchStream:
 
     @staticmethod
     def _convert_file_sort_order(
-        file_sort_order: list[list[Expr | SortExpr | str]] | None,
+        file_sort_order: list[list[SortKey]] | None,
     ) -> list[list[Any]] | None:
+        """Convert nested ``SortKey`` lists into raw sort representations.
+
+        Each ``SortKey`` can be a column name string, an ``Expr``, or a
+        ``SortExpr`` and will be converted using
+        :func:`datafusion.expr.sort_list_to_raw_sort_list`.
+        """
+        # Convert each ``SortKey`` in the provided sort order to the low-level
+        # representation expected by the Rust bindings.
         return (
             [sort_list_to_raw_sort_list(f) for f in file_sort_order]
             if file_sort_order is not None