Correct three claims in the extension bundle docs

The `SessionExtensionComponents` doctest took its codec capsule off a
`SessionContext()` that was dropped on the same line. An FFI codec holds its
task-context provider weakly, so that capsule names a session that is already
gone — the doctest only reads an id back so it passes, but it is the exact
shape the FFI guide warns against. It now keeps the context in a name.

`SessionPlannerExportable` called returning `fallback` a wrap that "contributes
nothing". It is not: the capsule the first bundle receives wraps the session's
planner for export, so handing it back installs it as a foreign planner and
every later plan crosses an FFI boundary that was not there before. `None` is
the no-op. Corrected in the protocol docstring, the FFI guide's canonical
section, and the `_PlannerExtension` test helper that repeated the claim.

`__post_init__` walked a written-out list of field names. It now walks
`dataclasses.fields`, filtered on the `_codecs` suffix so a codec field added
later is normalized without anyone remembering to name it, and a future field
that is not a codec collection is left alone.

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

Author: timsaucer

docs/source/contributor-guide/ffi.md

@@ -412,6 +412,11 @@ library that must be the only planner does it deliberately — but it is not com
 and nothing detects it. Returning `None` contributes no planner and leaves `fallback`
 in place.
 
+`None` is the no-op, not `fallback`. The capsule handed to the first bundle wraps the
+session's planner for export, so returning it unchanged installs that planner as a
+foreign one and every plan built afterwards crosses an FFI boundary it did not before.
+A bundle that decides at runtime it has nothing to contribute returns `None`.
+
 Three libraries that each ship a planner therefore install like this, with the
 outermost last:
 

python/datafusion/extensions.py

@@ -48,7 +48,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, fields
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
@@ -135,7 +135,15 @@ class SessionExtensionComponents:
         ...
         ...     def __datafusion_logical_extension_codec__(self, session=None):
         ...         return self._capsule
-        >>> capsule = SessionContext().__datafusion_logical_extension_codec__()
+
+        The context stays in scope for as long as the codec does. An
+        ``FFI_LogicalExtensionCodec`` holds its task-context provider *weakly*,
+        so a capsule taken off a throwaway ``SessionContext()`` names a session
+        that is already gone and fails on first use with ``TaskContextProvider
+        went out of scope over FFI boundary``:
+
+        >>> ctx = SessionContext()
+        >>> capsule = ctx.__datafusion_logical_extension_codec__()
         >>> components = SessionExtensionComponents(
         ...     logical_extension_codecs=(NamedCodec(capsule),)
         ... )
@@ -183,8 +191,17 @@ def __post_init__(self) -> None:
         and the class is frozen, so a list left in place would be a mutable
         member of an immutable value, and a generator would be exhausted by
         the first read.
+
+        Driven off :py:func:`dataclasses.fields` rather than a written-out
+        list, so a codec field added later is normalized without anyone
+        remembering to name it here. The ``_codecs`` suffix is what marks a
+        field as one of them, leaving room for a future field that is not a
+        codec collection and must not be turned into a tuple.
         """
-        for name in ("logical_extension_codecs", "physical_extension_codecs"):
+        for field in fields(self):
+            name = field.name
+            if not name.endswith("_codecs"):
+                continue
             value = getattr(self, name)
             # A str is iterable, so it would otherwise normalize into a tuple
             # of characters and fail much later as that many bogus codecs.
@@ -257,6 +274,12 @@ class SessionPlannerExportable(Protocol):
     not left encoding through a chain that a later bundle has grown.
 
     Return ``None`` to contribute no planner and leave ``fallback`` in place.
+    That is the no-op, and it is not the same as returning ``fallback``: the
+    capsule the first bundle receives wraps the session's planner for export, so
+    handing it back installs it as a foreign planner and every later plan crosses
+    an FFI boundary that was not there before. A bundle with nothing to
+    contribute returns ``None``.
+
     Ignoring ``fallback`` and returning a planner that does not delegate to it
     is legal and means "replace" — but it discards every planner listed before
     this one, including any the session already had.
@@ -274,8 +297,9 @@ class SessionPlannerExportable(Protocol):
         ...     def __datafusion_session_planner__(self, ctx, fallback):
         ...         # A real library returns its own planner wrapping
         ...         # `fallback`, e.g. ``my_library.Planner(fallback=fallback)``.
-        ...         # Handing it straight back is the degenerate wrap: valid,
-        ...         # and contributes nothing.
+        ...         # Handing it straight back is the degenerate wrap: legal,
+        ...         # but it still installs `fallback` as a foreign planner.
+        ...         # Return None instead to contribute nothing.
         ...         return fallback
         >>> isinstance(MyEngineExtension(), SessionPlannerExportable)
         True

python/tests/test_context.py

@@ -935,9 +935,11 @@ def __datafusion_session_extension__(self, ctx):
 class _PlannerExtension:
     """Contributes a planner, recording the fallback it was handed.
 
-    Passing ``fallback`` straight back through is the degenerate wrap: the
-    resulting session plans exactly as it did before, which is what lets a
-    pure-Python test assert the threading without a real layering planner.
+    Passing ``fallback`` straight back through is the degenerate wrap: it plans
+    the same queries to the same plans, which is what lets a pure-Python test
+    assert the threading without a real layering planner. It is not a no-op —
+    the capsule gets installed, so the session ends up planning through a
+    foreign planner — but nothing here depends on that either way.
     """
 
     def __init__(self):