Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #92796

Re: Documenting a function signature (was: Set a flag on the function or a global?)

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> (permalink)
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

Show key headers only | View raw

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

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Set a flag on the function or a global? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-06-15 23:57 +0000
  Re: Set a flag on the function or a global? Chris Angelico <rosuav@gmail.com> - 2015-06-16 10:07 +1000
  Re: Set a flag on the function or a global? Ethan Furman <ethan@stoneleaf.us> - 2015-06-15 17:19 -0700
  Re: Set a flag on the function or a global? Ben Finney <ben+python@benfinney.id.au> - 2015-06-16 10:20 +1000
    Re: Set a flag on the function or a global? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-06-16 19:07 +1000
  Re: Set a flag on the function or a global? Ethan Furman <ethan@stoneleaf.us> - 2015-06-15 17:21 -0700
  Re: Set a flag on the function or a global? sohcahtoa82@gmail.com - 2015-06-15 17:24 -0700
    Re: Set a flag on the function or a global? MRAB <python@mrabarnett.plus.com> - 2015-06-16 01:35 +0100
      Re: Set a flag on the function or a global? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-06-16 18:18 +1000
        Re: Set a flag on the function or a global? Oscar Benjamin <oscar.j.benjamin@gmail.com> - 2015-06-16 13:45 +0100
          Re: Set a flag on the function or a global? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-06-16 22:46 +0000
        Re: Set a flag on the function or a global? Cameron Simpson <cs@zip.com.au> - 2015-06-17 09:51 +1000
          Re: Set a flag on the function or a global? Steven D'Aprano <steve@pearwood.info> - 2015-06-18 00:59 +1000
            Re: Set a flag on the function or a global? Laura Creighton <lac@openend.se> - 2015-06-17 17:06 +0200
              Re: Set a flag on the function or a global? Steven D'Aprano <steve@pearwood.info> - 2015-06-18 01:55 +1000
                Documenting a function signature (was: Set a flag on the function or a global?) Ben Finney <ben+python@benfinney.id.au> - 2015-06-18 10:04 +1000
                Re: Documenting a function signature (was: Set a flag on the function or a global?) Ian Kelly <ian.g.kelly@gmail.com> - 2015-06-17 18:10 -0600
                Re: Documenting a function signature (was: Set a flag on the function or a global?) Chris Angelico <rosuav@gmail.com> - 2015-06-18 10:14 +1000
                Re: Documenting a function signature (was: Set a flag on the function or a global?) random832@fastmail.us - 2015-06-18 08:37 -0400
                Re: Documenting a function signature (was: Set a flag on the function or a global?) Laura Creighton <lac@openend.se> - 2015-06-18 23:38 +0200
                Re: Documenting a function signature Ben Finney <ben+python@benfinney.id.au> - 2015-06-19 10:41 +1000
  Re: Set a flag on the function or a global? Ron Adam <ron3200@gmail.com> - 2015-06-15 20:24 -0400
    Re: Set a flag on the function or a global? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-06-16 19:15 +1000
      Re: Set a flag on the function or a global? Ron Adam <ron3200@gmail.com> - 2015-06-16 07:02 -0400
  Re: Set a flag on the function or a global? Chris Angelico <rosuav@gmail.com> - 2015-06-16 10:32 +1000
  Re: Set a flag on the function or a global? Paul Rubin <no.email@nospam.invalid> - 2015-06-15 17:37 -0700
    Re: Set a flag on the function or a global? Ethan Furman <ethan@stoneleaf.us> - 2015-06-15 17:53 -0700
      Re: Set a flag on the function or a global? Paul Rubin <no.email@nospam.invalid> - 2015-06-15 19:04 -0700
    Re: Set a flag on the function or a global? MRAB <python@mrabarnett.plus.com> - 2015-06-16 02:15 +0100
    Re: Set a flag on the function or a global? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-06-16 18:30 +1000
  Re: Set a flag on the function or a global? Mark Lawrence <breamoreboy@yahoo.co.uk> - 2015-06-16 07:06 +0100
    Re: Set a flag on the function or a global? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2015-06-16 19:28 +1000
  Re: Set a flag on the function or a global? Jonas Wielicki <jonas@wielicki.name> - 2015-06-16 12:00 +0200
  Re: Set a flag on the function or a global? Michael Torrie <torriem@gmail.com> - 2015-06-16 07:44 -0600
  Re: Set a flag on the function or a global? Michael Torrie <torriem@gmail.com> - 2015-06-16 07:56 -0600
  Re: Set a flag on the function or a global? Peter Otten <__peter__@web.de> - 2015-06-16 15:59 +0200
  Re: Set a flag on the function or a global? Ethan Furman <ethan@stoneleaf.us> - 2015-06-16 07:57 -0700

csiph-web