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.

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

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)
@rgommers
Copy link
Member

rgommers commented Aug 21, 2021

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
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
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants