docs: put each bundle-functions claim in front of its own audience

The docs added alongside the new `udfs`/`udafs`/`udwfs` fields mixed three
readerships. Sorting them out:

The four-step Collect/Chains/Resolve/Commit list, and the rule it imposes on
whoever adds the next `SessionExtensionComponents` field, moves from the
extension guide to `contributor-guide/ffi-internals.md`, which already declares
itself the page you do *not* need to write an extension library. The extension
guide keeps only what an author acts on — declare, do not register — and links
across. The comment in `with_extensions` that states the same rule now points
at the new label rather than at the extension-facing one.

`Two bundles claiming one name` becomes a `##` and moves ahead of `Failure and
rollback`, which it had been splitting: the paragraphs closing that section
were rendering under the collision heading.

The user guide gains the collision as its own entry under what will bite you,
with the error text and the two-sessions workaround, since it is raised by a
call the user makes and cannot fix in their own code. Its section heading no
longer says "two kinds" over three, the functions paragraph moves above the
note that closes the section, and the discovery section covers `udfs()` and
friends rather than codec ids alone.

The bundle snippet in `functions.md` names `MyFunctionExtension` and this
crate's real function names, separates the author's class from the caller's
line, and says the cdylib can export the getter directly — it had implied a
Rust library ships a Python shim. The table's `—` for table functions now says
what to do instead.

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

Author: timsaucer

docs/source/contributor-guide/ffi-internals.md

@@ -111,6 +111,43 @@ library would serialize, and would do it with the codecs it was imported with.
 The extension-facing consequence — install codecs before a layered planner, and
 prefer `with_extensions` — is documented at {ref}`planner_codec_rebinding`.
 
+(ffi_internals_commit_order)=
+
+## Why `with_extensions` commits last
+
+`with_extensions` promises that a bundle which raises leaves the session as it
+was. Keeping that promise is an ordering constraint on the implementation,
+because the components a bundle declares no longer all live on the returned
+handle — functions are registered on the shared `SessionState`, and the planner
+is bound there too.
+
+A call therefore splits into a part that may fail and a part that may not:
+
+1. **Collect.** Every `__datafusion_session_components__` runs.
+2. **Chains.** The codecs are assembled into the returned handle. Codec chains
+   live on that handle rather than on the session, so this step writes nothing
+   even though it can fail on a bad capsule or a duplicate id.
+3. **Resolve.** Every declared function is wrapped and every name is checked,
+   and every `__datafusion_session_planner__` runs against the completed
+   chains.
+4. **Commit.** The planner is bound and the functions are registered.
+
+Only step 4 touches the session, and every step that can fail happens before
+it. This is a rule for the next field added to
+`SessionExtensionComponents`, not only a description of the current code: a new
+kind of component must do its fallible work — importing a capsule, resolving a
+name — in step 3, so that step 4 cannot raise part-way through.
+
+There is nothing to roll back to if it does. The returned handle shares one
+session with the receiver, so the damage is visible from every other handle;
+and undoing a registration is not the same as restoring what it displaced,
+because deregistering a function that shadowed a built-in removes the built-in
+too. The split is cheaper than an undo log that cannot be written correctly.
+
+The extension-facing statement of this is
+{ref}`extension_bundles_transaction`, which says only that declaring a
+component is safe where registering one during the hook is not.
+
 ## Two argument kinds for one convention
 
 `CapsuleGetterArg` in `crates/util/src/lib.rs` distinguishes three cases: no

docs/source/extension-guide/bundles.md

@@ -289,41 +289,9 @@ for direct ones. The wrapper travels with the codec; the bundle does not.
 The query planner is exempt — it carries no wire id, so it may be an object or
 a capsule.
 
-(extension_bundles_transaction)=
-
-## Failure and rollback
-
-Nothing is written to the session until every factory has returned and every
-component has been validated, so a factory that raises leaves the session
-exactly as it was. A factory that mutates the context it is handed —
-registering a table, say — is **not** rolled back, which is why bundle objects
-must be configuration-only: create fresh components on each call, never cache
-bound components, and do not retain the context passed in.
-
-That guarantee is why the installation runs in the order it does. A call splits
-into a part that may fail and a part that may not:
-
-1. **Collect.** Every `__datafusion_session_components__` runs.
-2. **Chains.** The codecs are assembled into the returned handle. Codec chains
-   live on that handle rather than on the session, so this step writes nothing
-   even though it can fail on a bad capsule or a duplicate id.
-3. **Resolve.** Every declared function is wrapped and every name is checked,
-   and every `__datafusion_session_planner__` runs against the completed
-   chains.
-4. **Commit.** The planner is bound and the functions are registered.
-
-Only step 4 touches the session, and every step that can fail happens before
-it. This is a rule for anyone extending `with_extensions`, not only a
-description: a new kind of component must do its fallible work — importing a
-capsule, resolving a name — in step 3, so that step 4 cannot raise part-way
-through. There is nothing to roll back to if it does. The returned handle
-shares one session with the receiver, and undoing a registration is not the
-same as restoring what it displaced: deregistering a function that shadowed a
-built-in removes the built-in too.
-
 (extension_bundles_collisions)=
 
-### Two bundles claiming one name
+## Two bundles claiming one name
 
 Within a single call, two extensions declaring a function of the same kind
 under the same name is a `ValueError` naming both. Codec ids dispatch on
@@ -336,6 +304,29 @@ Shadowing a name the session *already* has is allowed and is not a collision.
 The registry holds every DataFusion built-in, and overriding built-ins by name
 is a supported thing to do — `enable_spark_functions` is built on it.
 
+Since the caller cannot repair a collision from their own code, name your
+functions so this does not arise: a prefix tying them to your library is the
+usual answer.
+
+(extension_bundles_transaction)=
+
+## Failure and rollback
+
+Nothing is written to the session until every factory has returned and every
+component has been validated, so a factory that raises leaves the session
+exactly as it was. A factory that mutates the context it is handed —
+registering a table, say — is **not** rolled back, which is why bundle objects
+must be configuration-only: create fresh components on each call, never cache
+bound components, and do not retain the context passed in.
+
+Declaring a component is what buys you that guarantee, and it is the whole
+reason to prefer `udfs=(...)` over a `register_udf` call inside your hook.
+Anything you declare is resolved and checked while a failure still costs
+nothing, and is written only after every bundle in the call has succeeded.
+Anything you register yourself is written immediately, before the other bundles
+have even run. The ordering that makes this hold is recorded at
+{ref}`ffi_internals_commit_order`.
+
 Like every other derivation, the returned context is a handle on the *same*
 session as the receiver — see {ref}`extension_sessions`. Only the Python-side
 codec chains belong to the returned handle; the planner is installed on the

docs/source/extension-guide/functions.md

@@ -33,7 +33,11 @@ the same registration methods.
 | `__datafusion_window_udf__` | window function | {py:func}`datafusion.udwf` | {py:meth}`~datafusion.SessionContext.register_udwf` | `udwfs` |
 | `__datafusion_table_function__` | function returning a table | {py:func}`datafusion.udtf` | {py:meth}`~datafusion.SessionContext.register_udtf` | — |
 
-All four are implemented in [`datafusion-ffi-example`], one per file.
+All four are implemented in [`datafusion-ffi-example`], one per file. The last
+column is the {py:class}`~datafusion.SessionExtensionComponents` field a
+{ref}`bundle <extension_bundles>` declares the function in; table functions
+have no such field yet, so they are always registered by the caller with
+{py:meth}`~datafusion.SessionContext.register_udtf`.
 
 ## The three scalar-shaped hooks
 
@@ -67,21 +71,38 @@ from datafusion import udf
 ctx.register_udf(udf(my_library.MyScalarUDF()))
 ```
 
-If your library ships more than a function or two, declare them on a bundle
-instead and let one call install everything:
+If your library ships more than a function or two, do not make your users write
+that line once per function. Ship a {ref}`bundle <extension_bundles>` declaring
+them, so one call installs the lot:
 
 ```python
-class MyLibraryExtension:
-    def __datafusion_session_components__(self, ctx):
-        return SessionExtensionComponents(udfs=(my_library.MyScalarUDF(),))
+ctx = SessionContext().with_extensions(my_library.MyFunctionExtension())
+```
+
+The bundle is yours to write, and like the rest of the protocol it is an object
+exposing a getter — which your cdylib can export directly. That is what
+`MyFunctionExtension` in [`datafusion-ffi-example`] does for this crate's three
+functions; spelled in Python, it is:
+
+```python
+from datafusion import SessionExtensionComponents
 
 
-ctx = SessionContext().with_extensions(MyLibraryExtension())
+class MyFunctionExtension:
+    def __datafusion_session_components__(self, ctx):
+        return SessionExtensionComponents(
+            udfs=(IsNullUDF(),),
+            udafs=(MySumUDF(),),
+            udwfs=(MyRankUDF(),),
+        )
 ```
 
-Either the raw exportable or an already-wrapped
-{py:class}`~datafusion.user_defined.ScalarUDF` is accepted; the name comes off
-the capsule either way. See {ref}`extension_bundles`.
+Declare either the raw exportable, as here, or an already-wrapped
+{py:class}`~datafusion.user_defined.ScalarUDF`; the registered name comes off
+the function either way. Declare rather than calling `register_udf` inside the
+hook — see {ref}`extension_bundles_transaction` for why — and pick names that
+will not collide with another library's
+({ref}`extension_bundles_collisions`).
 
 ## Table functions
 

docs/source/user-guide/extensions.md

@@ -32,9 +32,9 @@ which exposes Delta Lake tables to DataFusion, and the two worked examples in
 this repository under
 [`examples/`](https://github.com/apache/datafusion-python/tree/main/examples).
 
-## Two kinds of extension
+## How an extension reaches your session
 
-Which one you have determines how much setup you do.
+Which route your library takes determines how much setup you do.
 
 **Tables register directly.** If the library gives you a table, register it
 the same way you would register a CSV file. No extra setup:
@@ -63,17 +63,25 @@ ctx.register_table("events", my_engine.TableProvider("s3://bucket/events"))
 ctx.sql("SELECT count(*) FROM events").show()
 ```
 
+**Functions arrive by whichever route their library chose.** A library
+offering one or two functions hands you the functions themselves, and you wrap
+and register each:
+
+```python
+from datafusion import udf
+
+ctx.register_udf(udf(my_library.MyScalarUDF()))
+```
+
+A library shipping a set of them packages them in its `Extension` object
+instead, so `with_extensions` installs them all along with everything else it
+provides, and there is nothing per-function for you to do. Its documentation
+says which.
+
 `with_extensions` returns a context; use the returned one. It shares
 everything else with the context you called it on, so tables you registered
 before the call are still there.
 
-**Functions can arrive either way.** A single function is registered directly
-with {py:func}`~datafusion.udf` and
-{py:meth}`~datafusion.SessionContext.register_udf`. A library shipping a set of
-them usually packages them in the same `Extension` object instead, so
-`with_extensions` installs them along with everything else it provides. Follow
-whichever the library documents.
-
 ## Using more than one library
 
 Pass them all to a single call:
@@ -91,7 +99,24 @@ rarely matters. When a library needs a particular position — usually "list me
 last" for something that wraps the others — it says so in its own
 documentation.
 
-## Two things that will bite you
+## Three things that will bite you
+
+**Two libraries can claim one function name.** If both ship a function of the
+same kind under the same name, the call raises a `ValueError` naming both,
+rather than letting one silently replace the other:
+
+```text
+ValueError: Two extensions declare a scalar function 'normalize': ...
+```
+
+You cannot rename another library's function from your own code, so the fix is
+to use two sessions, one per library, and query each for what only it provides.
+Worth reporting upstream too: the library whose names are the less specific
+should be prefixing them. A function shadowing a *built-in* is not a collision
+and raises nothing — that is a supported thing for a library to do. See
+{ref}`extension_bundles_collisions`.
+
+
 
 **Keep your context alive.** A `DataFrame` or a plan does not keep its session
 alive on its own. If a context is garbage-collected while something built from
@@ -139,6 +164,17 @@ ctx.logical_extension_codec_ids()
 
 An empty list means nothing extra is installed.
 
+For functions, {py:meth}`~datafusion.SessionContext.udfs`,
+{py:meth}`~datafusion.SessionContext.udafs` and
+{py:meth}`~datafusion.SessionContext.udwfs` return the names a session knows.
+Both the library's and every DataFusion built-in are in there, so look for the
+name rather than reading the whole list:
+
+```python
+"my_engine_normalize" in ctx.udfs()
+# True
+```
+
 ## Next steps
 
 - {ref}`distributed_query_engines` — running your queries across several

python/datafusion/context.py

@@ -2178,7 +2178,7 @@ def with_extensions(
         # commit can fail belongs above, split into an import step that returns
         # a resolved object and an insert step that cannot raise -- there is one
         # session here, shared with the receiver, so a failure part-way through
-        # has nothing to roll back to. See :ref:`extension_bundles_transaction`.
+        # has nothing to roll back to. See :ref:`ffi_internals_commit_order`.
         if planner is not None or logical_codecs or physical_codecs:
             new.ctx._install_extension_planner(planner)
         for function in resolved_udfs: