fix: reject with_session=True for FFI UDTFs and qualify mutation docs

Raise TypeError when with_session=True is combined with an FFI-exported
table function (one exposing __datafusion_table_function__). The Rust
FFI branch does not consult the flag, so it would silently be dropped;
guard both TableFunction.__init__ and the udtf() convenience entry.

Qualify the doc claim that mutations through the injected session
propagate to the caller: registry mutations do (shared Arc registries),
but config changes do not (SessionConfig is cloned). Mirror the caveat
in TableFunction.__init__ per the user-guide caveats convention.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: timsaucer

docs/source/user-guide/common-operations/udf-and-udfa.rst

@@ -465,5 +465,8 @@ unchanged.
 
 The injected ``session`` is a fresh :py:class:`~datafusion.SessionContext`
 wrapper backed by the same underlying state as the caller, so registries
-(tables, UDFs, catalogs) are visible. Mutations made through it affect
-the live session.
+(tables, UDFs, catalogs) are visible. Registry mutations (e.g. registering
+a new table or UDF) propagate to the live session because the registries
+are reference-counted and shared. Configuration changes made through the
+wrapper (e.g. setting session options) do **not** propagate — the wrapper
+holds its own clone of the session config.

python/datafusion/user_defined.py

@@ -1096,9 +1096,26 @@ def __init__(
         ``with_session`` is ``False`` (the default), ``func`` is invoked
         with the positional expression arguments only.
 
+        ``with_session=True`` is only supported for pure-Python callables.
+        Passing it together with an FFI-exported table function (one
+        exposing ``__datafusion_table_function__``) raises
+        :class:`TypeError`.
+
+        Registry mutations performed through the injected session (such
+        as registering tables or UDFs) propagate to the caller's
+        :class:`SessionContext` because the registries are shared.
+        Configuration changes do **not** propagate; the wrapper holds
+        its own clone of the session config.
+
         See :py:func:`udtf` for a convenience function and argument
         descriptions.
         """
+        if with_session and hasattr(func, "__datafusion_table_function__"):
+            msg = (
+                "`with_session=True` is not supported for FFI-exported table "
+                "functions; session injection requires a pure-Python callable."
+            )
+            raise TypeError(msg)
         registered = _wrap_session_kwarg_for_udtf(func) if with_session else func
         self._udtf = df_internal.TableFunction(name, registered, ctx, with_session)
 
@@ -1139,6 +1156,13 @@ def udtf(*args: Any, with_session: bool = False, **kwargs: Any):
             )
         if args and hasattr(args[0], "__datafusion_table_function__"):
             # Case 2: We have a datafusion FFI provided function
+            if with_session:
+                msg = (
+                    "`with_session=True` is not supported for FFI-exported "
+                    "table functions; session injection requires a "
+                    "pure-Python callable."
+                )
+                raise TypeError(msg)
             return TableFunction(args[1], args[0])
         # Case 3: Used as a decorator with parameters
         return TableFunction._create_table_udf_decorator(

python/tests/test_udtf.py

@@ -17,8 +17,10 @@
 
 import pyarrow as pa
 import pyarrow.dataset as ds
+import pytest
 from datafusion import Expr, SessionContext, Table, udtf
 from datafusion.context import TableProviderExportable
+from datafusion.user_defined import TableFunction
 
 
 def python_table_function_inner(
@@ -215,3 +217,19 @@ def plain_func(n: Expr) -> TableProviderExportable:
     result = ctx.sql("SELECT * FROM plain_func(4)").collect()
 
     assert result[0].column(0).to_pylist() == [0, 1, 2, 3]
+
+
+def test_with_session_rejected_for_ffi_table_function() -> None:
+    """`with_session=True` is incompatible with FFI-exported table functions."""
+
+    class FakeFFITableFunction:
+        # Presence of this attribute is what marks a function as FFI-exported.
+        __datafusion_table_function__ = "stub"
+
+    fake = FakeFFITableFunction()
+
+    with pytest.raises(TypeError, match="FFI-exported table functions"):
+        udtf(fake, "fake_ffi", with_session=True)
+
+    with pytest.raises(TypeError, match="FFI-exported table functions"):
+        TableFunction("fake_ffi", fake, with_session=True)