docs: state that a declared function may not be a bare capsule

udf(), udaf() and udwf() accept a bare PyCapsule, but a declaration in
SessionExtensionComponents must be a wrapper or an object exposing the
getter. Say so on the field, and pin it with an FFI example test that
shows the same capsule wrapping fine through udf().

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

Author: timsaucer

examples/datafusion-ffi-example/python/tests/_test_session_extension.py

@@ -21,8 +21,8 @@
 
 import pyarrow as pa
 import pytest
-from datafusion import SessionContext, SessionExtensionComponents
-from datafusion_ffi_example import MyFunctionExtension
+from datafusion import SessionContext, SessionExtensionComponents, udf
+from datafusion_ffi_example import IsNullUDF, MyFunctionExtension
 
 
 def _session():
@@ -96,6 +96,30 @@ def test_installing_the_library_twice_is_refused():
         ctx.udf("my_custom_is_null")
 
 
+def test_a_bare_capsule_is_not_a_declaration():
+    """A declared function is an object, even though ``udf`` takes a capsule.
+
+    The capsule itself is fine -- ``udf`` wraps it -- so the refusal is the
+    declaration rule, not a bad capsule.
+    """
+    ctx = SessionContext()
+    capsule = IsNullUDF().__datafusion_scalar_udf__()
+
+    class CapsuleExtension:
+        def __datafusion_session_components__(
+            self, ctx: SessionContext
+        ) -> SessionExtensionComponents:
+            return SessionExtensionComponents(udfs=(capsule,))
+
+    with pytest.raises(TypeError, match=r"__datafusion_scalar_udf__"):
+        ctx.with_extensions(CapsuleExtension())
+
+    with pytest.raises(KeyError):
+        ctx.udf("my_custom_is_null")
+
+    assert udf(capsule).name == "my_custom_is_null"
+
+
 def test_a_failure_after_the_hook_registers_nothing():
     """The transaction covers functions imported across the FFI boundary too."""
     ctx = SessionContext()

python/datafusion/extensions.py

@@ -276,8 +276,10 @@ class SessionExtensionComponents:
 
     Either a :py:class:`~datafusion.user_defined.ScalarUDF` or an object
     exposing ``__datafusion_scalar_udf__``, which is wrapped with
-    :py:func:`~datafusion.udf` on the way in. The registered name comes from
-    the function itself, not from this field.
+    :py:func:`~datafusion.udf` on the way in. A bare ``PyCapsule`` is refused,
+    though :py:func:`~datafusion.udf` accepts one; declare the object that
+    exports it. The registered name comes from the function itself, not from
+    this field.
 
     One :py:meth:`~datafusion.context.SessionContext.with_extensions` call may
     not declare a name twice, whether the two claims come from one extension or