[Tutor] What is meaning of "/" in "pow(x, y, z=None, /)"?

[Steven D'Aprano]

On Wed, Aug 02, 2017 at 11:25:34AM +1000, Ben Finney wrote:
> Steven D'Aprano <steve at pearwood.info> writes:
> 
> > Its quite new. Up until recently, the documentation didn't distinguish
> > between function parameters which can take optional keywords and those
> > that can't.
> 
> Where does the documentation describe this distinction? How is the
> reader, coming across a link to documentation for a function, expected
> to know what that symbol means in that context?

I don't know if it is already documented somewhere. I would have 
expected it to be listed in the Glossary under "parameter":

https://docs.python.org/3/glossary.html#term-parameter

but it isn't, even though positional-only parameters are listed. So 
that's a documentation bug.

But in general, there are certain conventions which the reader is just 
expected to know as background knowledge. Such as "->" meaning the 
return result, and [...] used for optional arguments:

    Help on class range in module builtins:

    class range(object)
     |  range(stop) -> range object
     |  range(start, stop[, step]) -> range object


That's from Python 3.5. But to prove this isn't a new issue, here's the 
start of the output of help(range) from Python 2.4:

    Help on built-in function range in module __builtin__:

    range(...)
        range([start,] stop[, step]) -> list of integers

As far as I know, the [...] convention for optional arguments is not 
documented anywhere.


> I am dismayed that the documentation has gone from describing function
> signatures in Python syntax, to describing function signatures that
> don't have the expected effect in Python code.

That's not new. If a naive user writes:

    range(1, 10[, 2])

they will get a SyntaxError. For that matter, if a naive user writes:

    range(stop)

they will probably get a NameError. A certain amount of domain knowledge 
has to be assumed.

"/" as a parameter is currently reserved for future use, and doesn't 
work in Python functions created with def or lambda. But it can be added 
to the signature for functions written in C.



-- 
Steve