diff options
| -rw-r--r-- | Doc/faq/programming.rst | 21 | ||||
| -rw-r--r-- | Doc/glossary.rst | 94 | ||||
| -rw-r--r-- | Misc/NEWS | 2 |
3 files changed, 99 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 3c11de7..ddecc09 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 @@ -391,10 +409,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` @@ -516,12 +531,55 @@ 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 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`. + 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 @@ -741,6 +741,8 @@ Tools/Demos Documentation ------------- +- Issue #15990: Improve argument/parameter documentation. + - Issue #13538: Improve str() and object.__str__() documentation. - Issue #16400: Update the description of which versions of a given package |