docs: pass volatility by keyword, drop a dead cross-reference

The new bundle examples spelled volatility positionally while the
neighbouring `context.py` examples name it, which leaves a bare
"stable" sitting among three pyarrow arguments with nothing to say
what it is.

Two docstrings alongside: `_components` pointed a `:py:meth:` role at
`__post_init__`, which Sphinx has no target for and never renders
anyway from a private helper; and `_resolve_declared_functions` said
its `wrapper` argument was "passed through already", which says
nothing. It is the class a declaration may already be an instance of.

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

Author: timsaucer

python/datafusion/context.py

@@ -304,7 +304,8 @@ def _resolve_declared_functions(
 
     Args:
         declared: ``(extension, function)`` pairs in declaration order.
-        wrapper: The Python wrapper class for this kind, passed through already.
+        wrapper: The wrapper class a declaration may already be an instance of,
+            in which case it is taken as-is.
         getter: The capsule getter an unwrapped declaration must expose.
         factory: The helper that wraps a declaration — ``udf`` and friends.
         kind: What to call this sort of function in an error.

python/datafusion/extensions.py

@@ -121,8 +121,8 @@ def _components(noun: str) -> Any:
 
     ``noun`` names what the field holds, for the error a bundle sees when it
     hands over one component instead of a collection of them. Carrying it in
-    the field metadata is what lets :py:meth:`SessionExtensionComponents.__post_init__`
-    normalize a field it was never told about by name.
+    the field metadata is what lets ``__post_init__`` normalize a field it was
+    never told about by name.
     """
     return field(default=(), metadata={"datafusion_component": noun})
 
@@ -190,7 +190,7 @@ class SessionExtensionComponents:
         ...     lambda arr: pa.array([v.as_py() * 2 for v in arr]),
         ...     [pa.int64()],
         ...     pa.int64(),
-        ...     "stable",
+        ...     volatility="stable",
         ...     name="double",
         ... )
         >>> components = SessionExtensionComponents(udfs=(double,))

python/tests/test_context.py

@@ -1422,7 +1422,7 @@ def _doubler(name="double"):
         lambda arr: pa.array([v.as_py() * 2 for v in arr]),
         [pa.int64()],
         pa.int64(),
-        "stable",
+        volatility="stable",
         name=name,
     )
 
@@ -1483,8 +1483,21 @@ def test_with_extensions_registers_a_declared_udf(ctx):
 
 def test_with_extensions_registers_udafs_and_udwfs(ctx):
     """The other two function kinds install the same way."""
-    total = udaf(_Total, pa.int64(), pa.int64(), [pa.int64()], "stable", name="total")
-    first = udwf(_First, pa.int64(), pa.int64(), "immutable", name="first_value_of")
+    total = udaf(
+        _Total,
+        pa.int64(),
+        pa.int64(),
+        [pa.int64()],
+        volatility="stable",
+        name="total",
+    )
+    first = udwf(
+        _First,
+        pa.int64(),
+        pa.int64(),
+        volatility="immutable",
+        name="first_value_of",
+    )
 
     result = ctx.with_extensions(_FunctionExtension(udafs=(total,), udwfs=(first,)))
     result.from_pydict({"a": [1, 2, 3]}, name="nums")