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!post.news.xs4all.nl!not-for-mail Return-Path: X-Original-To: python-list@python.org Delivered-To: python-list@mail.python.org X-Spam-Status: OK 0.061 X-Spam-Evidence: '*H*': 0.88; '*S*': 0.00; 'value,': 0.03; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'python': 0.11; 'syntax': 0.13; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'subject:?)': 0.16; 'arguments': 0.22; 'parameter': 0.22; 'rid': 0.22; 'code.': 0.23; 'seems': 0.24; 'header:User-Agent:1': 0.26; 'question': 0.26; 'header:X -Complaints-To:1': 0.26; 'least': 0.27; 'rest': 0.28; 'notation': 0.29; 'optional.': 0.29; 'function': 0.30; 'gets': 0.32; "d'aprano": 0.33; 'steven': 0.33; 'to:addr:python-list': 0.35; 'something': 0.35; 'but': 0.36; 'depends': 0.36; 'subject:: ': 0.37; 'signature': 0.37; 'received:org': 0.38; 'to:addr:python.org': 0.39; 'subject: (': 0.40; 'subject:the': 0.40; 'your': 0.60; 'default': 0.61; 'skip:u 10': 0.62; 'introduction': 0.63; 'dear': 0.67; 'square': 0.76; '_o__)': 0.84; 'asterisk': 0.84; 'confusing': 0.84; 'received:125': 0.84; 'lone': 0.91; 'subject:Set': 0.91; 'thoughts,': 0.91 X-Injected-Via-Gmane: http://gmane.org/ To: python-list@python.org From: Ben Finney Subject: Documenting a function signature (was: Set a flag on the function or a global?) Date: Thu, 18 Jun 2015 10:04:46 +1000 References: <557fdbd6$0$11097$c3e8da3@news.astraweb.com> <55818b3c$0$1665$c3e8da3$5496439d@news.astraweb.com> <55819878$0$1658$c3e8da3$5496439d@news.astraweb.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Gmane-NNTP-Posting-Host: jigong.madmonks.org X-Public-Key-ID: 0xAC128405 X-Public-Key-Fingerprint: 517C F14B B2F3 98B0 CB35 4855 B8B2 4C06 AC12 8405 X-Public-Key-URL: http://www.benfinney.id.au/contact/bfinney-pubkey.asc X-Post-From: Ben Finney User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.4 (gnu/linux) Cancel-Lock: sha1:xOjYx7YRgirZPk2Vw71cvhQW4J4= X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.20+ Precedence: list List-Id: General discussion list for the Python programming language List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: Lines: 35 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1434585912 news.xs4all.nl 2886 [2001:888:2000:d::a6]:59905 X-Complaints-To: abuse@xs4all.nl X-Received-Bytes: 4485 X-Received-Body-CRC: 2658609053 Xref: csiph.com comp.lang.python:92793 Steven D'Aprano 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. 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? -- \ “It is difficult to get a man to understand something when his | `\ salary depends upon his not understanding it.” —Upton Sinclair, | _o__) 1935 | Ben Finney