documentation of arguments

[Skaperen]

in The Python Library Reference (and other documentation) how is one supposed to know if a given argument is supposed to be given by position or given by keyword when a keyword is given in a specific position?  for example, the builtin sorted function has both in its documentation but only accepts positional iterable while it only accepts key as a keyword.  error messages give a good indication of what is happening with key but the documentation does not does anyone know what is going on with this?  is there some essential explanation i missed?

[stranac]

Well, positional-only arguments are only a thing with built-in functions, as python has no syntax for those (can be emulated using *args though).
I guess you just have to learn which functions and arguments those are, as I can't find them detailed anywhere in the docs.

As for keyword-only args, those are usually shown clearly, at least in python 3, where syntax for something like that exists, check e.g. https://docs.python.org/3/library/functions.html#max

while it only accepts key as a keyword

You can pass a key function as a positional argument to sorted()...

[Larz60+]

For non-builtins, you can use inspect

>>> from tkinter import *
>>> import inspect

>>> inspect.signature(Tk)

will result in

Output:
<Signature (screenName=None, baseName=None, className='Tk', useTk=1, sync=0, use=None)>

[Larz60+]

Actually this is a better example:

>>> from tkinter import *
>>> import inspect
>>> print(inspect.getargspec(Frame))
ArgSpec(args=['self', 'master', 'cnf'], varargs=None, keywords='kw', defaults=(None, {}))
>>>

---

Note that getargspec has been depreciated, and signature is recommended.
However I don't seem able to get the same results with signature

[nilamo]

Well, positional-only arguments are only a thing with built-in functions, as python has no syntax for those (can be emulated using *args though).
I guess you just have to learn which functions and arguments those are, as I can't find them detailed anywhere in the docs.

As for keyword-only args, those are usually shown clearly, at least in python 3, where syntax for something like that exists, check e.g. https://docs.python.org/3/library/functions.html#max

while it only accepts key as a keyword

You can pass a key function as a positional argument to sorted()...

It looks like with python 3.0, a PEP3102 added keyword-only support (although this doesn't throw errors):

>>> def spam(eggs, *whocares, fish="fried"): print(fish)
...
>>> spam(1)
fried
>>> spam(1, 4, 2, 3)
fried
>>> spam(1, 4, 2, fish=3)
3

But then again, the docs for 3.0's sorted do indicate that they're keyword only:

sorted(iterable[, key][, reverse])
Return a new sorted list from the items in iterable.

Has two optional arguments which must be specified as keyword arguments.

---

...don't mind me, I'll just go ahead and correct myself. You can get errors if you don't supply default values:

>>> def spam(eggs, *whocares, fish): print(fish)
...
>>> spam(1, 4, 2, fish=3)
3
>>> spam(1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: spam() missing 1 required keyword-only argument: 'fish'
>>>

However, that's still not the same thing as what sorted() does...

[stranac]

It looks like with python 3.0, a PEP3102 added keyword-only support (although this doesn't throw errors):

>>> def spam(eggs, *whocares, fish="fried"): print(fish)
...

That's not the correct syntax, your code allows an arbitrary number of positional arguments.
You want this instead:

def spam(eggs,*,fish="fried"):

But then again, the docs for 3.0's sorted do indicate that they're keyword only:

Looks like that is indeed the case in python 3, and the docs clearly state it.
Considering the docs for min and max, I'd say the function signature of sorted in the docs should be updated.

[Skaperen]

But then again, the docs for 3.0's sorted do indicate that they're keyword only:

[quote="https://docs.python.org/3.6/library/func...tml#sorted"]sorted(iterable[, key][, reverse])
Return a new sorted list from the items in iterable.

Has two optional arguments which must be specified as keyword arguments.

---

my bad, reading the docs for sorted in version 2 and version 3 side by side seems to leave me confused.

and that feature of combing one-after-another posts to same thread with a long horizontal rule between them seems to leave the reply editing confused.  that long horizontal rule gets in the reply and can't be removed.