What does the slash mean in help() output?
I asked this question myself. :) Found out that / was originally proposed by Guido in here.
Alternative proposal: how about using '/' ? It's kind of the opposite of '*' which means "keyword argument", and '/' is not a new character.
Then his proposal won.
Heh. If that's true, my '/' proposal wins:
def foo(pos_only, /, pos_or_kw, *, kw_only): ...
I think the very relevant document covering this is PEP 570. Where recap section looks nice.
Recap
The use case will determine which parameters to use in the function definition:
def f(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):As guidance:
Use positional-only if names do not matter or have no meaning, and there are only a few arguments which will always be passed in the same order. Use keyword-only when names have meaning and the function definition is more understandable by being explicit with names.
If the function ends with /
def foo(p1, p2, /)
This means all functional arguments are positional.
Forward Slash (/) indicates all arguments prior to it are positional only argument. Positional only arguments feature was added in python 3.8 after PEP 570 was accepted. Initially this notation was defined in PEP 457 - Notation for Notation For Positional-Only Parameters
Parameters in function definition prior Foraward slash (/) are positional only and parameters followed by slash(/) can be of any kind as per syntax. Where arguments are mapped to positional only parameters solely based on their position upon calling a function. Passing positional-only parameters by keywords(name) is invalid.
Let's take following example
def foo(a, b, / , x, y):
print("positional ", a, b)
print("positional or keyword", x, y)
Here in the above function definition parameters a and b are positional-only, while x or y can be either positional or keyword.
Following function calls are valid
foo(40, 20, 99, 39)
foo(40, 3.14, "hello", y="world")
foo(1.45, 3.14, x="hello", y="world")
But, following function call is not valid which raises an exception TypeError since a, b are not passed as positional arguments instead passed as keyword
foo(a=1.45, b=3.14, x=1, y=4)
TypeError: foo() got some positional-only arguments passed as keyword arguments: 'a, b'
Many built in function in python accept positional only arguments where passing arguments by keyword doesn't make sense. For example built-in function len accepts only one positional(only) argument, Where calling len as len(obj="hello world") impairs readability, check help(len).
>>> help(len)
Help on built-in function len in module builtins:
len(obj, /)
Return the number of items in a container.
Positional only parameters make underlying c/library functions easy to maintain. It allows parameters names of positional only parameters to be changes in future without risk of breaking client code that uses API
Last but not least, positional only parameters allow us to use their names to be used in variable length keyword arguments. Check following example
>>> def f(a, b, /, **kwargs):
... print(a, b, kwargs)
...
>>> f(10, 20, a=1, b=2, c=3) # a and b are used in two ways
10 20 {'a': 1, 'b': 2, 'c': 3}
Positional only parameters is better Explained here at Types of function arguments in python: Positional Only Parameters
Positional-only parameters syntax was officially added to python3.8. Checkout what's new python3.8 - positional only arguments
PEP Related: PEP 570 -- Python Positional-Only Parameters
It signifies the end of the positional only parameters, parameters you cannot use as keyword parameters. Before Python 3.8, such parameters could only be specified in the C API.
It means the key argument to __contains__ can only be passed in by position (range(5).__contains__(3)), not as a keyword argument (range(5).__contains__(key=3)), something you can do with positional arguments in pure-python functions.
Also see the Argument Clinic documentation:
To mark all parameters as positional-only in Argument Clinic, add a
/on a line by itself after the last parameter, indented the same as the parameter lines.
and the (very recent addition to) the Python FAQ:
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.
The syntax is now part of the Python language specification, as of version 3.8, see PEP 570 – Python Positional-Only Parameters. Before PEP 570, the syntax was already reserved for possible future inclusion in Python, see PEP 457 - Syntax For Positional-Only Parameters.
Positional-only parameters can lead to cleaner and clearer APIs, make pure-Python implementations of otherwise C-only modules more consistent and easier to maintain, and because positional-only parameters require very little processing, they lead to faster Python code.