Convention for specifying that arguments are keyword only?

[matthew-brett]

Is there a standard way for the docstring to tell the user that the arguments (or following arguments) are keyword only? Other than some note for each argument? I mean for a situation like this:

def my_func(a, *, b, c):
    """ My function does stuff

    a : object
        Something about `a`.
    b : object, keyword-only
        Something about `b`.
    c : object, keyword-only
        Something about `c`.
    """
    print(a, b, c)

[rgommers]

There's no standard way to do this. There's optional which needs to be kept unchanged (because it's so widely used, not necessarily because it's optimal), and that intersects with keyword-only. The description for d here is a little ugly, but I don't have a better suggestion:

def my_func(a, *, b, c, d=None):
    """ My function does stuff

    a : object
        Something about `a`.
    b : object, keyword-only
        Something about `b`.
    c : object, keyword-only
        Something about `c`.
    d : object, optional, keyword-only
    """

[timhoffm]

Personal opinion: keyword-only (and positional-only) are just syntactic usage aspects. They don't carry information for understanding the function and its parameters. I therefore propose that it's sufficient to let the user infer the usage from the signature and would not document that aspect in the parameters section at all.

[matthew-brett]

I just found this again. I think keyword-only does carry carry information for understanding the function and its parameters. Consider:

def func(a, *, b):
     return a * b

You might want to be reminded that b is keyword-only in the docstring, because otherwise you'd see:

Parameters
-----------
a : object
b : object

Returns
--------
c : object
    Result of ``a * b``

And then do:

func(1, 2)

and be surprised by TypeError: func() takes 1 positional argument but 2 were given. Of course, if you were careful and looked at the signature, you'd see the problem, but the same is true of "optional" - you can infer it from the presence of a default value in the signature. I think noting this aspect of use in the docstring would be a helpful addition.

[rossbar]

My 2 cents: from numpydoc's perspective, there is no requirement/prohibition of adding such information to the parameter type line or description. In other words, adding such information will no affect the docstring parsing. So, if a project wants to add keyword-only to the parameter type line where appropriate, then do so!

I'd be hesitant to add something to the standard to prescribe how specifically one should do so though. IMO, libraries should be able to choose their own patterns. For example:

my_param : int, keyword-only

is no more or less valid than:

my_param : int, kw-only

However a project chooses to specify this info, they can use numpydoc's parameter cross-linking feature to "codify" it. For example, let's say you prefer option 2, then add:

numpydoc_xref_aliases = {
    ... # other aliases
    "kw-only": ":external:py:ref:`kw-only <keyword-only_param>`,
}

to conf.py, and (assuming the python3 docs are in the intersphinx mapping) then all usages of kw-only in the parameter type line will link here.

So - to summarize my personal take: numpydoc should (and currently does) support adding this info to docstrings, but the adopting libraries should be free to choose specifically whether/how they want to do so.

[mdhaber]

@rossbar Can you tell offhand whether scipy/scipy#22323 is a SciPy-specific issue? The * and / in the signatures isn't even showing up.

[rossbar]

is a SciPy-specific issue?

Off the top of my head I have no idea. Comparing with the NetworkX docs, I don't see the same issue: the keyword-only bit is rendering properly on the autodoc'ed function pages as well as in autosummaries.

However, the fact that this seems to show up in scipy in methods specifically makes me suspicious...