Backport from 3.2: improve argument/parameter documentation (issue #15990).

The corresponding 3.x commits are 69d5d834c5cb, 40fd26a4206b, and
74d8a2a20c52.
This commit is contained in:
Chris Jerdonek 2012-11-29 19:03:37 -08:00
parent 07d126f0de
commit 8da8268b1f
3 changed files with 90 additions and 18 deletions

View File

@ -469,6 +469,27 @@ In the unlikely case that you care about Python versions older than 2.0, use
apply(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)?
---------------------------------------------------------------------

View File

@ -39,16 +39,34 @@ Glossary
create your own 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 and the FAQ question on
:ref:`the difference between arguments and parameters
<faq-argument-vs-parameter>`.
attribute
A value associated with an object which is referenced by name using
@ -412,10 +430,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`
@ -537,12 +552,46 @@ Glossary
(methods). Also the ultimate base class of any :term:`new-style
class`.
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 four 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:`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>`, and the :ref:`function` section.
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`.
Python 3000
Nickname for the Python 3.x release line (coined long ago when the release

View File

@ -594,6 +594,8 @@ Tools/Demos
Documentation
-------------
- Issue #15990: Improve argument/parameter documentation.
- Issue #16400: Update the description of which versions of a given package
PyPI displays.