Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Convention for specifying that arguments are keyword only? #330

Open
matthew-brett opened this issue Aug 21, 2021 · 2 comments · May be fixed by #367
Open

Convention for specifying that arguments are keyword only? #330

matthew-brett opened this issue Aug 21, 2021 · 2 comments · May be fixed by #367

Comments

@matthew-brett
Copy link

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)
@matthew-brett matthew-brett mentioned this issue Aug 21, 2021
Merged
@rgommers
Copy link
Member

rgommers commented Aug 21, 2021 •
edited
Loading

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
    """

This was referenced Mar 2, 2022
Merged
Open
@timhoffm
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

DOC: include positional-only and keyword-only parameters in standard namurphy/numpydoc
3 participants
@matthew-brett @rgommers @timhoffm