refactor: collapse the two collision messages into one

The branch on `claimed_at == position` produced two messages so each could
name only the remedy its reader could apply. One message naming both argument
positions carries the same information: two different positions means two
bundles and is the caller's to resolve, one position named twice means a
single bundle claimed the name twice and is its author's. The reader works
that out from the numbers, which were already in the message.

Position-keying still matters and keeps its comment -- object identity would
read one extension passed twice as a bundle colliding with itself, and offer a
rename of someone else's function that the caller cannot make.

`test_with_extensions_rejects_one_extension_passed_twice` loses its assertion
that the message never says "rename", which is the behaviour being removed; it
and its sibling now pin the argument positions instead, which is what tells
the two cases apart. Docstrings and both guides drop the "two extensions"
framing -- one extension declaring a name twice was always refused too.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: timsaucer

docs/source/extension-guide/bundles.md

@@ -290,27 +290,27 @@ a capsule.
 
 ## Two bundles claiming one name
 
-Two extensions in one call may not declare a function of the same kind under
-the same name. Doing so raises:
+One `with_extensions` call may not declare a function of the same kind under
+the same name twice. Doing so raises:
 
 ```text
-ValueError: Two extensions declare a scalar function named 'normalize':
-argument 0 (...) and argument 1 (...). ...
+ValueError: A scalar function named 'normalize' is declared twice: argument 0
+(<lib_a.Extension>) and argument 1 (<lib_b.Extension>). ...
 ```
 
 Codecs get away with sharing a chain because a payload carries the id of the
 codec that wrote it, so decode routes to the right one. A function registry has
 no such fall-through — one name holds one function — so the second registration
 would quietly replace the first. The call refuses instead.
 
-Which argument each claim came from is part of the message because it is what
-picks the remedy. Two arguments colliding is the caller's to resolve, by
-installing the two on separate sessions or by dropping a repeat; renaming is
-not something a caller can do. One argument declaring a name twice is the
-bundle author's own bug, and gets a different message saying so. Collisions are
-keyed on position rather than on object identity, so passing one extension
-twice reads as the caller's duplicate that it is, rather than as a bundle
-colliding with itself.
+The argument each claim came from is in the message because it is what picks
+the remedy, and the reader works it out from the two positions. Two different
+positions means two bundles, which only the caller can resolve — by dropping a
+repeat, or by installing them on separate sessions. One position named twice
+means a single bundle claimed the name twice, which is its author's own bug and
+the one case a rename fixes. Collisions are keyed on position rather than on
+object identity so that passing one extension twice reads as the caller's
+duplicate that it is, rather than as a bundle colliding with itself.
 
 Three cases this does *not* catch:
 

docs/source/user-guide/extensions.md

@@ -106,7 +106,8 @@ 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 named 'normalize': ...
+ValueError: A scalar function named 'normalize' is declared twice: argument 0
+(<lib_a.Extension>) and argument 1 (<lib_b.Extension>). ...
 ```
 
 You cannot rename another library's function from your own code, so the fix is
@@ -121,6 +122,8 @@ supported thing for a library to do. See {ref}`extension_bundles_collisions`.
 Check the argument positions the message names before you go looking for a
 second library. Passing one extension twice collides with itself, and an
 extension list assembled from a plugin registry is the usual way that happens.
+If both positions are the *same* number, only one library is involved and it
+declared the name twice — nothing on your side fixes that, so report it.
 
 **Functions outlive the handle you installed them on.** `with_extensions`
 returns a new context, and its codecs belong to that context alone — but

python/datafusion/context.py

@@ -296,25 +296,19 @@ def _resolve_declared_functions(
             raise TypeError(msg)
         name = wrapped.name
         if name in claimed:
-            # Keyed on position, not object identity, so each message names
-            # the remedy its reader actually has — see
+            # Keyed on position, not object identity: one argument listed
+            # twice is what tells the reader a single bundle claimed the name
+            # twice, which is the only case a rename can fix. See
             # `extension_bundles_collisions` in the extension guide.
             claimed_at, claimed_by = claimed[name]
-            if claimed_at == position:
-                msg = (
-                    f"{extension!r} declares two {label}s named {name!r}. "
-                    "Registrations have no fall-through, so the second would "
-                    "silently replace the first; rename one of them."
-                )
-            else:
-                msg = (
-                    f"Two extensions declare a {label} named {name!r}: "
-                    f"argument {claimed_at} ({claimed_by!r}) and argument "
-                    f"{position} ({extension!r}). Registrations have no "
-                    "fall-through, so one would silently replace the other; "
-                    "install them on separate sessions, or drop the repeat if "
-                    "one extension was passed twice."
-                )
+            msg = (
+                f"A {label} named {name!r} is declared twice: argument "
+                f"{claimed_at} ({claimed_by!r}) and argument {position} "
+                f"({extension!r}). Registrations have no fall-through, so one "
+                "would silently replace the other. Rename one if both came "
+                "from an extension you own, drop the repeat if one extension "
+                "was passed twice, or install them on separate sessions."
+            )
             raise ValueError(msg)
         claimed[name] = (position, extension)
         resolved.append(wrapped)
@@ -2103,8 +2097,8 @@ def with_extensions(
                 ``PyCapsule`` rather than an object exposing the getter, or if
                 a declared function is neither a wrapper nor exposes its
                 capsule getter.
-            ValueError: If two codecs claim the same id, if two extensions
-                declare a function of one kind under the same name, or if a
+            ValueError: If two codecs claim the same id, if one call declares a
+                function of one kind under the same name twice, or if a
                 getter returns a capsule of the wrong kind. See
                 :py:meth:`with_logical_extension_codec` for how ids are
                 assigned.

python/datafusion/extensions.py

@@ -233,10 +233,10 @@ class SessionExtensionComponents:
     :py:func:`~datafusion.udf` on the way in. The registered name comes from
     the function itself, not from this field.
 
-    Two extensions in one
-    :py:meth:`~datafusion.context.SessionContext.with_extensions` call may not
-    declare the same name; shadowing a function the session already has is
-    allowed. See :ref:`extension_bundles_collisions`.
+    One :py:meth:`~datafusion.context.SessionContext.with_extensions` call may
+    not declare a name twice, whether the two claims come from one extension or
+    two; shadowing a function the session already has is allowed. See
+    :ref:`extension_bundles_collisions`.
     """
 
     udafs: tuple[AggregateUDF | AggregateUDFExportable, ...] = ()

python/tests/test_context.py

@@ -1570,34 +1570,31 @@ def test_with_extensions_rejects_a_name_two_extensions_claim(
 def test_with_extensions_rejects_one_extension_passed_twice(ctx):
     """A bundle object listed twice is the caller's duplicate, not a naming bug.
 
-    The remedy has to match the mistake, and nothing the bundle author renames
-    helps here — both claims come from the one declaration. Collisions are
-    therefore keyed on argument position rather than on object identity, which
-    would read a repeat as a bundle colliding with itself and offer a rename
-    that cannot be made.
+    Two argument positions is what says so, and it is the reason collisions are
+    keyed on position rather than on object identity: identity would read a
+    repeat as one bundle colliding with itself, pointing the reader at a rename
+    of someone else's function that they cannot make.
     """
     extension = _FunctionExtension(udfs=(_doubler(),))
 
-    with pytest.raises(ValueError, match=r"argument 0 .* and argument 1 ") as excinfo:
+    with pytest.raises(ValueError, match=r"argument 0 .* and argument 1 "):
         ctx.with_extensions(extension, extension)
 
-    assert "rename" not in str(excinfo.value)
     with pytest.raises(KeyError):
         ctx.udf("double")
 
 
 def test_with_extensions_rejects_a_name_one_extension_claims_twice(ctx):
-    """A bundle colliding with itself is its own bug, not a clash of libraries.
+    """A bundle colliding with itself is caught by the same check.
 
-    Separated from the two-extension case because the remedy differs: a bundle
-    author can rename their own function, and a caller cannot rename someone
-    else's.
+    One argument position named twice is what distinguishes it, and it is the
+    case the message's rename remedy is for — the only reader who can rename a
+    function is the one who declared both of them.
     """
-    with pytest.raises(
-        ValueError, match=r"declares two scalar functions named 'double'"
-    ):
+    with pytest.raises(ValueError, match=r"argument 0 .* and argument 0 ") as excinfo:
         ctx.with_extensions(_FunctionExtension(udfs=(_doubler(), _doubler())))
 
+    assert "scalar function named 'double'" in str(excinfo.value)
     with pytest.raises(KeyError):
         ctx.udf("double")