Remove map() in favor of make_map(), fix docstrings, add validation

- Remove map() function that shadowed Python builtin; make_map() is now
  the sole entry point for creating map expressions
- Fix map_extract/element_at docstrings: missing keys return [None],
  not an empty list (matches actual upstream behavior)
- Add length validation for the two-list calling convention
- Update all tests and docstring examples accordingly

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timsaucer

python/datafusion/functions.py

@@ -3383,15 +3383,15 @@ def empty(array: Expr) -> Expr:
 # map functions
 
 
-def map(*args: Any) -> Expr:
+def make_map(*args: Any) -> Expr:
     """Returns a map expression.
 
     Supports three calling conventions:
 
-    - ``map({"a": 1, "b": 2})`` — from a Python dictionary.
-    - ``map([keys], [values])`` — from a list of keys and a list of
+    - ``make_map({"a": 1, "b": 2})`` — from a Python dictionary.
+    - ``make_map([keys], [values])`` — from a list of keys and a list of
       their associated values.  Both lists must be the same length.
-    - ``map(k1, v1, k2, v2, ...)`` — from alternating keys and their
+    - ``make_map(k1, v1, k2, v2, ...)`` — from alternating keys and their
       associated values.
 
     Keys and values that are not already :py:class:`~datafusion.expr.Expr`
@@ -3403,15 +3403,15 @@ def map(*args: Any) -> Expr:
         >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": [1]})
         >>> result = df.select(
-        ...     dfn.functions.map({"a": 1, "b": 2}).alias("m"))
+        ...     dfn.functions.make_map({"a": 1, "b": 2}).alias("m"))
         >>> result.collect_column("m")[0].as_py()
         [('a', 1), ('b', 2)]
 
         From two lists:
 
         >>> df = ctx.from_pydict({"key": ["x", "y"], "val": [10, 20]})
         >>> df = df.select(
-        ...     dfn.functions.map(
+        ...     dfn.functions.make_map(
         ...         [dfn.col("key")], [dfn.col("val")]
         ...     ).alias("m"))
         >>> df.collect_column("m")[0].as_py()
@@ -3421,7 +3421,7 @@ def map(*args: Any) -> Expr:
 
         >>> df = ctx.from_pydict({"a": [1]})
         >>> result = df.select(
-        ...     dfn.functions.map("x", 1, "y", 2).alias("m"))
+        ...     dfn.functions.make_map("x", 1, "y", 2).alias("m"))
         >>> result.collect_column("m")[0].as_py()
         [('x', 1), ('y', 2)]
     """
@@ -3433,37 +3433,34 @@ def map(*args: Any) -> Expr:
         and isinstance(args[0], list)
         and isinstance(args[1], list)
     ):
+        if len(args[0]) != len(args[1]):
+            msg = "make_map requires key and value lists to be the same length"
+            raise ValueError(msg)
         key_list = args[0]
         value_list = args[1]
     elif len(args) >= 2 and len(args) % 2 == 0:  # noqa: PLR2004
         key_list = list(args[0::2])
         value_list = list(args[1::2])
     else:
-        msg = "map expects a dict, two lists, or an even number of key-value arguments"
+        msg = (
+            "make_map expects a dict, two lists, or an even number of "
+            "key-value arguments"
+        )
         raise ValueError(msg)
 
     key_exprs = [k if isinstance(k, Expr) else Expr.literal(k) for k in key_list]
     val_exprs = [v if isinstance(v, Expr) else Expr.literal(v) for v in value_list]
     return Expr(f.make_map([k.expr for k in key_exprs], [v.expr for v in val_exprs]))
 
 
-def make_map(*args: Any) -> Expr:
-    """Returns a map expression.
-
-    See Also:
-        This is an alias for :py:func:`map`.
-    """
-    return map(*args)
-
-
 def map_keys(map: Expr) -> Expr:
     """Returns a list of all keys in the map.
 
     Examples:
         >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": [1]})
         >>> df = df.select(
-        ...     dfn.functions.map({"x": 1, "y": 2}).alias("m"))
+        ...     dfn.functions.make_map({"x": 1, "y": 2}).alias("m"))
         >>> result = df.select(
         ...     dfn.functions.map_keys(dfn.col("m")).alias("keys"))
         >>> result.collect_column("keys")[0].as_py()
@@ -3479,7 +3476,7 @@ def map_values(map: Expr) -> Expr:
         >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": [1]})
         >>> df = df.select(
-        ...     dfn.functions.map({"x": 1, "y": 2}).alias("m"))
+        ...     dfn.functions.make_map({"x": 1, "y": 2}).alias("m"))
         >>> result = df.select(
         ...     dfn.functions.map_values(dfn.col("m")).alias("vals"))
         >>> result.collect_column("vals")[0].as_py()
@@ -3489,13 +3486,15 @@ def map_values(map: Expr) -> Expr:
 
 
 def map_extract(map: Expr, key: Expr) -> Expr:
-    """Returns the value for the given key in the map, or an empty list if absent.
+    """Return the value for a given key in the map.
+
+    Returns ``[None]`` if the key is absent.
 
     Examples:
         >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": [1]})
         >>> df = df.select(
-        ...     dfn.functions.map({"x": 1, "y": 2}).alias("m"))
+        ...     dfn.functions.make_map({"x": 1, "y": 2}).alias("m"))
         >>> result = df.select(
         ...     dfn.functions.map_extract(
         ...         dfn.col("m"), dfn.lit("x")
@@ -3513,7 +3512,7 @@ def map_entries(map: Expr) -> Expr:
         >>> ctx = dfn.SessionContext()
         >>> df = ctx.from_pydict({"a": [1]})
         >>> df = df.select(
-        ...     dfn.functions.map({"x": 1, "y": 2}).alias("m"))
+        ...     dfn.functions.make_map({"x": 1, "y": 2}).alias("m"))
         >>> result = df.select(
         ...     dfn.functions.map_entries(dfn.col("m")).alias("entries"))
         >>> result.collect_column("entries")[0].as_py()
@@ -3523,7 +3522,9 @@ def map_entries(map: Expr) -> Expr:
 
 
 def element_at(map: Expr, key: Expr) -> Expr:
-    """Returns the value for the given key in the map, or an empty list if absent.
+    """Return the value for a given key in the map.
+
+    Returns ``[None]`` if the key is absent.
 
     See Also:
         This is an alias for :py:func:`map_extract`.

python/tests/test_functions.py

@@ -673,7 +673,7 @@ def test_map_from_dict():
     batch = pa.RecordBatch.from_arrays([pa.array([1])], names=["a"])
     df = ctx.create_dataframe([[batch]])
 
-    result = df.select(f.map({"x": 1, "y": 2}).alias("m")).collect()[0].column(0)
+    result = df.select(f.make_map({"x": 1, "y": 2}).alias("m")).collect()[0].column(0)
     assert result[0].as_py() == [("x", 1), ("y", 2)]
 
 
@@ -683,7 +683,7 @@ def test_map_from_dict_with_expr_values():
     df = ctx.create_dataframe([[batch]])
 
     result = (
-        df.select(f.map({"x": literal(1), "y": literal(2)}).alias("m"))
+        df.select(f.make_map({"x": literal(1), "y": literal(2)}).alias("m"))
         .collect()[0]
         .column(0)
     )
@@ -701,7 +701,7 @@ def test_map_from_two_lists():
     )
     df = ctx.create_dataframe([[batch]])
 
-    m = f.map([column("keys")], [column("vals")])
+    m = f.make_map([column("keys")], [column("vals")])
     result = df.select(f.map_keys(m).alias("k")).collect()[0].column(0)
     for i, expected in enumerate(["k1", "k2", "k3"]):
         assert result[i].as_py() == [expected]
@@ -716,7 +716,7 @@ def test_map_from_variadic_pairs():
     batch = pa.RecordBatch.from_arrays([pa.array([1])], names=["a"])
     df = ctx.create_dataframe([[batch]])
 
-    result = df.select(f.map("x", 1, "y", 2).alias("m")).collect()[0].column(0)
+    result = df.select(f.make_map("x", 1, "y", 2).alias("m")).collect()[0].column(0)
     assert result[0].as_py() == [("x", 1), ("y", 2)]
 
 
@@ -726,33 +726,31 @@ def test_map_variadic_with_exprs():
     df = ctx.create_dataframe([[batch]])
 
     result = (
-        df.select(f.map(literal("x"), literal(1), literal("y"), literal(2)).alias("m"))
+        df.select(
+            f.make_map(literal("x"), literal(1), literal("y"), literal(2)).alias("m")
+        )
         .collect()[0]
         .column(0)
     )
     assert result[0].as_py() == [("x", 1), ("y", 2)]
 
 
-def test_map_odd_args_raises():
-    with pytest.raises(ValueError, match="map expects"):
-        f.map("x", 1, "y")
+def test_make_map_odd_args_raises():
+    with pytest.raises(ValueError, match="make_map expects"):
+        f.make_map("x", 1, "y")
 
 
-def test_make_map_is_alias():
-    ctx = SessionContext()
-    batch = pa.RecordBatch.from_arrays([pa.array([1])], names=["a"])
-    df = ctx.create_dataframe([[batch]])
-
-    result = df.select(f.make_map({"x": 1, "y": 2}).alias("m")).collect()[0].column(0)
-    assert result[0].as_py() == [("x", 1), ("y", 2)]
+def test_make_map_mismatched_lengths():
+    with pytest.raises(ValueError, match="same length"):
+        f.make_map(["a", "b"], [1])
 
 
 def test_map_keys():
     ctx = SessionContext()
     batch = pa.RecordBatch.from_arrays([pa.array([1])], names=["a"])
     df = ctx.create_dataframe([[batch]])
 
-    m = f.map({"x": 1, "y": 2})
+    m = f.make_map({"x": 1, "y": 2})
     result = df.select(f.map_keys(m).alias("keys")).collect()[0].column(0)
     assert result[0].as_py() == ["x", "y"]
 
@@ -762,7 +760,7 @@ def test_map_values():
     batch = pa.RecordBatch.from_arrays([pa.array([1])], names=["a"])
     df = ctx.create_dataframe([[batch]])
 
-    m = f.map({"x": 1, "y": 2})
+    m = f.make_map({"x": 1, "y": 2})
     result = df.select(f.map_values(m).alias("vals")).collect()[0].column(0)
     assert result[0].as_py() == [1, 2]
 
@@ -772,7 +770,7 @@ def test_map_extract():
     batch = pa.RecordBatch.from_arrays([pa.array([1])], names=["a"])
     df = ctx.create_dataframe([[batch]])
 
-    m = f.map({"x": 1, "y": 2})
+    m = f.make_map({"x": 1, "y": 2})
     result = (
         df.select(f.map_extract(m, literal("x")).alias("val")).collect()[0].column(0)
     )
@@ -784,7 +782,7 @@ def test_map_extract_missing_key():
     batch = pa.RecordBatch.from_arrays([pa.array([1])], names=["a"])
     df = ctx.create_dataframe([[batch]])
 
-    m = f.map({"x": 1})
+    m = f.make_map({"x": 1})
     result = (
         df.select(f.map_extract(m, literal("z")).alias("val")).collect()[0].column(0)
     )
@@ -796,7 +794,7 @@ def test_map_entries():
     batch = pa.RecordBatch.from_arrays([pa.array([1])], names=["a"])
     df = ctx.create_dataframe([[batch]])
 
-    m = f.map({"x": 1, "y": 2})
+    m = f.make_map({"x": 1, "y": 2})
     result = df.select(f.map_entries(m).alias("entries")).collect()[0].column(0)
     assert result[0].as_py() == [
         {"key": "x", "value": 1},
@@ -809,7 +807,7 @@ def test_element_at():
     batch = pa.RecordBatch.from_arrays([pa.array([1])], names=["a"])
     df = ctx.create_dataframe([[batch]])
 
-    m = f.map({"a": 10, "b": 20})
+    m = f.make_map({"a": 10, "b": 20})
     result = (
         df.select(f.element_at(m, literal("b")).alias("val")).collect()[0].column(0)
     )