The slash "/" as used in the documentation

[Terry Reedy]

On 2/9/2019 8:29 AM, Piet van Oostrum wrote:
> ram at zedat.fu-berlin.de (Stefan Ram) writes:

>>    The slash »/« as used in the documentation
>>
>> f( x, /, y )
>>
>>    is so ugly, it will disappear. Especially since it consumes
>>    a comma as it it was a parameter itself.
>>
>>    Possible alternatives include:
>>
>>    A newline:
>>
>> f( x,
>> y )
>>
>>    A separate specification of the first non-positional parameter:
>>
>> f( x, y )
>> # y
>>
>>    (use "(" or ")" when all parameters are non-positional or
>>    positional, respectively).
>>
>>    A semicolon:
>>
>> f( x; y )
>>
>>    (the actual call still would use a comma there).

'/' is no uglier than, and directly analogous to, and as easy to produce 
and comprehend, as '*'.  It was selected after considerable discussion 
of how to indicate that certain parameters are, at least in CPython, 
positional only.  The discussion of options included at least some of 
those given above.  It is very unlikely to go away or be changed.

> What are you talking about? What documentation?

CPython has an internal 'Argument Clinic' function that is gradually 
being applied to more and more builtin C-coded functions.  (It requires 
a slight rewrite of the function code.)  It adds a __text_signature__ 
attribute to the function object.  The text signature includes '/' when 
appropriate.  For instance

 >>> dict.fromkeys.__text_signature__
'($type, iterable, value=None, /)'

inspect.signature creates an inspect.Signature object from this 
attribute.  The __str__ method turns it back to the text needed for 
display of the signature.

 >>> s = inspect.signature(dict.fromkeys)
 >>> type(s)
<class 'inspect.Signature'>
 >>> str(s)
'(iterable, value=None, /)'

The interactive help function uses this text.

 >>> help(dict.fromkeys)
...
fromkeys(iterable, value=None, /) method ...

IDLE tool tips present the same signature string.

AFAIK, '/' is not yet used in the reference docs.  Perhaps the reason is 
that limiting arg passing to position is a CPython limitation rather 
than a language requirement.  (AFAIK, pypy could allow iterable and 
value to be passed by keyword.)  The help function is not part of the 
language definition, so I think the CPython version can document the 
CPython builtins.

The dict doc in the library reference has

classmethod fromkeys(iterable[, value])

The default value for 'value' is buried in the entry because 
'value=None' in the signature, without a following '/', would falsely 
imply that 'value=0' in a call should work.  There is no indication of 
the limitation.

> It seems to me you are talking about a completely different programming language, not python.

Documentation is not the language.  Whether to allow '/' in def 
statements signatures has been discussed.  The conclusion so far is that 
the C limitation is not needed in Python itself.

-- 
Terry Jan Reedy