summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorChris Jerdonek <chris.jerdonek@gmail.com>2012-11-28 10:37:42 (GMT)
committerChris Jerdonek <chris.jerdonek@gmail.com>2012-11-28 10:37:42 (GMT)
commitd97c71fedacd070e22ec2de3cd2e6f03c3c8b520 (patch)
tree30e4dd07aff5ed3cbc3d136b1dfff72178f02ba2 /Doc
parentbb4e941c6d721c2461f7dd30a84565abc350eca3 (diff)
parentc2a7fd60e1e1cc86c52d7409b5b8d84ee447a4ae (diff)
downloadcpython-d97c71fedacd070e22ec2de3cd2e6f03c3c8b520.zip
cpython-d97c71fedacd070e22ec2de3cd2e6f03c3c8b520.tar.gz
cpython-d97c71fedacd070e22ec2de3cd2e6f03c3c8b520.tar.bz2
Merge from 3.2: improve argument/parameter documentation (issue #15990).
Diffstat (limited to 'Doc')
-rw-r--r--Doc/faq/programming.rst21
-rw-r--r--Doc/glossary.rst94
2 files changed, 97 insertions, 18 deletions
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index d33e25b..2d5d2b1 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -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)?
---------------------------------------------------------------------
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 35bdb96..59075d5 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -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:
+
+ * :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))
- Any expression may be used within the argument list, and the evaluated
- value is passed to the local variable.
+ 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