diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -313,6 +313,26 @@ g(x, *args, **kwargs) +What is the difference between arguments and parameters? +-------------------------------------------------------- + +Given the function definition:: + + def func(foo, bar=None, **kwargs): + pass + +we can say that *foo*, *bar* and *kwargs* are :term:`parameter`\s of +``func``. When we call the function, for example:: + + func(42, bar=314, extra=somevar) + +we can say that ``42``, ``314``, and ``somevar`` are :term:`argument`\s passed +to ``func``. + +That is, parameters are the names that appears in the function signature, +arguments are the actual values passed to a function during a call. + + How do I write a function with output parameters (call by reference)? --------------------------------------------------------------------- diff --git a/Doc/glossary.rst b/Doc/glossary.rst --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -40,16 +40,26 @@ 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 method) and assigned to a named + local variable in the function body. There are two kinds of argument: - Any expression may be used within the argument list, and the evaluated - value is passed to the local variable. + * positional arguments: values passed by position (e.g. ``3`` and ``5`` + in ``complex(3, 5)``) and assigned to local names inside a function + according to the order in which they are given in the call. + An :term:`iterable` preceded by ``*`` can also be used to pass a + sequence of positional arguments (e.g. ``c = (3, 5); complex(*c)``). + + * keyword arguments: values passed by keyword and assigned to the local + variables whose names match the corresponding keywords (e.g. ``3`` and + ``5`` in ``complex(real=3, imag=5)``). + A dictionary preceded by ``**`` can also be used to pass a mapping of + keyword arguments (e.g. ``c = {'real': 3, 'imag': 5); complex(**c)``). + + Syntactically, any expression can be used within an argument list; the + evaluated value is passed to the local variable. + + See the :ref:`calls` section for the rules governing assignment to local + variables. Also see the :term:`parameter` glossary entry and :pep:`362`. attribute A value associated with an object which is referenced by name using @@ -402,10 +412,7 @@ ` 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 +555,37 @@ subpackages. Technically, a package is a Python module with an ``__path__`` attribute. + parameter + A named entity in a :term:`function` (or method) signature that + corresponds to an :term:`argument` or collection of arguments that the + function can accept. There are five types of paramters: + + * positional-or-keyword: value may be supplied either by position (e.g. + ``complex(3, 5)``) or by keyword (e.g. ``complex(real=3, imag=5)``). + This is the default kind of parameter (e.g. *foo* and *bar* in + ``def func(foo, bar=None): ...``). + + * positional-only: value can be supplied only by position. There is no + syntax to specify positional-only parameters in Python, however some + built-in functions only accepts positional arguments (e.g. :func:`abs`). + + * keyword-only: value can be supplied only by keyword (e.g. *key* in + ``max(seq, key=func)``). This can be specified by adding a bare ``*`` + before the keyword-only parameters in the function signature (e.g. + *kw_only* in ``def func(arg, *, kw_only): ...``). + + * var-positional: a tuple of positional arguments that aren't bound to + any other parameter. This can be specified by using ``*args`` in the + function signature (e.g. *args* in ``def func(*args, **kwargs): ...``). + + * var-keyword: a dict of keyword arguments that aren't bound to any other + parameter. This can be specified by using ``**kwargs`` in the function + signature (e.g. *kwargs* in ``def func(*args, **kwargs): ...``). + + See also the :term:`argument` glossary entry, 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 +609,7 @@ 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