Skip to content

Commit d97c71f

Browse files
cjerdonekcjerdonek
committed
Merge from 3.2: improve argument/parameter documentation (issue #15990).
2 parents bb4e941 + c2a7fd6 commit d97c71f

3 files changed

Lines changed: 99 additions & 18 deletions

File tree

‎Doc/faq/programming.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -313,6 +313,27 @@ calling another function by using ``*`` and ``**``::
313313
g(x, *args, **kwargs)
314314

315315

316+
.. _faq-argument-vs-parameter:
317+
318+
What is the difference between arguments and parameters?
319+
--------------------------------------------------------
320+
321+
:term:`Parameters <parameter>` are defined by the names that appear in a
322+
function definition, whereas :term:`arguments <argument>` are the values
323+
actually passed to a function when calling it. Parameters define what types of
324+
arguments a function can accept. For example, given the function definition::
325+
326+
def func(foo, bar=None, **kwargs):
327+
pass
328+
329+
*foo*, *bar* and *kwargs* are parameters of ``func``. However, when calling
330+
``func``, for example::
331+
332+
func(42, bar=314, extra=somevar)
333+
334+
the values ``42``, ``314``, and ``somevar`` are arguments.
335+
336+
316337
How do I write a function with output parameters (call by reference)?
317338
---------------------------------------------------------------------
318339

‎Doc/glossary.rst‎

Lines changed: 76 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -40,16 +40,34 @@ Glossary
4040
ABCs with the :mod:`abc` module.
4141

4242
argument
43-
A value passed to a function or method, assigned to a named local
44-
variable in the function body. A function or method may have both
45-
positional arguments and keyword arguments in its definition.
46-
Positional and keyword arguments may be variable-length: ``*`` accepts
47-
or passes (if in the function definition or call) several positional
48-
arguments in a list, while ``**`` does the same for keyword arguments
49-
in a dictionary.
43+
A value passed to a :term:`function` (or :term:`method`) when calling the
44+
function. There are two types of arguments:
45+
46+
* :dfn:`keyword argument`: an argument preceded by an identifier (e.g.
47+
``name=``) in a function call or passed as a value in a dictionary
48+
preceded by ``**``. For example, ``3`` and ``5`` are both keyword
49+
arguments in the following calls to :func:`complex`::
50+
51+
complex(real=3, imag=5)
52+
complex(**{'real': 3, 'imag': 5})
53+
54+
* :dfn:`positional argument`: an argument that is not a keyword argument.
55+
Positional arguments can appear at the beginning of an argument list
56+
and/or be passed as elements of an :term:`iterable` preceded by ``*``.
57+
For example, ``3`` and ``5`` are both positional arguments in the
58+
following calls::
59+
60+
complex(3, 5)
61+
complex(*(3, 5))
5062

51-
Any expression may be used within the argument list, and the evaluated
52-
value is passed to the local variable.
63+
Arguments are assigned to the named local variables in a function body.
64+
See the :ref:`calls` section for the rules governing this assignment.
65+
Syntactically, any expression can be used to represent an argument; the
66+
evaluated value is assigned to the local variable.
67+
68+
See also the :term:`parameter` glossary entry, the FAQ question on
69+
:ref:`the difference between arguments and parameters
70+
<faq-argument-vs-parameter>`, and :pep:`362`.
5371

5472
attribute
5573
A value associated with an object which is referenced by name using
@@ -402,10 +420,7 @@ Glossary
402420
<sortinghowto>` for examples of how to create and use key functions.
403421

404422
keyword argument
405-
Arguments which are preceded with a ``variable_name=`` in the call.
406-
The variable name designates the local name in the function to which the
407-
value is assigned. ``**`` is used to accept or pass a dictionary of
408-
keyword arguments. See :term:`argument`.
423+
See :term:`argument`.
409424

410425
lambda
411426
An anonymous inline function consisting of a single :term:`expression`
@@ -548,6 +563,53 @@ Glossary
548563
subpackages. Technically, a package is a Python module with an
549564
``__path__`` attribute.
550565

566+
parameter
567+
A named entity in a :term:`function` (or method) definition that
568+
specifies an :term:`argument` (or in some cases, arguments) that the
569+
function can accept. There are five types of parameters:
570+
571+
* :dfn:`positional-or-keyword`: specifies an argument that can be passed
572+
either :term:`positionally <argument>` or as a :term:`keyword argument
573+
<argument>`. This is the default kind of parameter, for example *foo*
574+
and *bar* in the following::
575+
576+
def func(foo, bar=None): ...
577+
578+
* :dfn:`positional-only`: specifies an argument that can be supplied only
579+
by position. Python has no syntax for defining positional-only
580+
parameters. However, some built-in functions have positional-only
581+
parameters (e.g. :func:`abs`).
582+
583+
* :dfn:`keyword-only`: specifies an argument that can be supplied only
584+
by keyword. Keyword-only parameters can be defined by including a
585+
single var-positional parameter or bare ``*`` in the parameter list
586+
of the function definition before them, for example *kw_only1* and
587+
*kw_only2* in the following::
588+
589+
def func(arg, *, kw_only1, kw_only2): ...
590+
591+
* :dfn:`var-positional`: specifies that an arbitrary sequence of
592+
positional arguments can be provided (in addition to any positional
593+
arguments already accepted by other parameters). Such a parameter can
594+
be defined by prepending the parameter name with ``*``, for example
595+
*args* in the following::
596+
597+
def func(*args, **kwargs): ...
598+
599+
* :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments
600+
can be provided (in addition to any keyword arguments already accepted
601+
by other parameters). Such a parameter can be defined by prepending
602+
the parameter name with ``**``, for example *kwargs* in the example
603+
above.
604+
605+
Parameters can specify both optional and required arguments, as well as
606+
default values for some optional arguments.
607+
608+
See also the :term:`argument` glossary entry, the FAQ question on
609+
:ref:`the difference between arguments and parameters
610+
<faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the
611+
:ref:`function` section, and :pep:`362`.
612+
551613
path entry
552614
A single location on the :term:`import path` which the :term:`path
553615
based finder` consults to find modules for importing.
@@ -571,11 +633,7 @@ Glossary
571633
that contribute to a namespace package, as defined in :pep:`420`.
572634

573635
positional argument
574-
The arguments assigned to local names inside a function or method,
575-
determined by the order in which they were given in the call. ``*`` is
576-
used to either accept multiple positional arguments (when in the
577-
definition), or pass several arguments as a list to a function. See
578-
:term:`argument`.
636+
See :term:`argument`.
579637

580638
provisional package
581639
A provisional package is one which has been deliberately excluded from

‎Misc/NEWS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -292,6 +292,8 @@ Tools/Demos
292292
Documentation
293293
-------------
294294

295+
- Issue #15990: Improve argument/parameter documentation.
296+
295297
- Issue #16209: Move the documentation for the str built-in function to a new
296298
str class entry in the "Text Sequence Type" section.
297299

0 commit comments

Comments
 (0)