Name the execute partition index for what it is, trim the upgrade guide

`SessionContext.execute` took its second argument as `partitions`, which reads
as a count when it is a single partition index. Rename it to `partition` and
give the method a real docstring with a doctest covering both a full sweep over
`partition_count` and the out-of-range `ValueError`. Every call site in the
repo, docs, and examples passes it positionally, so add a short note to the
upgrade guide for anyone passing it by keyword.

Drop two changelog-shaped sections from the upgrade guide. `output_partitioning`
is additive and `SessionContext.execute` / `SessionConfig.set` only trade a
panic for a raise, so neither asks the reader to change anything. The
`with_extensions` recommendation goes for the same reason; it is advice, and the
extension guide already carries it under `extension_bundles`.

Also remove the comment above the partition range check. It explained the check
by way of a `MemorySourceConfig` panic, which reads as a complaint about
DataFusion's leaves. The index arrives straight from Python and no planner has
seen it, so validating it needs no more justification than any other argument
check at the boundary.

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

Author: timsaucer

crates/core/src/context.rs

@@ -1422,10 +1422,6 @@ impl PySessionContext {
     ) -> PyDataFusionResult<PyRecordBatchStream> {
         let ctx: TaskContext = TaskContext::from(&self.ctx.state());
         let plan = plan.plan.clone();
-        // Checked here because the leaves index their partitions directly: a
-        // `MemorySourceConfig` panics with a bare `index out of bounds`, which
-        // surfaces as a `JoinError::Panic` naming neither the plan nor the
-        // partition the caller asked for.
         let partition_count = plan.output_partitioning().partition_count();
         if part >= partition_count {
             return Err(PyValueError::new_err(format!(

docs/source/user-guide/upgrade-guides.md

@@ -96,16 +96,6 @@ way `add_physical_optimizer_rule` does and returns nothing — the query planner
 lives in `SessionState`, so it belongs to the session rather than to a
 particular handle on it. See {ref}`extension_planners` for the full protocol.
 
-If a library ships codecs *and* a planner, prefer
-`SessionContext.with_extensions(bundle)` over installing each piece by hand. It
-installs every codec before it binds any planner, so a planner cannot end up
-carrying a chain that a later `with_logical_extension_codec` call has grown.
-The library exposes a bundle object implementing
-`__datafusion_session_components__` for its codecs and
-`__datafusion_session_planner__` for its planner — the latter is handed the
-planner installed so far, so several libraries that each ship one nest instead
-of displacing each other. See {ref}`extension_bundles`.
-
 (extension_version_mismatch)=
 
 ### Mismatched extension libraries now fail loudly
@@ -169,41 +159,17 @@ installed produces the same bytes as before, as do functions encoded by name.
 Regenerate any plan you serialized with an earlier release and stored for later
 use, if it was produced by a session with an extension codec installed.
 
-### Physical plans report their partitioning scheme
+### `SessionContext.execute` renamed its second parameter
 
-{py:attr}`~datafusion.ExecutionPlan.output_partitioning` is new, and reports
-what {py:attr}`~datafusion.ExecutionPlan.partition_count` leaves out: whether
-the rows in those partitions are hash-distributed on known keys, spread
-round-robin, or merely counted. It returns a
-{py:class}`~datafusion.PhysicalPartitioning`.
+The parameter is a single partition index, not a count, and is now named
+`partition` rather than `partitions`. Positional calls are unaffected; update
+any call passing it by keyword.
 
 ```python
-partitioning = df.execution_plan().output_partitioning
-partitioning.scheme  # 'Hash', 'RoundRobinBatch', 'Range', 'UnknownPartitioning'
-partitioning.partition_count
-partitioning.hash_expressions  # display strings, or None
+ctx.execute(plan, partitions=0)  # before
+ctx.execute(plan, partition=0)  # after
 ```
 
-This is additive; `partition_count` keeps working and agrees with
-`output_partitioning.partition_count`. Note that
-{py:class}`datafusion.expr.Partitioning` is a different type: that one is the
-*logical* partitioning {py:meth}`~datafusion.DataFrame.repartition_by_hash`
-takes as a request, while this one is what a built plan actually does.
-
-### Two error paths that used to abort the interpreter
-
-{py:meth}`~datafusion.SessionContext.execute` now raises `ValueError` for a
-partition index that is out of range. Previously the plan's leaves indexed
-their partitions directly and the resulting Rust panic surfaced as an error
-naming neither the plan nor the index.
-
-{py:meth}`~datafusion.SessionConfig.set` now raises for a key whose namespace
-does not exist -- `datafusion.runtime.*`, or a config extension that has not
-been installed yet. Previously it aborted with a `PanicException`, which
-derives from `BaseException` and so escaped `except Exception`. This matters
-when replaying settings read back from `information_schema.df_settings`, which
-lists keys in both of those categories.
-
 ### Changes to the `datafusion-python-util` crate
 
 Extension libraries written in Rust usually depend on the

python/datafusion/context.py

@@ -2351,9 +2351,42 @@ def read_table(
         """Creates a :py:class:`~datafusion.dataframe.DataFrame` from a table."""
         return DataFrame(self.ctx.read_table(table))
 
-    def execute(self, plan: ExecutionPlan, partitions: int) -> RecordBatchStream:
-        """Execute the ``plan`` and return the results."""
-        return RecordBatchStream(self.ctx.execute(plan._raw_plan, partitions))
+    def execute(self, plan: ExecutionPlan, partition: int) -> RecordBatchStream:
+        """Execute a single partition of ``plan`` and stream its batches.
+
+        Args:
+            plan: The physical plan to execute.
+            partition: Index of the partition to execute, in
+                ``range(plan.partition_count)``.
+
+        Returns:
+            A stream over the record batches that partition produces.
+
+        Raises:
+            ValueError: If ``partition`` is not a valid index for ``plan``.
+
+        Example usage:
+
+        >>> import pyarrow as pa
+        >>> from datafusion import SessionContext
+        >>> ctx = SessionContext()
+        >>> ctx.register_record_batches(
+        ...     "t", [[pa.record_batch({"a": [1, 2]})], [pa.record_batch({"a": [3]})]]
+        ... )
+        >>> plan = ctx.sql("select a from t").execution_plan()
+        >>> plan.partition_count
+        2
+        >>> sum(
+        ...     batch.to_pyarrow().num_rows
+        ...     for p in range(plan.partition_count)
+        ...     for batch in ctx.execute(plan, p)
+        ... )
+        3
+        >>> ctx.execute(plan, 2)
+        Traceback (most recent call last):
+        ValueError: Partition index 2 is out of range for a plan with 2 partition(s)
+        """
+        return RecordBatchStream(self.ctx.execute(plan._raw_plan, partition))
 
     @staticmethod
     def _convert_file_sort_order(

python/tests/test_plans.py

@@ -145,12 +145,7 @@ def test_output_partitioning_reports_the_scheme_not_just_the_count() -> None:
 
 
 def test_execute_rejects_an_out_of_range_partition() -> None:
-    """An out-of-range partition index raises instead of panicking.
-
-    The leaves index their partition vector directly, so without this check a
-    bad index surfaces as a `JoinError::Panic` carrying `index out of bounds`
-    and naming neither the plan nor the index requested.
-    """
+    """An out-of-range partition index raises instead of panicking."""
     ctx = SessionContext()
     ctx.register_record_batches("t", [[pa.record_batch({"a": [1, 2, 3]})]])
     plan = ctx.sql("select a from t").execution_plan()