minor fixes; message, doc polish

Author: dg-pb

Doc/library/functools.rst

@@ -348,7 +348,7 @@ The :mod:`functools` module defines the following functions:
 
    The :func:`partial` is used for partial function application which "freezes"
    some portion of a function's arguments and/or keywords resulting in a new object
-   with a simplified signature.  For example, :func:`partial` can be used to create
+   with a simplified signature. For example, :func:`partial` can be used to create
    a callable that behaves like the :func:`int` function where the *base* argument
    defaults to two:
 
@@ -362,7 +362,7 @@ The :mod:`functools` module defines the following functions:
    when :func:`partial` is called. This allows custom selection of positional arguments
    to be pre-filled when constructing a :ref:`partial object <partial-objects>`.
 
-   If :data:`!Placeholder` sentinels are used, all of them must be filled at call time:
+   If :data:`!Placeholder` sentinels are present, all of them must be filled at call time:
 
       >>> from functools import partial, Placeholder
       >>> say_to_world = partial(print, Placeholder, Placeholder, "world!")

Doc/whatsnew/3.14.rst

@@ -117,6 +117,14 @@ Added support for converting any objects that have the
 :meth:`!as_integer_ratio` method to a :class:`~fractions.Fraction`.
 (Contributed by Serhiy Storchaka in :gh:`82017`.)
 
+functools
+---------
+
+* Added support to :func:`functools.partial` and
+  :func:`functools.partialmethod` for :data:`functools.Placeholder` sentinels
+  to reserve a place for positional arguments.
+  (Contributed by Dominykas Grigonis in :gh:`119127`.)
+
 json
 ----
 
@@ -133,14 +141,6 @@ operator
   to ``obj is not None``.
   (Contributed by Raymond Hettinger and Nico Mexis in :gh:`115808`.)
 
-functools
----------
-
-* :func:`functools.partial` and :func:`functools.partialmethod` now support
-  :data:`functools.Placeholder` sentinels to reserve a place for
-  positional arguments.
-  (Contributed by Dominykas Grigonis in :gh:`119127`)
-
 os
 --
 

Lib/functools.py

@@ -301,9 +301,9 @@ def __reduce__(self):
 Placeholder = _PlaceholderType()
 
 def _partial_prepare_merger(args):
-    nargs = len(args)
-    if not nargs:
+    if not args:
         return 0, None
+    nargs = len(args)
     order = []
     j = nargs
     for i, a in enumerate(args):
@@ -324,9 +324,9 @@ def _partial_new(cls, func, /, *args, **keywords):
     else:
         base_cls = partialmethod
         # func could be a descriptor like classmethod which isn't callable
-        # assert issubclass(cls, partialmethod)
         if not callable(func) and not hasattr(func, "__get__"):
-            raise TypeError(f"{func!r} is not callable or a descriptor")
+            raise TypeError(f"the first argument {func!r} must be a callable "
+                            "or a descriptor")
     if args and args[-1] is Placeholder:
         raise TypeError("trailing Placeholders are not allowed")
     if isinstance(func, base_cls):
@@ -459,7 +459,7 @@ def _method(cls_or_self, /, *args, **keywords):
                     args = args[phcount:]
                 except IndexError:
                     raise TypeError("missing positional arguments "
-                                    "in 'partial' call; expected "
+                                    "in 'partialmethod' call; expected "
                                     f"at least {phcount}, got {len(args)}")
             else:
                 pto_args = self.args

Lib/inspect.py

@@ -2464,7 +2464,7 @@ def _signature_from_callable(obj, *,
                 assert (not sig_params or
                         first_wrapped_param is not sig_params[0])
                 # If there were placeholders set,
-                #   first param is transformaed to positional only
+                #   first param is transformed to positional only
                 if partialmethod.args.count(functools.Placeholder):
                     first_wrapped_param = first_wrapped_param.replace(
                         kind=Parameter.POSITIONAL_ONLY)

Lib/test/test_functools.py

@@ -364,14 +364,19 @@ def test_setstate(self):
         f = self.partial(signature)
         f.__setstate__((capture, (PH, 1), dict(a=10), dict(attr=[])))
         self.assertEqual(signature(f), (capture, (PH, 1), dict(a=10), dict(attr=[])))
-        with self.assertRaises(TypeError):
+        with self.assertRaises(TypeError) as cm:
             self.assertEqual(f(), (PH, 1), dict(a=10))
+        expected = ("missing positional arguments in 'partial' call; "
+                    "expected at least 1, got 0")
+        self.assertEqual(cm.exception.args[0], expected)
         self.assertEqual(f(2), ((2, 1), dict(a=10)))
 
-        # Leading Placeholder error
+        # Trailing Placeholder error
         f = self.partial(signature)
-        with self.assertRaises(TypeError):
+        with self.assertRaises(TypeError) as cm:
             f.__setstate__((capture, (1, PH), dict(a=10), dict(attr=[])))
+        expected = "trailing Placeholders are not allowed"
+        self.assertEqual(cm.exception.args[0], expected)
 
     def test_setstate_errors(self):
         f = self.partial(signature)
@@ -556,10 +561,16 @@ class TestPartialPySubclass(TestPartialPy):
     partial = PyPartialSubclass
 
     def test_subclass_optimization(self):
+        # `partial` input to `partial` subclass
         p = py_functools.partial(min, 2)
         p2 = self.partial(p, 1)
         self.assertIs(p2.func, min)
         self.assertEqual(p2(0), 0)
+        # `partial` subclass input to `partial` subclass
+        p = self.partial(min, 2)
+        p2 = self.partial(p, 1)
+        self.assertIs(p2.func, min)
+        self.assertEqual(p2(0), 0)
 
 
 class TestPartialMethod(unittest.TestCase):
@@ -702,10 +713,16 @@ def f(a, b, /):
     def test_subclass_optimization(self):
         class PartialMethodSubclass(functools.partialmethod):
             pass
+        # `partialmethod` input to `partialmethod` subclass
         p = functools.partialmethod(min, 2)
         p2 = PartialMethodSubclass(p, 1)
         self.assertIs(p2.func, min)
         self.assertEqual(p2.__get__(0)(), 0)
+        # `partialmethod` subclass input to `partialmethod` subclass
+        p = PartialMethodSubclass(min, 2)
+        p2 = PartialMethodSubclass(p, 1)
+        self.assertIs(p2.func, min)
+        self.assertEqual(p2.__get__(0)(), 0)
 
 
 class TestUpdateWrapper(unittest.TestCase):