Path: csiph.com!usenet.pasdenom.info!news.redatomik.org!newsfeed.xs4all.nl!newsfeed8.news.xs4all.nl!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
Return-Path: <rosuav@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.002
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'defaults': 0.05; 'initialize': 0.05; '*args,': 0.07; 'executable': 0.07; 'false,': 0.07; 'imply': 0.07; 'cc:addr:python-list': 0.10; 'python': 0.11; 'syntax': 0.13; 'argument': 0.15; 'thu,': 0.15; '(either': 0.16; 'boolean': 0.16; 'clear.': 0.16; 'definition.': 0.16; 'downside': 0.16; 'from:addr:rosuav': 0.16; 'from:name:chris angelico': 0.16; 'parameter,': 0.16; 'sentinel': 0.16; 'simple.': 0.16; 'slash': 0.16; 'subject: \n ': 0.16; 'subject:?)': 0.16; 'wrote:': 0.16; 'copied': 0.18; '>>>': 0.20; 'cc:2**0': 0.21; 'cc:addr:python.org': 0.21; 'fairly': 0.22; 'saying': 0.22; 'arguments': 0.22; 'am,': 0.23; 'code.': 0.23; 'bit': 0.23; '2015': 0.23; 'seems': 0.24; 'header:In-Reply-To:1': 0.24; 'parameters': 0.27; 'least': 0.27; 'message-id:@mail.gmail.com': 0.28; 'rest': 0.28; 'looks': 0.29; '**kwargs)': 0.29; 'signatures': 0.29; 'objects': 0.29; 'function': 0.30; "i'd": 0.31; 'code': 0.31; 'skip:_ 10': 0.32; "d'aprano": 0.33; 'steven': 0.33; 'received:google.com': 0.34; 'possible,': 0.35; 'something': 0.35; "isn't": 0.35; 'but': 0.36; 'subject:: ': 0.37; 'signature': 0.37; 'does': 0.39; 'subject: (': 0.40; 'subject:the': 0.40; 'some': 0.40; 'your': 0.60; 'default': 0.61; 'show': 0.62; 'more': 0.62; 'dear': 0.67; 'unusual': 0.72; 'aiui': 0.84; 'asterisk': 0.84; 'chrisa': 0.84; 'confusing': 0.84; 'signature.': 0.84; 'valid,': 0.84; 'to:none': 0.90; 'lone': 0.91; 'subject:Set': 0.91; 'thoughts,': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:cc :content-type; bh=iMUCjiZ9rCFmXDHeOtrE/ENeyR/CdhRJ7PfjN+drFgE=; b=ubFjf4X83sAHCmPLKW6ZwPQV3Ui54FYi7HeI6Mqy89X4Z6Eb7Vnypm5XVDPRV5fwHW wU/dLq4fSNVVuJlawL24ML0KPlKC/bu2N7rUbEFE1uw3iwXX5yIp/a+cY/3UjIPOtwYm 2qrWMQQxv73kNuUgc688OB9x27eGzng/fZPRh1yrA56zZNz5qymi2EREHpV7dD+Muffp dtYTCtVtQyfDYVFWkeMiBYbcg4AKtmgH7aoFXystsfglmuaxr7skurgObInQ6Z7ClqMy E005nrTA2DPkpe0adZbMzCrIhkcr69BElkdGf8Gtk/m1bHSsbPtNbHp/lFXee6ps2fUr tpcA==
MIME-Version: 1.0
X-Received: by 10.50.43.196 with SMTP id y4mr14547745igl.14.1434586494670; Wed, 17 Jun 2015 17:14:54 -0700 (PDT)
In-Reply-To: <85egl9ubj5.fsf_-_@benfinney.id.au>
References: <557fdbd6$0$11097$c3e8da3@news.astraweb.com> <mailman.530.1434500492.13271.python-list@python.org> <55818b3c$0$1665$c3e8da3$5496439d@news.astraweb.com> <mailman.556.1434553624.13271.python-list@python.org> <55819878$0$1658$c3e8da3$5496439d@news.astraweb.com> <85egl9ubj5.fsf_-_@benfinney.id.au>
Date: Thu, 18 Jun 2015 10:14:54 +1000
Subject: Re: Documenting a function signature (was: Set a flag on the function or a global?)
From: Chris Angelico <rosuav@gmail.com>
Cc: "python-list@python.org" <python-list@python.org>
Content-Type: text/plain; charset=UTF-8
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.20+
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <https://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.574.1434586497.13271.python-list@python.org>
Lines: 44
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1434586497 news.xs4all.nl 2860 [2001:888:2000:d::a6]:39843
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:92796

On Thu, Jun 18, 2015 at 10:04 AM, Ben Finney <ben+python@benfinney.id.au> wrote:
> Steven D'Aprano <steve@pearwood.info> writes:
>
>> The full signature is:
>>
>> edir([object [, glob=''] [, dunders=True] [, meta=False]])
>>
>> All four arguments are optional, and dunders and meta are
>> keyword-only.
>
> The official documentation seems to prefer this style::
>
>     edit(object, glob='', *, dunders=True, meta=False)

Mostly. That would imply that object is a mandatory parameter, which
AIUI isn't the case for Steven's edir. The downside of this kind of
signature is that it's hard to show the parameters that have unusual
defaults (either sentinel objects and custom code to cope, or they're
pulled out of *a or **kw).

> The lone asterisk showing the separation of keyword-only arguments from
> the rest is confusing to me. Not least because it is (if I understand
> correctly) invalid syntax to actually have that in Python code.

It's perfectly valid, and it does exactly what it looks like. What's
not valid syntax is the slash that comes up in some Argument Clinic
functions:

>>> help(list.__init__)
__init__(self, /, *args, **kwargs)
    Initialize self.  See help(type(self)) for accurate signature.

> What are your thoughts, dear reader, on the documentation style for
> showing a Python function signature, now that we have not only default
> arguments but also keyword-only arguments?

I like the executable form when it's fairly simple. If you have a
boolean that defaults to True but you can set it to false, saying
"dunders=True" is awesomely clear. It's a bit harder when you want to
do something more complicated, but so far as it's possible, I'd like
to see signatures that look like they were copied and pasted straight
from the function definition.

ChrisA