Merge from 3.3: improve argument/parameter documentation (issue #15990).
This commit is contained in:
Chris Jerdonek
commit
1bfaa688ba
|
|
@ -313,6 +313,27 @@ calling another function by using ``*`` and ``**``::
|
|||
g(x, *args, **kwargs)
|
||||
|
||||
|
||||
.. _faq-argument-vs-parameter:
|
||||
|
||||
What is the difference between arguments and parameters?
|
||||
--------------------------------------------------------
|
||||
|
||||
:term:`Parameters <parameter>` are defined by the names that appear in a
|
||||
function definition, whereas :term:`arguments <argument>` are the values
|
||||
actually passed to a function when calling it. Parameters define what types of
|
||||
arguments a function can accept. For example, given the function definition::
|
||||
|
||||
def func(foo, bar=None, **kwargs):
|
||||
pass
|
||||
|
||||
*foo*, *bar* and *kwargs* are parameters of ``func``. However, when calling
|
||||
``func``, for example::
|
||||
|
||||
func(42, bar=314, extra=somevar)
|
||||
|
||||
the values ``42``, ``314``, and ``somevar`` are arguments.
|
||||
|
||||
|
||||
How do I write a function with output parameters (call by reference)?
|
||||
---------------------------------------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -40,16 +40,34 @@ Glossary
|
|||
ABCs with the :mod:`abc` module.
|
||||
|
||||
argument
|
||||
A value passed to a function or method, assigned to a named local
|
||||
variable in the function body. A function or method may have both
|
||||
positional arguments and keyword arguments in its definition.
|
||||
Positional and keyword arguments may be variable-length: ``*`` accepts
|
||||
or passes (if in the function definition or call) several positional
|
||||
arguments in a list, while ``**`` does the same for keyword arguments
|
||||
in a dictionary.
|
||||
A value passed to a :term:`function` (or :term:`method`) when calling the
|
||||
function. There are two types of arguments:
|
||||
|
||||
Any expression may be used within the argument list, and the evaluated
|
||||
value is passed to the local variable.
|
||||
* :dfn:`keyword argument`: an argument preceded by an identifier (e.g.
|
||||
``name=``) in a function call or passed as a value in a dictionary
|
||||
preceded by ``**``. For example, ``3`` and ``5`` are both keyword
|
||||
arguments in the following calls to :func:`complex`::
|
||||
|
||||
complex(real=3, imag=5)
|
||||
complex(**{'real': 3, 'imag': 5})
|
||||
|
||||
* :dfn:`positional argument`: an argument that is not a keyword argument.
|
||||
Positional arguments can appear at the beginning of an argument list
|
||||
and/or be passed as elements of an :term:`iterable` preceded by ``*``.
|
||||
For example, ``3`` and ``5`` are both positional arguments in the
|
||||
following calls::
|
||||
|
||||
complex(3, 5)
|
||||
complex(*(3, 5))
|
||||
|
||||
Arguments are assigned to the named local variables in a function body.
|
||||
See the :ref:`calls` section for the rules governing this assignment.
|
||||
Syntactically, any expression can be used to represent an argument; the
|
||||
evaluated value is assigned to the local variable.
|
||||
|
||||
See also the :term:`parameter` glossary entry, the FAQ question on
|
||||
:ref:`the difference between arguments and parameters
|
||||
<faq-argument-vs-parameter>`, and :pep:`362`.
|
||||
|
||||
attribute
|
||||
A value associated with an object which is referenced by name using
|
||||
|
|
@ -402,10 +420,7 @@ Glossary
|
|||
<sortinghowto>` for examples of how to create and use key functions.
|
||||
|
||||
keyword argument
|
||||
Arguments which are preceded with a ``variable_name=`` in the call.
|
||||
The variable name designates the local name in the function to which the
|
||||
value is assigned. ``**`` is used to accept or pass a dictionary of
|
||||
keyword arguments. See :term:`argument`.
|
||||
See :term:`argument`.
|
||||
|
||||
lambda
|
||||
An anonymous inline function consisting of a single :term:`expression`
|
||||
|
|
@ -548,6 +563,53 @@ Glossary
|
|||
subpackages. Technically, a package is a Python module with an
|
||||
``__path__`` attribute.
|
||||
|
||||
parameter
|
||||
A named entity in a :term:`function` (or method) definition that
|
||||
specifies an :term:`argument` (or in some cases, arguments) that the
|
||||
function can accept. There are five types of parameters:
|
||||
|
||||
* :dfn:`positional-or-keyword`: specifies an argument that can be passed
|
||||
either :term:`positionally <argument>` or as a :term:`keyword argument
|
||||
<argument>`. This is the default kind of parameter, for example *foo*
|
||||
and *bar* in the following::
|
||||
|
||||
def func(foo, bar=None): ...
|
||||
|
||||
* :dfn:`positional-only`: specifies an argument that can be supplied only
|
||||
by position. Python has no syntax for defining positional-only
|
||||
parameters. However, some built-in functions have positional-only
|
||||
parameters (e.g. :func:`abs`).
|
||||
|
||||
* :dfn:`keyword-only`: specifies an argument that can be supplied only
|
||||
by keyword. Keyword-only parameters can be defined by including a
|
||||
single var-positional parameter or bare ``*`` in the parameter list
|
||||
of the function definition before them, for example *kw_only1* and
|
||||
*kw_only2* in the following::
|
||||
|
||||
def func(arg, *, kw_only1, kw_only2): ...
|
||||
|
||||
* :dfn:`var-positional`: specifies that an arbitrary sequence of
|
||||
positional arguments can be provided (in addition to any positional
|
||||
arguments already accepted by other parameters). Such a parameter can
|
||||
be defined by prepending the parameter name with ``*``, for example
|
||||
*args* in the following::
|
||||
|
||||
def func(*args, **kwargs): ...
|
||||
|
||||
* :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments
|
||||
can be provided (in addition to any keyword arguments already accepted
|
||||
by other parameters). Such a parameter can be defined by prepending
|
||||
the parameter name with ``**``, for example *kwargs* in the example
|
||||
above.
|
||||
|
||||
Parameters can specify both optional and required arguments, as well as
|
||||
default values for some optional arguments.
|
||||
|
||||
See also the :term:`argument` glossary entry, the FAQ question on
|
||||
:ref:`the difference between arguments and parameters
|
||||
<faq-argument-vs-parameter>`, the :class:`inspect.Parameter` class, the
|
||||
:ref:`function` section, and :pep:`362`.
|
||||
|
||||
path entry
|
||||
A single location on the :term:`import path` which the :term:`path
|
||||
based finder` consults to find modules for importing.
|
||||
|
|
@ -571,11 +633,7 @@ Glossary
|
|||
that contribute to a namespace package, as defined in :pep:`420`.
|
||||
|
||||
positional argument
|
||||
The arguments assigned to local names inside a function or method,
|
||||
determined by the order in which they were given in the call. ``*`` is
|
||||
used to either accept multiple positional arguments (when in the
|
||||
definition), or pass several arguments as a list to a function. See
|
||||
:term:`argument`.
|
||||
See :term:`argument`.
|
||||
|
||||
provisional package
|
||||
A provisional package is one which has been deliberately excluded from
|
||||
|
|
|
|||
Loading…
Reference in New Issue