Deprecate singular external table location

AI Disclosure: This code was written in part by an AI agent.:

Author: timsaucer

crates/core/src/expr/create_external_table.rs

@@ -118,10 +118,6 @@ impl PyCreateExternalTable {
         Ok(self.create.name.to_string())
     }
 
-    pub fn location(&self) -> String {
-        self.create.locations.first().cloned().unwrap_or_default()
-    }
-
     pub fn locations(&self) -> Vec<String> {
         self.create.locations.clone()
     }

python/datafusion/expr.py

@@ -49,6 +49,11 @@
 from collections.abc import Callable, Iterable, Sequence
 from typing import TYPE_CHECKING, Any, ClassVar
 
+try:
+    from warnings import deprecated  # Python 3.13+
+except ImportError:
+    from typing_extensions import deprecated  # Python 3.12
+
 import pyarrow as pa
 
 from ._internal import expr as expr_internal
@@ -90,6 +95,25 @@
 CreateCatalog = expr_internal.CreateCatalog
 CreateCatalogSchema = expr_internal.CreateCatalogSchema
 CreateExternalTable = expr_internal.CreateExternalTable
+
+
+@deprecated("CreateExternalTable.location() is deprecated; use locations() instead.")
+def _create_external_table_location(self: Any) -> str:
+    """Return the first external table location.
+
+    Examples:
+        >>> class Command:
+        ...     def locations(self) -> list[str]:
+        ...         return ["data.csv"]
+        >>> _create_external_table_location(Command())
+        'data.csv'
+    """
+    locations = self.locations()
+    return locations[0] if locations else ""
+
+
+CreateExternalTable.location = _create_external_table_location
+
 CreateFunction = expr_internal.CreateFunction
 CreateFunctionBody = expr_internal.CreateFunctionBody
 CreateIndex = expr_internal.CreateIndex

python/tests/test_expr.py

@@ -19,6 +19,7 @@
 from concurrent.futures import ThreadPoolExecutor
 from datetime import date, datetime, time, timezone
 from decimal import Decimal
+from unittest.mock import MagicMock
 
 import arro3.core
 import nanoarrow
@@ -39,6 +40,7 @@
     BinaryExpr,
     Column,
     CopyTo,
+    CreateExternalTable,
     CreateIndex,
     DescribeTable,
     DmlStatement,
@@ -68,6 +70,17 @@ def test_ctx():
     return ctx
 
 
+def test_create_external_table_location_is_deprecated():
+    """The singular location accessor delegates to locations()."""
+    command = MagicMock()
+    command.locations.return_value = ["first.csv", "second.csv"]
+
+    with pytest.warns(DeprecationWarning, match=r"location\(\).+deprecated"):
+        location = CreateExternalTable.location(command)
+
+    assert location == "first.csv"
+
+
 def test_projection(test_ctx):
     df = test_ctx.sql("select c1, 123, c1 < 123 from test")
     plan = df.logical_plan()