Path: csiph.com!usenet.pasdenom.info!weretis.net!feeder4.news.weretis.net!newsreader4.netcologne.de!news.netcologne.de!bcyclone05.am1.xlned.com!bcyclone05.am1.xlned.com!newsfeed.xs4all.nl!newsfeed8.news.xs4all.nl!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
Return-Path: <ian.g.kelly@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.026
X-Spam-Evidence: '*H*': 0.95; '*S*': 0.00; 'value,': 0.03; 'compiler': 0.05; 'remaining': 0.07; 'python': 0.11; 'syntax': 0.13; 'wed,': 0.15; 'subject: \n ': 0.16; 'subject:?)': 0.16; 'wrote:': 0.16; 'arguments': 0.22; 'parameter': 0.22; 'rid': 0.22; 'code.': 0.23; '2015': 0.23; 'seems': 0.24; 'header:In-Reply-To:1': 0.24; 'question': 0.26; 'least': 0.27; 'message-id:@mail.gmail.com': 0.28; 'rest': 0.28; 'notation': 0.29; 'optional.': 0.29; 'no,': 0.29; 'gets': 0.32; "d'aprano": 0.33; 'steven': 0.33; 'received:google.com': 0.34; 'to:addr:python-list': 0.35; 'subject:: ': 0.37; 'signature': 0.37; 'means': 0.39; 'pm,': 0.39; 'to:addr:python.org': 0.39; 'subject: (': 0.40; 'subject:the': 0.40; 'default': 0.61; 'introduction': 0.63; 'square': 0.76; 'asterisk': 0.84; 'confusing': 0.84; 'to:name:python': 0.84; 'lone': 0.91; 'subject:Set': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :content-type; bh=vxPjknJJU6lhgyAjJbCxetle6wOghy6Ob/lT+Tj7k3c=; b=xFshCre32dhBOC80nJcw/98522arMkAbUfgCVlF/jdEx0/AKRvWnu42g6SfG9NHpq1 6/o9/qCPOfimBbmJJip5vKdTnD0PV/iLjBUDmNK6BTsbRHkzz0vJww0Q+4FjYJUh0XvK QQ/HV2SKSpbTSVWlVnBxPRSYEwrCN5D8/jejiUDly0grLolF4AakhWFB/VJKSMtxd0Z3 7GtUY8/uGpVixRFvF8zLfAr8ZYY37RKtLvVSwfRJhsR8INc9CTIPsXPhsD1yCjtA4HX1 n7VyGzRxsvp3Ael2+JSEobYS3Lnzwlc+LDDNJUsMNsST082BbpcI9Ca85gvfA11N6n/D obGQ==
X-Received: by 10.129.56.70 with SMTP id f67mr10173544ywa.85.1434586285881; Wed, 17 Jun 2015 17:11:25 -0700 (PDT)
MIME-Version: 1.0
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>
From: Ian Kelly <ian.g.kelly@gmail.com>
Date: Wed, 17 Jun 2015 18:10:45 -0600
Subject: Re: Documenting a function signature (was: Set a flag on the function or a global?)
To: Python <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.573.1434586294.13271.python-list@python.org>
Lines: 29
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1434586294 news.xs4all.nl 2841 [2001:888:2000:d::a6]:37039
X-Complaints-To: abuse@xs4all.nl
X-Received-Bytes: 4523
X-Received-Body-CRC: 1704830019
Xref: csiph.com comp.lang.python:92795

On Wed, Jun 17, 2015 at 6:04 PM, 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)
>
> (I think that's the style, anyway.)
>
> I like that it gets rid of square brackets; with the notation showing a
> default value, that already communicates that a parameter is optional.
>
> Since the introduction of keyword-only arguments in Python functions,
> the question arises of how to communicate this in documentation.
>
> 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.

No, this is valid syntax in Python 3. It means the same thing to the
compiler -- the remaining arguments are keyword-only -- that it means
in the documentation.