https://github.com/python/cpython/commit/cf2418076d7cf69a3bd4bf6be0e0001635a7ad4d
commit: cf2418076d7cf69a3bd4bf6be0e0001635a7ad4d
branch: main
author: Jelle Zijlstra <[email protected]>
committer: JelleZijlstra <[email protected]>
date: 2024-09-26T07:12:56-07:00
summary:
gh-119127: functools: Improve docs for partial and Placeholder (#124575)
files:
M Doc/library/functools.rst
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 774b3262117723..c2c25ca67f338a 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -354,7 +354,7 @@ The :mod:`functools` module defines the following functions:
newfunc.keywords = keywords
return newfunc
- The :func:`partial` function is used for partial function application which
"freezes"
+ The :func:`!partial` function 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
a callable that behaves like the :func:`int` function where the *base*
argument
@@ -368,10 +368,11 @@ The :mod:`functools` module defines the following
functions:
18
If :data:`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 a :ref:`partial object
<partial-objects>`.
+ when :func:`!partial` is called. This makes it possible to pre-fill any
positional
+ argument with a call to :func:`!partial`; without :data:`!Placeholder`,
only the
+ first positional argument can be pre-filled.
- If :data:`!Placeholder` sentinels are present, all of them must be filled
at call time:
+ If any :data:`!Placeholder` sentinels are present, all must be filled at
call time:
.. doctest::
@@ -379,14 +380,15 @@ The :mod:`functools` module defines the following
functions:
>>> say_to_world('Hello', 'dear')
Hello dear world!
- Calling ``say_to_world('Hello')`` would raise a :exc:`TypeError`, because
- only one positional argument is provided, while there are two placeholders
- in :ref:`partial object <partial-objects>`.
+ Calling ``say_to_world('Hello')`` raises a :exc:`TypeError`, because
+ only one positional argument is provided, but there are two placeholders
+ that must be filled in.
- Successive :func:`partial` applications fill :data:`!Placeholder` sentinels
- of the input :func:`partial` objects with new positional arguments.
- A place for positional argument can be retained by inserting new
- :data:`!Placeholder` sentinel to the place held by previous
:data:`!Placeholder`:
+ If :func:`!partial` is applied to an existing :func:`!partial` object,
+ :data:`!Placeholder` sentinels of the input object are filled in with
+ new positional arguments.
+ A placeholder can be retained by inserting a new
+ :data:`!Placeholder` sentinel to the place held by a previous
:data:`!Placeholder`:
.. doctest::
@@ -402,8 +404,8 @@ The :mod:`functools` module defines the following functions:
>>> remove_first_dear(message)
'Hello, dear world!'
- Note, :data:`!Placeholder` has no special treatment when used for keyword
- argument of :data:`!Placeholder`.
+ :data:`!Placeholder` has no special treatment when used in a keyword
+ argument to :func:`!partial`.
.. versionchanged:: 3.14
Added support for :data:`Placeholder` in positional arguments.
@@ -791,7 +793,7 @@ have three read-only attributes:
The keyword arguments that will be supplied when the :class:`partial`
object is
called.
-:class:`partial` objects are like :class:`function` objects in that they are
+:class:`partial` objects are like :ref:`function objects <user-defined-funcs>`
in that they are
callable, weak referenceable, and can have attributes. There are some
important
-differences. For instance, the :attr:`~definition.__name__` and
:attr:`__doc__` attributes
+differences. For instance, the :attr:`~definition.__name__` and
:attr:`~definition.__doc__` attributes
are not created automatically.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
