docs: clarify Python UDF inlining docstring; drop unresolved :doc: refs

Rewrite with_python_udf_inlining docstring for readability and remove
references to /user-guide/io/distributing_work, which does not exist
yet. Keep security warning inline as a .. warning:: Security block,
matching the existing pattern in Expr.to_bytes / from_bytes /
__reduce__. The central doc will land in a follow-on PR.

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

Author: timsaucer

python/datafusion/context.py

@@ -1771,42 +1771,35 @@ def with_physical_extension_codec(self, codec: Any) -> SessionContext:
         return new
 
     def with_python_udf_inlining(self, *, enabled: bool) -> SessionContext:
-        """Toggle inline encoding of Python-defined UDFs on this session.
-
-        ``enabled`` is keyword-only:
-        ``with_python_udf_inlining(enabled=False)`` reads at the call
-        site as the inverse of
-        ``with_python_udf_inlining(enabled=True)``, where a positional
-        ``True`` / ``False`` would not.
-
-        When ``True`` (the default), Python scalar, aggregate, and window
-        UDFs travel inside the serialized expression and are
-        reconstructed on the receiver without pre-registration.
-
-        Set ``False`` to:
-
-        * Produce serialized bytes that round-trip through a non-Python
-          decoder (cross-language portability). UDFs are stored by name
-          only; the receiver must have matching registrations.
-        * Refuse to reconstruct Python UDFs from
-          :meth:`Expr.from_bytes` input that may come from an untrusted
-          source — ``cloudpickle.loads`` will not be invoked.
-
-        The toggle applies directly to :meth:`Expr.to_bytes` /
-        :meth:`Expr.from_bytes` calls that pass this session as their
-        ``ctx`` argument. To make the toggle apply through
-        :func:`pickle.dumps` (which calls :meth:`Expr.to_bytes` with no
-        context), install this session as the driver's sender context
-        via :func:`datafusion.ipc.set_sender_ctx` — and install it as
-        the worker's context via
-        :func:`datafusion.ipc.set_worker_ctx` for the corresponding
-        :func:`pickle.loads`.
-
-        For the full security model, see
-        :doc:`/user-guide/io/distributing_work` (Security section). In
-        short: this toggle narrows only the :meth:`Expr.from_bytes`
-        surface; :func:`pickle.loads` on untrusted bytes remains
-        unsafe regardless of the toggle.
+        """Control whether Python UDFs are embedded in serialized expressions.
+
+        When ``enabled=True`` (the default), serialized expressions carry
+        the Python code for any scalar, aggregate, or window UDFs they
+        reference. The receiver rebuilds the UDFs from those bytes and
+        does not need to register them first.
+
+        When ``enabled=False``, serialized expressions store only the
+        UDF names. This has two uses:
+
+        * **Cross-language portability.** The bytes can be decoded by a
+          non-Python receiver, which must already have UDFs registered
+          under matching names.
+        * **Safer deserialization.** :meth:`Expr.from_bytes` will refuse
+          to rebuild Python UDFs rather than call ``cloudpickle.loads``
+          on untrusted input.
+
+        The setting affects :meth:`Expr.to_bytes` and
+        :meth:`Expr.from_bytes` whenever this session is passed as the
+        ``ctx`` argument. :func:`pickle.dumps` and :func:`pickle.loads`
+        do not pass a context, so to apply the setting through pickle,
+        register this session with
+        :func:`datafusion.ipc.set_sender_ctx` on the sender and
+        :func:`datafusion.ipc.set_worker_ctx` on the receiver.
+
+        .. warning:: Security
+            This setting narrows only :meth:`Expr.from_bytes`. Calling
+            :func:`pickle.loads` on untrusted bytes remains unsafe
+            regardless of the toggle.
         """
         new_internal = self.ctx.with_python_udf_inlining(enabled)
         new = SessionContext.__new__(SessionContext)

python/datafusion/expr.py

@@ -454,8 +454,7 @@ def to_bytes(self, ctx: SessionContext | None = None) -> bytes:
         Built-in functions and Python UDFs (scalar, aggregate, window)
         travel inside the returned bytes; the worker does not need to
         pre-register them. UDFs imported via the FFI capsule protocol
-        travel by name only and must be registered on the worker. See
-        :doc:`/user-guide/io/distributing_work`.
+        travel by name only and must be registered on the worker.
 
         .. warning:: Security
             Bytes returned here may embed a cloudpickled Python

python/datafusion/ipc.py

@@ -72,8 +72,6 @@ def init_worker():
 inlining on). The sender context only affects pickle / ``to_bytes``
 encoding; explicit ``expr.to_bytes(ctx)`` calls still use the supplied
 ``ctx``.
-
-See :doc:`/user-guide/io/distributing_work` for the full pattern.
 """
 
 from __future__ import annotations