From 1aeeaeb79efa4de41f97b58547e23c2965ecabc5 Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Sun, 10 Mar 2019 12:30:11 +0100 Subject: bpo-21314: Add a FAQ entry about positional only parameters (GH-10641) --- Doc/faq/programming.rst | 35 ++++++++++++++++++++++ Doc/library/functions.rst | 5 ++++ Doc/library/inspect.rst | 4 +++ .../2018-11-21-23-01-37.bpo-21314.PG33VT.rst | 3 ++ 4 files changed, 47 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2018-11-21-23-01-37.bpo-21314.PG33VT.rst diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 7bc00ff..3161418 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -767,6 +767,41 @@ Yes. Usually this is done by nesting :keyword:`lambda` within Don't try this at home, kids! +.. _faq-positional-only-arguments: + +What does the slash(/) in the parameter list of a function mean? +---------------------------------------------------------------- + +A slash in the argument list of a function denotes that the parameters prior to +it are positional-only. Positional-only parameters are the ones without an +externally-usable name. Upon calling a function that accepts positional-only +parameters, arguments are mapped to parameters based solely on their position. +For example, :func:`pow` is a function that accepts positional-only parameters. +Its documentation looks like this:: + + >>> help(pow) + Help on built-in function pow in module builtins: + + pow(x, y, z=None, /) + Equivalent to x**y (with two arguments) or x**y % z (with three arguments) + + Some types, such as ints, are able to use a more efficient algorithm when + invoked using the three argument form. + +The slash at the end of the parameter list means that all three parameters are +positional-only. Thus, calling :func:`pow` with keyword aguments would lead to +an error:: + + >>> pow(x=3, y=4) + Traceback (most recent call last): + File "", line 1, in + TypeError: pow() takes no keyword arguments + +Note that as of this writing this is only documentational and no valid syntax +in Python, although there is :pep:`570`, which proposes a syntax for +position-only parameters in Python. + + Numbers and strings =================== diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index ebbee71..ae0c9fb 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -669,6 +669,11 @@ are always available. They are listed here in alphabetical order. topic, and a help page is printed on the console. If the argument is any other kind of object, a help page on the object is generated. + Note that if a slash(/) appears in the parameter list of a function, when + invoking :func:`help`, it means that the parameters prior to the slash are + positional-only. For more info, see + :ref:`the FAQ entry on positional-only parameters `. + This function is added to the built-in namespace by the :mod:`site` module. .. versionchanged:: 3.4 diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index dfd78a9..81824dd 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -572,6 +572,10 @@ function. Raises :exc:`ValueError` if no signature can be provided, and :exc:`TypeError` if that type of object is not supported. + A slash(/) in the signature of a function denotes that the parameters prior + to it are positional-only. For more info, see + :ref:`the FAQ entry on positional-only parameters `. + .. versionadded:: 3.5 ``follow_wrapped`` parameter. Pass ``False`` to get a signature of ``callable`` specifically (``callable.__wrapped__`` will not be used to diff --git a/Misc/NEWS.d/next/Documentation/2018-11-21-23-01-37.bpo-21314.PG33VT.rst b/Misc/NEWS.d/next/Documentation/2018-11-21-23-01-37.bpo-21314.PG33VT.rst new file mode 100644 index 0000000..83080a3 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-11-21-23-01-37.bpo-21314.PG33VT.rst @@ -0,0 +1,3 @@ +A new entry was added to the Core Language Section of the Programming FAQ, +which explaines the usage of slash(/) in the signature of a function. Patch +by Lysandros Nikolaou -- cgit v0.12