Correct three more claims in the extension bundle docs

`QueryPlannerExportable` said `session` is the
`datafusion.context.SessionContext` the planner is being installed on. It
is not. The capsule getters are called from Rust and receive the PyO3
context, so `isinstance(session, SessionContext)` is False -- while its
repr reads `datafusion.SessionContext`, because the pyclass declares
`module = "datafusion"`. It carries every capsule getter and
`__datafusion_codec_id__`, which is all the protocol needs, so the fix is
to say duck-type it rather than to change what is passed. The two bundle
hooks are the exception and do receive the wrapper, since `with_extensions`
dispatches them from Python; the ffi.md section on capsule getters now
draws the same distinction.

The `with_extensions` `Raises:` section listed ValueError for colliding
codec ids only. A getter returning a capsule of the wrong kind also raises
it -- `Expected name 'datafusion_query_planner' in PyCapsule, instead got
'datafusion_logical_extension_codec'` -- which
`test_with_extensions_rejects_bad_codec_capsule` already pins.

The `datafusion.extensions` module docstring said phase two runs the
planner hook "once per bundle". Once per bundle that implements it; a
bundle implements either hook or both.

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

Author: timsaucer

docs/source/contributor-guide/ffi.md

@@ -602,6 +602,14 @@ the session, and never touches a provider directly. That also matches what insta
 does anyway: `set_query_planner` builds the planner against the codecs of the session
 that will run the query.
 
+Duck-type `session`, and do not check its type. It is the PyO3 context the binding
+installs through, not the `datafusion.context.SessionContext` wrapper, so it carries
+every capsule getter and `__datafusion_codec_id__` — everything the protocol asks of it
+— but `isinstance(session, SessionContext)` is `False` in Python even though its `repr`
+reads `datafusion.SessionContext`. The two bundle hooks
+`__datafusion_session_extension__` and `__datafusion_session_planner__` are the
+exception: `with_extensions` dispatches them from Python and hands them the wrapper.
+
 `SessionContext` accepts the argument on all three getters and ignores it, so a session
 satisfies the same protocol an extension library implements. When you export the current
 planner to wrap it, `ctx.__datafusion_query_planner__()` and

python/datafusion/context.py

@@ -1915,7 +1915,11 @@ class as :py:meth:`with_logical_extension_codec` describes. Declare
                 ``__datafusion_codec_id__`` on at least one of them; the
                 collision is refused rather than resolved by position, because
                 a positional id would break stored plans the first time the
-                extension reordered what it returns.
+                extension reordered what it returns. Also if a capsule getter
+                returns a capsule of the wrong kind — a physical codec handed
+                over under ``__datafusion_logical_extension_codec__``, say —
+                which is reported against the name the getter should have
+                produced.
 
         Examples:
             The example is skipped here because it needs a built FFI

python/datafusion/extensions.py

@@ -37,10 +37,11 @@
 session's codec chain holds many codecs and dispatches between them by id, so
 codecs merely accumulate and their order does not affect decoding. A session
 holds exactly *one* query planner, so planners compose by nesting: each wraps
-the one before it. Phase one collects every bundle's codecs through
+the one before it. Phase one collects the codecs of every bundle implementing
 :py:class:`SessionExtensionExportable` and installs them; phase two runs
-:py:class:`SessionPlannerExportable` once per bundle, in argument order,
-handing each the planner built so far.
+:py:class:`SessionPlannerExportable` once for each bundle that implements it,
+in argument order, handing each the planner built so far. A bundle implements
+either hook or both, and one it does not implement is simply not called.
 
 That split is what lets several libraries that each ship a planner coexist. It
 also means bundle order is significant for planners and irrelevant for codecs.
@@ -72,10 +73,20 @@ class QueryPlannerExportable(Protocol):
     """Type hint for object that has a __datafusion_query_planner__ PyCapsule.
 
     The method returns a PyCapsule wrapping an ``FFI_QueryPlanner``, typically
-    produced by a separate compiled extension. ``session`` is the
-    :py:class:`~datafusion.context.SessionContext` the planner is being
-    installed on; take the extension codecs from it rather than building your
-    own.
+    produced by a separate compiled extension. ``session`` is a handle on the
+    session the planner is being installed on; take the extension codecs from
+    it rather than building your own.
+
+    Duck-type that handle rather than checking its type. It is the PyO3
+    context from ``datafusion._internal``, not the
+    :py:class:`~datafusion.context.SessionContext` wrapper, so it exposes every
+    capsule getter and ``__datafusion_codec_id__`` — which is all the protocol
+    asks of it — but ``isinstance(session, SessionContext)`` is ``False`` even
+    though its ``repr`` reads ``datafusion.SessionContext``. The same is true
+    of the codec getters in :py:mod:`datafusion.user_defined`. The two bundle
+    hooks are the exception: :py:class:`SessionExtensionExportable` and
+    :py:class:`SessionPlannerExportable` are dispatched from Python and receive
+    the wrapper.
     """
 
     def __datafusion_query_planner__(self, session: Any) -> object: ...  # noqa: D105