[Python-checkins] bpo-21314: Add a FAQ entry about positional only parameters (GH-10641)
Nick Coghlan
webhook-mailer at python.org
Sun Mar 10 07:30:18 EDT 2019
https://github.com/python/cpython/commit/1aeeaeb79efa4de41f97b58547e23c2965ecabc5
commit: 1aeeaeb79efa4de41f97b58547e23c2965ecabc5
branch: master
author: Lysandros Nikolaou <lisandrosnik at gmail.com>
committer: Nick Coghlan <ncoghlan at gmail.com>
date: 2019-03-10T21:30:11+10:00
summary:
bpo-21314: Add a FAQ entry about positional only parameters (GH-10641)
files:
A Misc/NEWS.d/next/Documentation/2018-11-21-23-01-37.bpo-21314.PG33VT.rst
M Doc/faq/programming.rst
M Doc/library/functions.rst
M Doc/library/inspect.rst
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index 7bc00ff7e69d..31614189a62d 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 "<stdin>", line 1, in <module>
+ 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 ebbee71f48ed..ae0c9fb55a75 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 <faq-positional-only-arguments>`.
+
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 dfd78a97145c..81824ddc1e54 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 <faq-positional-only-arguments>`.
+
.. 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 000000000000..83080a3a580b
--- /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
More information about the Python-checkins
mailing list