Merge branch 'implement-119127' into implement-119127-again

Author: dg-pb

Doc/library/functools.rst

@@ -358,6 +358,18 @@ The :mod:`functools` module defines the following functions:
       >>> basetwo('10010')
       18
 
+   If ``Placeholder`` sentinels are present in *args*, they will be filled first
+   when :func:`partial` is called. This allows custom selection of positional arguments
+   to be pre-filled when constructing :ref:`partial object<partial-objects>`.
+   If ``Placeholder`` sentinels are used, all of them must be filled at call time.:
+
+      >>> from functools import partial, Placeholder
+      >>> say_to_world = partial(print, Placeholder, 'world!')
+      >>> say_to_world('Hello')
+      Hello world!
+
+   .. versionchanged:: 3.14
+      Support for ``Placeholder`` in *args*
 
 .. class:: partialmethod(func, /, *args, **keywords)
 

Lib/functools.py

@@ -273,6 +273,11 @@ def reduce(function, sequence, initial=_initial_missing):
 ### partial() argument application
 ################################################################################
 
+
+class Placeholder:
+    """placeholder for partial arguments"""
+
+
 # Purely functional, no descriptor behaviour
 class partial:
     """New function with partial application of the given arguments
@@ -285,8 +290,33 @@ def __new__(cls, func, /, *args, **keywords):
         if not callable(func):
             raise TypeError("the first argument must be callable")
 
+        np = 0
+        nargs = len(args)
+        if args:
+            while nargs and args[nargs-1] is Placeholder:
+                nargs -= 1
+            args = args[:nargs]
+            np = args.count(Placeholder)
         if isinstance(func, partial):
-            args = func.args + args
+            pargs = func.args
+            pnp = func.np
+            if pnp and args:
+                all_args = list(pargs)
+                nargs = len(args)
+                j, pos = 0, 0
+                end = nargs if nargs < pnp else pnp
+                while j < end:
+                    pos = all_args.index(Placeholder, pos)
+                    all_args[pos] = args[j]
+                    j += 1
+                    pos += 1
+                if pnp < nargs:
+                    all_args.extend(args[pnp:])
+                np += pnp - end
+                args = tuple(all_args)
+            else:
+                np += pnp
+                args = func.args + args
             keywords = {**func.keywords, **keywords}
             func = func.func
 
@@ -295,11 +325,27 @@ def __new__(cls, func, /, *args, **keywords):
         self.func = func
         self.args = args
         self.keywords = keywords
+        self.np = np
         return self
 
     def __call__(self, /, *args, **keywords):
-        keywords = {**self.keywords, **keywords}
-        return self.func(*self.args, *args, **keywords)
+        if not hasattr(self, 'np'):
+            self.np = self.args.count(Placeholder)
+        if np := self.np:
+            if len(args) < np:
+                raise TypeError("unfilled placeholders in 'partial' call")
+            f_args = list(self.args)
+            j, pos = 0, 0
+            while j < np:
+                pos = f_args.index(Placeholder, pos)
+                f_args[pos] = args[j]
+                j += 1
+                pos += 1
+            keywords = {**self.keywords, **keywords}
+            return self.func(*f_args, *args[np:], **keywords)
+        else:
+            keywords = {**self.keywords, **keywords}
+            return self.func(*self.args, *args, **keywords)
 
     @recursive_repr()
     def __repr__(self):
@@ -340,7 +386,7 @@ def __setstate__(self, state):
         self.keywords = kwds
 
 try:
-    from _functools import partial
+    from _functools import partial, Placeholder
 except ImportError:
     pass
 

Lib/test/test_functools.py

@@ -210,6 +210,43 @@ def foo(bar):
         p2.new_attr = 'spam'
         self.assertEqual(p2.new_attr, 'spam')
 
+    def test_placeholders_trailing_trim(self):
+        PH = self.module.Placeholder
+        for args in [(PH,), (PH, 0), (0, PH), (0, PH, 1, PH, PH, PH)]:
+            expected, n = tuple(args), len(args)
+            while n and args[n-1] is PH:
+                n -= 1
+            expected = expected[:n]
+            p = self.partial(capture, *args)
+            self.assertTrue(p.args == expected)
+
+    def test_placeholders(self):
+        PH = self.module.Placeholder
+        # 1 Placeholder
+        args = (PH, 0)
+        p = self.partial(capture, *args)
+        got, empty = p('x')
+        self.assertTrue(('x', 0) == got and empty == {})
+        # 2 Placeholders
+        args = (PH, 0, PH, 1)
+        p = self.partial(capture, *args)
+        with self.assertRaises(TypeError):
+            got, empty = p('x')
+        got, empty = p('x', 'y')
+        expected = ('x', 0, 'y', 1)
+        self.assertTrue(expected == got and empty == {})
+
+    def test_placeholders_optimization(self):
+        PH = self.module.Placeholder
+        p = self.partial(capture, PH, 0)
+        p2 = self.partial(p, PH, 1, 2, 3)
+        expected = (PH, 0, 1, 2, 3)
+        self.assertTrue(expected == p2.args)
+        p3 = self.partial(p2, -1, 4)
+        got, empty = p3(5)
+        expected = (-1, 0, 1, 2, 3, 4, 5)
+        self.assertTrue(expected == got and empty == {})
+
     def test_repr(self):
         args = (object(), object())
         args_repr = ', '.join(repr(a) for a in args)

Misc/NEWS.d/next/Library/2024-05-25-00-54-26.gh-issue-119127.LpPvag.rst

@@ -0,0 +1,2 @@
+``partial`` of ``functools`` module now supports placeholders for positional
+arguments.