Rocksolid Light

Welcome to novaBBS (click a section below)

mail  files  register  newsreader  groups  login

Message-ID:  

What is now proved was once only imagin'd. -- William Blake


devel / comp.lang.python / Re: Style for docstring

SubjectAuthor
* Style for docstringMichael F. Stemper
+* Re: Style for docstringChris Angelico
|`* Re: Style for docstringMichael F. Stemper
| +- Re: Style for docstring2QdxY4RzWzUUiLuE
| +- Re: Style for docstringChris Angelico
| +- Re: Style for docstring2QdxY4RzWzUUiLuE
| +* Re: Style for docstringRob Cliffe
| |`* Re: Style for docstringStefan Ram
| | `- Re: Style for docstringjan
| +- Re: Style for docstringChris Angelico
| +- Re: Style for docstringMRAB
| +* Re: Style for docstringAvi Gross
| |`* Re: Style for docstringMichael F. Stemper
| | +* Re: Style for docstringAvi Gross
| | |`* Re: Style for docstringMichael F. Stemper
| | | `- Re: Style for docstringMichael F. Stemper
| | `- Re: Style for docstringdn
| +* Re: Style for docstringAvi Gross
| |`- Re: Style for docstringJulio Di Egidio
| `- Re: Style for docstringdn
+- Re: Style for docstringEthan Furman
+* Re: Style for docstringalister
|`- Re: Style for docstringMichael F. Stemper
+- Re: Style for docstringJulio Di Egidio
`- Re: Style for docstringDan Stromberg

1
Style for docstring

<t3v042$8s1$1@dont-email.me>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17969&group=comp.lang.python#17969

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!eternal-september.org!reader02.eternal-september.org!.POSTED!not-for-mail
From: michael....@gmail.com (Michael F. Stemper)
Newsgroups: comp.lang.python
Subject: Style for docstring
Date: Fri, 22 Apr 2022 14:36:27 -0500
Organization: A noiseless patient Spider
Lines: 19
Message-ID: <t3v042$8s1$1@dont-email.me>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Injection-Date: Fri, 22 Apr 2022 19:36:35 -0000 (UTC)
Injection-Info: reader02.eternal-september.org; posting-host="9b617cc56a692a90c6e4b914c700b764";
logging-data="9089"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX1837ijXBbg9zV872L2qB2o3qfrDI09+l6s="
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
Thunderbird/68.10.0
Cancel-Lock: sha1:R4OjYv1/uTYjtIjWnN+VXkPRe0Q=
Content-Language: en-US
X-Mozilla-News-Host: news://news.eternal-september.org:119
 by: Michael F. Stemper - Fri, 22 Apr 2022 19:36 UTC

I'm writing a function that is nearly self-documenting by its name,
but still want to give it a docstring. Which of these would be
best from a stylistic point of view:

Tells caller whether or not a permutation is even.

Determines if a permutation is even. (Alternative is that it's odd.)

Returns True if permutation is even, False if it is odd.

(Before somebody suggests it, I'm not going to put six weeks' worth
of a course in group theory in there to help somebody who doesn't
know what those standard terms mean.)

--
Michael F. Stemper
87.3% of all statistics are made up by the person giving them.

Re: Style for docstring

<mailman.197.1650657557.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17970&group=comp.lang.python#17970

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!usenet.goja.nl.eu.org!3.eu.feeder.erje.net!feeder.erje.net!fu-berlin.de!uni-berlin.de!not-for-mail
From: ros...@gmail.com (Chris Angelico)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 05:59:05 +1000
Lines: 26
Message-ID: <mailman.197.1650657557.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
X-Trace: news.uni-berlin.de z+rZ+pEWYScX3s4KSyDb5wUR0F+ZssnlFfE2NAuxykEA==
Return-Path: <rosuav@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=gmail.com header.i=@gmail.com header.b=Zx7epYDY;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.096
X-Spam-Evidence: '*H*': 0.81; '*S*': 0.00; '2022': 0.05; 'theory':
0.09; '05:56,': 0.16; 'chrisa': 0.16; 'determines': 0.16;
'from:addr:rosuav': 0.16; 'from:name:chris angelico': 0.16;
'wrote:': 0.16; 'to:addr:python-list': 0.20; 'returns': 0.22;
'sat,': 0.22; "i'd": 0.24; 'function': 0.27; 'it,': 0.29;
"doesn't": 0.32; 'message-id:@mail.gmail.com': 0.32; 'but': 0.32;
"i'm": 0.33; 'subject:for': 0.33; 'there': 0.33; 'header:In-Reply-
To:1': 0.34; 'received:google.com': 0.34; 'from:addr:gmail.com':
0.35; 'possibly': 0.36; 'those': 0.36; "it's": 0.37;
'received:209.85': 0.37; 'others': 0.37; 'put': 0.38;
'received:209': 0.39; 'still': 0.40; 'want': 0.40; 'michael':
0.60; 'best': 0.61; 'true': 0.63; 'opinion': 0.64; 'six': 0.65;
'nearly': 0.67; 'terms': 0.70; 'name,': 0.75; 'disagree': 0.84;
'somebody': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112;
h=mime-version:references:in-reply-to:from:date:message-id:subject:to;
bh=74bHLjy4lyzzAi44lYKcdLnyP8PfpL082qH6x3arZZs=;
b=Zx7epYDYcyKYHCKlqArUnm3EHzTw76Bf6eGQ7aP/1G7Dm7yiJMtU8kxU1U+ezeXlBl
o6c8GUf5Bj3++qP4kLnBPkEJQTuIgrff5tV0KhMWhdznVqr8YCERMb0cAoM1zGqioa+e
ZmsrlkpiBsG2qoEjhEGrv0nN7t3qSu5jX2rZaktdVz8uVZCi018dKCG2LAJlY++UZgwh
uiKQjh8kv0XkAv8yD5/FQ2amO5TJIBPNF+3xmwmzmgGsw2vGXr1pqCdzKn+/n1WIoC5G
XOPxDBYDE/JxSQUzWSKU37HJHOS3YJ/K7Tv5PL289mj+b/LY4/a76O3qoQqxymYQlKnB
kB6Q==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:mime-version:references:in-reply-to:from:date
:message-id:subject:to;
bh=74bHLjy4lyzzAi44lYKcdLnyP8PfpL082qH6x3arZZs=;
b=q3gwOIzNPfWRcIMQ7gMAnVLgq2xh6B7xDReCkQial6Od3qRsEtzaDKTPpx8euU+b1R
fxgZV/wWRO4u2hLJStaKx0lV10+XCK+9dSjngOneHNhqk3rcqDy3yGJTyUa+El3F7kWE
/lJPbJrS/AW3+gWIr+jBsimEzO6EnmSb9FEqG51ifUIEBUYOFYY3TbB0B+rXePOOOH8+
sseaRwMzJzXSGjBkg1sdetSCxlMBK4rNNRCEoh50rdeGtnxARBYprAl7bdQI4cmJvm6N
M6j+nsTYVMNOPzFGUaGU6GZ02hngfJfhx+1vtVMlk8w96HQnI+99LXBBtZUdnsGgcwFk
cEXQ==
X-Gm-Message-State: AOAM530Njd5i1J94CR1MqZe0FYahVK85zr/8gg4aqNnXkPCQcKcDG5Fz
lM8r90nkyiGnZnaZ5dbQrH42jell+ghZaGm9eOh1bgAO
X-Google-Smtp-Source: ABdhPJy0FedLUOlVMMgO3WWRhkmls4RLjhVrWxh+gcELbKehDkW5O+md2/AYRpg4FDURIU/zHINfcdSr+Qexhti8bgU=
X-Received: by 2002:a5d:6da8:0:b0:20a:9377:c389 with SMTP id
u8-20020a5d6da8000000b0020a9377c389mr5250118wrs.495.1650657556500; Fri, 22
Apr 2022 12:59:16 -0700 (PDT)
In-Reply-To: <t3v042$8s1$1@dont-email.me>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
 by: Chris Angelico - Fri, 22 Apr 2022 19:59 UTC

On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper
<michael.stemper@gmail.com> wrote:
>
> I'm writing a function that is nearly self-documenting by its name,
> but still want to give it a docstring. Which of these would be
> best from a stylistic point of view:
>
>
> Tells caller whether or not a permutation is even.
>
> Determines if a permutation is even. (Alternative is that it's odd.)
>
> Returns True if permutation is even, False if it is odd.
>
>
> (Before somebody suggests it, I'm not going to put six weeks' worth
> of a course in group theory in there to help somebody who doesn't
> know what those standard terms mean.)
>

I'd go with the third one, but "Return" rather than "Returns". Or
possibly "Test whether a permutation is even".

That's just one opinion though, others may disagree :)

ChrisA

Re: Style for docstring

<mailman.198.1650657636.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17971&group=comp.lang.python#17971

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: eth...@stoneleaf.us (Ethan Furman)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Fri, 22 Apr 2022 13:00:26 -0700
Lines: 12
Message-ID: <mailman.198.1650657636.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<8209d20c-3953-abb0-3acf-694d52b80434@stoneleaf.us>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de ZZovSPiWP2hjcW+vbsPQPgJG6aTvJVydmANlJ/AKzmWA==
Return-Path: <ethan@stoneleaf.us>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=stoneleaf.us header.i=@stoneleaf.us header.b=WF6cAEHG;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.007
X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; 'received:217.70': 0.09;
'received:gandi.net': 0.09; 'received:mail.gandi.net': 0.09;
'determines': 0.16; 'from:addr:ethan': 0.16;
'from:addr:stoneleaf.us': 0.16; 'from:name:ethan furman': 0.16;
'message-id:@stoneleaf.us': 0.16; 'option.': 0.16; '~ethan~':
0.16; 'wrote:': 0.16; 'to:addr:python-list': 0.20; 'returns':
0.22; 'header:User-Agent:1': 0.30; 'subject:for': 0.33; 'header
:In-Reply-To:1': 0.34; "it's": 0.37; 'michael': 0.60; 'true':
0.63; 'received:217': 0.67
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=stoneleaf.us;
s=gm1; t=1650657629;
h=from:from:reply-to:subject:subject:date:date:message-id:message-id:
to:to:cc:mime-version:mime-version:content-type:content-type:
content-transfer-encoding:content-transfer-encoding:
in-reply-to:in-reply-to:references:references;
bh=3RGiGETfLkUwrz+fcBUiHA0tznG45xfmHiuSYsfYZrI=;
b=WF6cAEHGJW9awjVSyy0bqCgWr9vhfibb36CFrZjsw9e5whNkPSzwnu6UQgJ2hlOe2xDsqP
BMVN5/eUqCCWwcrxcvImvvrrwafdwdR/W1Rr4WUywfyK6turijHjJ7zUGy8lDZfzPXhU21
Ptfk5DGbmhkFc0Mu8qBUVVhKZBMEZOWUhRgOQFs2PS/UPl+dCUKkpGT2KIS8YI0KlhZfBw
R26D67HafiMBsdDGnesW2Dsr8bJz4yQiF2ZfXcl4WwIU6n/VqO8+LEmS4oBMoJGdCnbMy9
1YxAAcdmWBw9Opk30Q4SYHz/+eRmRcFZMMWBEcTuaZyyrGj9RgVfoV7opnB9NA==
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
Thunderbird/91.7.0
Content-Language: en-US
In-Reply-To: <t3v042$8s1$1@dont-email.me>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <8209d20c-3953-abb0-3acf-694d52b80434@stoneleaf.us>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
 by: Ethan Furman - Fri, 22 Apr 2022 20:00 UTC

On 4/22/22 12:36, Michael F. Stemper wrote:

>   Tells caller whether or not a permutation is even.
>
>   Determines if a permutation is even. (Alternative is that it's odd.)
>
>   Returns True if permutation is even, False if it is odd.

Third option.

--
~Ethan~

Re: Style for docstring

<t3v3i3$32j$1@dont-email.me>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17972&group=comp.lang.python#17972

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!eternal-september.org!reader02.eternal-september.org!.POSTED!not-for-mail
From: michael....@gmail.com (Michael F. Stemper)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Fri, 22 Apr 2022 15:35:15 -0500
Organization: A noiseless patient Spider
Lines: 30
Message-ID: <t3v3i3$32j$1@dont-email.me>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Injection-Date: Fri, 22 Apr 2022 20:35:15 -0000 (UTC)
Injection-Info: reader02.eternal-september.org; posting-host="9b617cc56a692a90c6e4b914c700b764";
logging-data="3155"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX19FR7Dypl/pUxoTRUBXAAOmHxNTdsT5Km0="
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
Thunderbird/68.10.0
Cancel-Lock: sha1:lFFcUfFVTruzSYMQqJ4BQ9ypRVg=
In-Reply-To: <mailman.197.1650657557.20749.python-list@python.org>
Content-Language: en-US
 by: Michael F. Stemper - Fri, 22 Apr 2022 20:35 UTC

On 22/04/2022 14.59, Chris Angelico wrote:
> On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper
> <michael.stemper@gmail.com> wrote:
>>
>> I'm writing a function that is nearly self-documenting by its name,
>> but still want to give it a docstring. Which of these would be
>> best from a stylistic point of view:
>>
>>
>> Tells caller whether or not a permutation is even.
>>
>> Determines if a permutation is even. (Alternative is that it's odd.)
>>
>> Returns True if permutation is even, False if it is odd.

>
> I'd go with the third one, but "Return" rather than "Returns". Or
> possibly "Test whether a permutation is even".

"So let it be written. So let it be done."

> That's just one opinion though, others may disagree :)

Two for two. Thanks.

--
Michael F. Stemper
Always remember that you are unique. Just like everyone else.

Re: Style for docstring

<t3v5oo$4qj$1@gioia.aioe.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17973&group=comp.lang.python#17973

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!aioe.org!0BUoxIKeUVSm8bQj8XmtkA.user.46.165.242.75.POSTED!not-for-mail
From: alister....@ntlworld.com (alister)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Fri, 22 Apr 2022 21:12:56 -0000 (UTC)
Organization: Aioe.org NNTP Server
Message-ID: <t3v5oo$4qj$1@gioia.aioe.org>
References: <t3v042$8s1$1@dont-email.me>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Injection-Info: gioia.aioe.org; logging-data="4947"; posting-host="0BUoxIKeUVSm8bQj8XmtkA.user.gioia.aioe.org"; mail-complaints-to="abuse@aioe.org";
User-Agent: Pan/0.149 (Bellevue; 4c157ba git@gitlab.gnome.org:GNOME/pan.git)
X-Notice: Filtered by postfilter v. 0.9.2
 by: alister - Fri, 22 Apr 2022 21:12 UTC

On Fri, 22 Apr 2022 14:36:27 -0500, Michael F. Stemper wrote:

> I'm writing a function that is nearly self-documenting by its name,
> but still want to give it a docstring. Which of these would be best from
> a stylistic point of view:
>
>
> Tells caller whether or not a permutation is even.
>
> Determines if a permutation is even. (Alternative is that it's odd.)
>
> Returns True if permutation is even, False if it is odd.
>
>
> (Before somebody suggests it, I'm not going to put six weeks' worth of a
> course in group theory in there to help somebody who doesn't know what
> those standard terms mean.)

four guidance I would sugest Pep257 as a start point
which would suggest "Return True if permutation is even"

--
I think my career is ruined!

Re: Style for docstring

<mailman.200.1650666163.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17975&group=comp.lang.python#17975

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!aioe.org!news.mixmin.net!news2.arglkargh.de!news.karotte.org!fu-berlin.de!uni-berlin.de!not-for-mail
From: 2QdxY4Rz...@potatochowder.com
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Fri, 22 Apr 2022 17:22:33 -0500
Lines: 42
Message-ID: <mailman.200.1650666163.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Trace: news.uni-berlin.de TY12IBPbcDDlzSvjMCG4nQVNb0vm9HkInrvQyjy8Q4MA==
Return-Path: <2QdxY4RzWzUUiLuE@potatochowder.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=none reason="no signature";
dkim-adsp=none (unprotected policy); dkim-atps=neutral
X-Spam-Status: OK 0.010
X-Spam-Evidence: '*H*': 0.98; '*S*': 0.00; '2022': 0.05; 'tests':
0.07; 'angelico': 0.09; 'received:78': 0.09; '05:56,': 0.16;
'assuming': 0.16; 'database,': 0.16; 'determines': 0.16; 'done."':
0.16; 'from:addr:2qdxy4rzwzuuilue': 0.16;
'from:addr:potatochowder.com': 0.16; 'message-id:@scrozzle': 0.16;
'option.': 0.16; 'received:136.243': 0.16; 'received:78.46': 0.16;
'received:www458.your-server.de': 0.16; 'received:your-server.de':
0.16; 'strategies,': 0.16; 'written.': 0.16; 'wrote:': 0.16;
'to:addr:python-list': 0.20; "i've": 0.22; 'exception': 0.22;
'returns': 0.22; 'sat,': 0.22; 'version': 0.23; 'received:de':
0.23; "i'd": 0.24; 'perform': 0.26; 'leave': 0.27; 'function':
0.27; 'chris': 0.28; 'think': 0.32; 'assume': 0.32; 'programmers':
0.32; 'received:136': 0.32; 'but': 0.32; "i'm": 0.33;
'subject:for': 0.33; 'there': 0.33; 'header:In-Reply-To:1': 0.34;
'yes,': 0.35; 'functions': 0.36; 'possibly': 0.36; "it's": 0.37;
'means': 0.38; 'two': 0.39; 'enough': 0.39; 'still': 0.40;
'something': 0.40; 'want': 0.40; 'michael': 0.60; 'best': 0.61;
'seen': 0.62; 'reasonable': 0.62; 'true': 0.63; 'simply': 0.63;
'let': 0.66; 'nearly': 0.67; 'smart': 0.67; 'items': 0.68;
'name,': 0.75; 'out,': 0.78; 'happens': 0.84; 'received:70': 0.84
Mail-Followup-To: python-list@python.org
Content-Disposition: inline
In-Reply-To: <t3v3i3$32j$1@dont-email.me>
X-Authenticated-Sender: 2QdxY4RzWzUUiLuE@potatochowder.com
X-Virus-Scanned: Clear (ClamAV 0.103.5/26520/Fri Apr 22 10:30:17 2022)
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <YmMqqecSN67EM3Dg@scrozzle>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me>
 by: 2QdxY4Rz...@potatochowder.com - Fri, 22 Apr 2022 22:22 UTC

On 2022-04-22 at 15:35:15 -0500,
"Michael F. Stemper" <michael.stemper@gmail.com> wrote:

> On 22/04/2022 14.59, Chris Angelico wrote:
> > On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper
> > <michael.stemper@gmail.com> wrote:
> > >
> > > I'm writing a function that is nearly self-documenting by its name,
> > > but still want to give it a docstring. Which of these would be
> > > best from a stylistic point of view:
> > >
> > >
> > > Tells caller whether or not a permutation is even.
> > >
> > > Determines if a permutation is even. (Alternative is that it's odd.)
> > >
> > > Returns True if permutation is even, False if it is odd.
>
>
> >
> > I'd go with the third one, but "Return" rather than "Returns". Or
> > possibly "Test whether a permutation is even".
>
> "So let it be written. So let it be done."

"Test whether a permutation is even," while technically factual, leaves
the reader to wonder what form the result takes, and what happens to
that result. Yes, we'd all like to think that programmers are smart
enough to *assume* that the function returns the result of the test.
I've also seen functions that perform tests and then print the results
out, or write them to a database, or simply execute the tests for their
side effects (or leave it up to the individual tests to do something
with the result).

Do you want callers of the function also to assume that True means that
the permutation is even? There are other reasonable strategies, such as
an enumerated type (whose items are Even, Odd, and FileNotFound), or
throwing an exception if the permutation is odd.

I prefer the "return" (rather than "returns") version of the third
option. Assuming that the programmers are familiar with the domain, the
other two leave out important information.

Re: Style for docstring

<mailman.202.1650666832.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17977&group=comp.lang.python#17977

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: ros...@gmail.com (Chris Angelico)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 08:33:37 +1000
Lines: 64
Message-ID: <mailman.202.1650666832.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
X-Trace: news.uni-berlin.de InB5XJePyDeEk8HjjHaIewc3tjGkp9QeES38At+Jq9NQ==
Return-Path: <rosuav@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=gmail.com header.i=@gmail.com header.b=iMyXNyZ7;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.007
X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; '2022': 0.05; 'is.': 0.05;
'angelico': 0.09; 'implicit': 0.09; 'numeric': 0.09; '(eg': 0.16;
'05:56,': 0.16; 'assuming': 0.16; 'chrisa': 0.16; 'default.':
0.16; 'determines': 0.16; 'done."': 0.16; 'enumeration,': 0.16;
'false.': 0.16; 'from:addr:rosuav': 0.16; 'from:name:chris
angelico': 0.16; "isn't,": 0.16; 'object,': 0.16; 'option.': 0.16;
'python;': 0.16; 'received:209.85.128.41': 0.16; 'received:mail-
wm1-f41.google.com': 0.16; 'strategies,': 0.16; 'written.': 0.16;
'wrote:': 0.16; 'python': 0.16; 'says': 0.17; 'to:addr:python-
list': 0.20; 'exception': 0.22; 'returns': 0.22; 'sat,': 0.22;
'version': 0.23; "i'd": 0.24; 'anything': 0.25; 'leave': 0.27;
'function': 0.27; 'chris': 0.28; 'goes': 0.28; 'seem': 0.31;
'raise': 0.31; "doesn't": 0.32; 'assume': 0.32; 'programmers':
0.32; "wouldn't": 0.32; 'message-id:@mail.gmail.com': 0.32; 'but':
0.32; "i'm": 0.33; 'subject:for': 0.33; 'there': 0.33; 'core':
0.34; 'header:In-Reply-To:1': 0.34; 'received:google.com': 0.34;
'definitely': 0.35; 'from:addr:gmail.com': 0.35; 'functions':
0.36; 'possibly': 0.36; "it's": 0.37; 'received:209.85': 0.37;
'means': 0.38; 'received:209': 0.39; 'two': 0.39; 'methods': 0.39;
'neither': 0.39; 'still': 0.40; 'both': 0.40; 'something': 0.40;
'want': 0.40; 'michael': 0.60; 'best': 0.61; 'method': 0.61;
'reasonable': 0.62; 'true': 0.63; 'clear': 0.64; 'deliver': 0.64;
'let': 0.66; 'nearly': 0.67; 'items': 0.68; 'obvious': 0.69;
'raised': 0.70; 'them,': 0.70; 'name,': 0.75; 'happens': 0.84;
'say,': 0.84; 'false;': 0.91; 'true;': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112;
h=mime-version:references:in-reply-to:from:date:message-id:subject:to;
bh=V1JA5+ZF9n5lX+HASefz0prLB0NOCRJuAu/LaWjf8+o=;
b=iMyXNyZ7HYeYnhDFxZnVCzWYGqtvTynQ+6ijY8JYeS6ASdJ34JsC+E9ispD5TxrI+n
iu2XJ27QcwhqxwEgL3t+697YNoU+7kVdp5wzD0JR2SPADXQEdCvxv8M8jzjHhUfsgHtJ
k0iXv7Q3W9Jpc45nKzDv6WR9BWBGVWDjMiLjOOF1TRVh/OEWcJpqNTecfgRy0XD85t5f
HNaMNAZcwO0U8Wac/Y3CEHaQRE6RUxD3BkCBg2AILENIeShApTVauKRSsUHZNxambYuY
r/dPCImhy8diNh7rZUvj4zKTnW/iT2RbKHTee+7yg+NO+bbCbDhr2ujIuFj3jJ6EF8AS
d+Og==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:mime-version:references:in-reply-to:from:date
:message-id:subject:to;
bh=V1JA5+ZF9n5lX+HASefz0prLB0NOCRJuAu/LaWjf8+o=;
b=NBaLgAMrLTBwSjhNgyh5E7uC2EbUX2sNAxa5iOvd4LP1UKuRuhkC9HQBUvunA3Pk1A
94YIb4AuLrzSMj3PUw7i62dyJAXR4qqW/A8UWdRLAGPTkMxqbp/O57bSwTtx2hXX7M7B
oPl2TEeaWPZke4tO/vWLbYaj0k/fkpJgzXnAFGvXxul1Gs6WvnghZK01myvzY/wbv9Tv
mZ633ipgLyvPMl3gZYvAlnjklRERiXwLkZBvHq8qXACc+LXBtfEYhHyh3xvaRam8grNB
qRm3O3V2kpcPlInJWpjFrIVOjt1CoQRuP+hwrcXT71T3T0/HzXjIn94h3LVwUDMxCtPX
EsHQ==
X-Gm-Message-State: AOAM532y4bnDeg+kCNM2ER8jOBVnao0EeRRQhcttf5OJDXd3o1Tbqqeg
zPOpcRhcUWeE3/0VW22FoGIPOP/5a1Ks+1SBlhXcq25b
X-Google-Smtp-Source: ABdhPJxErbN0TyDBZO5q8x8TEkhxraNtcV8PW7aGfrlgoVp/AVoGtHN1fzT4EG10Z6mmlmHxfl0LXX/GF+BeOetBQh8=
X-Received: by 2002:a7b:c201:0:b0:38f:f7f5:f6db with SMTP id
x1-20020a7bc201000000b0038ff7f5f6dbmr15170974wmi.191.1650666829982; Fri, 22
Apr 2022 15:33:49 -0700 (PDT)
In-Reply-To: <YmMqqecSN67EM3Dg@scrozzle>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me>
<YmMqqecSN67EM3Dg@scrozzle>
 by: Chris Angelico - Fri, 22 Apr 2022 22:33 UTC

On Sat, 23 Apr 2022 at 08:24, <2QdxY4RzWzUUiLuE@potatochowder.com> wrote:
>
> On 2022-04-22 at 15:35:15 -0500,
> "Michael F. Stemper" <michael.stemper@gmail.com> wrote:
>
> > On 22/04/2022 14.59, Chris Angelico wrote:
> > > On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper
> > > <michael.stemper@gmail.com> wrote:
> > > >
> > > > I'm writing a function that is nearly self-documenting by its name,
> > > > but still want to give it a docstring. Which of these would be
> > > > best from a stylistic point of view:
> > > >
> > > >
> > > > Tells caller whether or not a permutation is even.
> > > >
> > > > Determines if a permutation is even. (Alternative is that it's odd.)
> > > >
> > > > Returns True if permutation is even, False if it is odd.
> >
> >
> > >
> > > I'd go with the third one, but "Return" rather than "Returns". Or
> > > possibly "Test whether a permutation is even".
> >
> > "So let it be written. So let it be done."
>
> "Test whether a permutation is even," while technically factual, leaves
> the reader to wonder what form the result takes, and what happens to
> that result.

While it's definitely possible to have other results and other ways to
deliver them, the return of a boolean would be the most obvious
default.

> Do you want callers of the function also to assume that True means that
> the permutation is even? There are other reasonable strategies, such as
> an enumerated type (whose items are Even, Odd, and FileNotFound), or
> throwing an exception if the permutation is odd.

I'm assuming that the function is called something like "is_even()"
and that it either is a method on a permutation object, or its
parameters make it very clear what the permutation is.

If it returns an enumeration, I would say that in the docstring. If
the docstring doesn't say, I would assume it returns True or False.

> I prefer the "return" (rather than "returns") version of the third
> option. Assuming that the programmers are familiar with the domain, the
> other two leave out important information.

Core Python methods and functions seem to prefer either "Return ..."
or "Verb the thing" where the result is implicit (eg str.zfill.__doc__
which says "Pad a numeric string..."). Both are used extensively.
Neither form leaves out anything that wouldn't be the obvious default.

We don't need to say "Figures out algorithmically whether the
permutation is even. If it is, will return True; if it isn't, will
return False; if something goes wrong, will raise an exception". This
is Python; we know that if something goes wrong, an exception is
raised. (Though it can help to say WHICH exception will be raised
under WHAT circumstances). Some things are obvious.

ChrisA

Re: Style for docstring

<mailman.203.1650668507.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17978&group=comp.lang.python#17978

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: 2QdxY4Rz...@potatochowder.com
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Fri, 22 Apr 2022 18:01:43 -0500
Lines: 75
Message-ID: <mailman.203.1650668507.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
X-Trace: news.uni-berlin.de C7iwEsDg/ZGQUZKkK1edQQnVuabPUeEVLiiuJdMm4izw==
Return-Path: <2QdxY4RzWzUUiLuE@potatochowder.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=none reason="no signature";
dkim-adsp=none (unprotected policy); dkim-atps=neutral
X-Spam-Status: OK 0.016
X-Spam-Evidence: '*H*': 0.97; '*S*': 0.00; '2022': 0.05; 'is.': 0.05;
'angelico': 0.09; 'fact,': 0.09; 'received:78': 0.09; '05:56,':
0.16; 'apis': 0.16; 'assuming': 0.16; 'default.': 0.16;
'determines': 0.16; 'done."': 0.16; 'enumeration,': 0.16;
'false.': 0.16; 'from:addr:2qdxy4rzwzuuilue': 0.16;
'from:addr:potatochowder.com': 0.16; "isn't,": 0.16; 'message-
id:@scrozzle': 0.16; 'object,': 0.16; 'option.': 0.16; 'python;':
0.16; 'received:136.243': 0.16; 'received:78.46': 0.16;
'received:www458.your-server.de': 0.16; 'received:your-server.de':
0.16; 'strategies,': 0.16; 'written.': 0.16; 'wrote:': 0.16;
'to:addr:python-list': 0.20; "i've": 0.22; 'application.': 0.22;
'exception': 0.22; 'returns': 0.22; 'sat,': 0.22; 'way.': 0.22;
'version': 0.23; 'received:de': 0.23; "i'd": 0.24; '(and': 0.25;
'leave': 0.27; 'function': 0.27; 'chris': 0.28; 'purpose': 0.28;
'goes': 0.28; 'raise': 0.31; 'think': 0.32; "doesn't": 0.32;
'question': 0.32; 'assume': 0.32; 'context': 0.32; 'programmers':
0.32; 'received:136': 0.32; 'but': 0.32; "i'm": 0.33;
'subject:for': 0.33; 'there': 0.33; "didn't": 0.34; 'header:In-
Reply-To:1': 0.34; 'definitely': 0.35; "we're": 0.35; 'possibly':
0.36; "it's": 0.37; 'means': 0.38; 'two': 0.39; 'enough': 0.39;
'still': 0.40; 'something': 0.40; 'want': 0.40; 'michael': 0.60;
'provide': 0.60; 'best': 0.61; 'method': 0.61; 'seen': 0.62;
'skip:i 20': 0.62; 'reasonable': 0.62; 'true': 0.63;
'professional': 0.63; 'clear': 0.64; 'deliver': 0.64; 'opinion':
0.64; 'named': 0.65; 'let': 0.66; 'worked': 0.67; 'nearly': 0.67;
'items': 0.68; 'obvious': 0.69; 'depending': 0.70; 'raised': 0.70;
'them,': 0.70; 'name,': 0.75; 'happens': 0.84; 'received:70':
0.84; 'say,': 0.84; 'false;': 0.91; 'true;': 0.91
Mail-Followup-To: python-list@python.org
Content-Disposition: inline
In-Reply-To: <CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
X-Authenticated-Sender: 2QdxY4RzWzUUiLuE@potatochowder.com
X-Virus-Scanned: Clear (ClamAV 0.103.5/26520/Fri Apr 22 10:30:17 2022)
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <YmMz13q12bOvHl3y@scrozzle>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me>
<YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
 by: 2QdxY4Rz...@potatochowder.com - Fri, 22 Apr 2022 23:01 UTC

On 2022-04-23 at 08:33:37 +1000,
Chris Angelico <rosuav@gmail.com> wrote:

> On Sat, 23 Apr 2022 at 08:24, <2QdxY4RzWzUUiLuE@potatochowder.com> wrote:
> >
> > On 2022-04-22 at 15:35:15 -0500,
> > "Michael F. Stemper" <michael.stemper@gmail.com> wrote:
> >
> > > On 22/04/2022 14.59, Chris Angelico wrote:
> > > > On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper
> > > > <michael.stemper@gmail.com> wrote:
> > > > >
> > > > > I'm writing a function that is nearly self-documenting by its name,
> > > > > but still want to give it a docstring. Which of these would be
> > > > > best from a stylistic point of view:
> > > > >
> > > > >
> > > > > Tells caller whether or not a permutation is even.
> > > > >
> > > > > Determines if a permutation is even. (Alternative is that it's odd.)
> > > > >
> > > > > Returns True if permutation is even, False if it is odd.
> > >
> > >
> > > >
> > > > I'd go with the third one, but "Return" rather than "Returns". Or
> > > > possibly "Test whether a permutation is even".
> > >
> > > "So let it be written. So let it be done."
> >
> > "Test whether a permutation is even," while technically factual, leaves
> > the reader to wonder what form the result takes, and what happens to
> > that result.
>
> While it's definitely possible to have other results and other ways to
> deliver them, the return of a boolean would be the most obvious
> default.

Maybe, depending on the context and purpose of the application.

> > Do you want callers of the function also to assume that True means that
> > the permutation is even? There are other reasonable strategies, such as
> > an enumerated type (whose items are Even, Odd, and FileNotFound), or
> > throwing an exception if the permutation is odd.
>
> I'm assuming that the function is called something like "is_even()"
> and that it either is a method on a permutation object, or its
> parameters make it very clear what the permutation is.
>
> If it returns an enumeration, I would say that in the docstring. If
> the docstring doesn't say, I would assume it returns True or False.

I think we're agreeing, but the OP didn't provide that information.
I've seen enough oddball (yes, that's my professional opinion :-)) APIs
(and worked with enough programmers from enough backgrounds) to know
that "most obvious default" is subjective.

> > I prefer the "return" (rather than "returns") version of the third
> > option. Assuming that the programmers are familiar with the domain,
> > the other two leave out important information.

[...]

> We don't need to say "Figures out algorithmically whether the
> permutation is even. If it is, will return True; if it isn't, will
> return False; if something goes wrong, will raise an exception". This
> is Python; we know that if something goes wrong, an exception is
> raised. (Though it can help to say WHICH exception will be raised
> under WHAT circumstances). Some things are obvious.

No, we don't need to say it that way. I believe that we do need to say
what the function returns under what circumstances.

If, in fact, the function in question is named is_permutation_even, then
it *is* as simple as the OP's third option, but not simpler.

Re: Style for docstring

<mailman.204.1650670232.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17979&group=comp.lang.python#17979

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: rob.cli...@btinternet.com (Rob Cliffe)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 00:25:11 +0100
Lines: 15
Message-ID: <mailman.204.1650670232.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
<5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de 2DocNvr8VYKoHTmMKVog8AHTauVrO03xZItKIzvx852A==
Return-Path: <rob.cliffe@btinternet.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=btinternet.com header.i=@btinternet.com header.b=T8Y2L5Oq;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.024
X-Spam-Evidence: '*H*': 0.95; '*S*': 0.00; 'comments': 0.03; 'e.g.':
0.07; 'programmer': 0.07; 'received:192.168.1.64': 0.09;
'situations': 0.09; 'suggestion,': 0.09; 'does,': 0.16; 'python':
0.16; 'instead': 0.17; 'to:addr:python-list': 0.20; 'returns':
0.22; 'code': 0.23; 'lines': 0.23; 'function': 0.27; 'header:User-
Agent:1': 0.30; 'seem': 0.31; 'think': 0.32; 'received:192.168.1':
0.32; 'but': 0.32; "i'm": 0.33; 'subject:for': 0.33; 'header:In-
Reply-To:1': 0.34; 'following': 0.35; 'addressed': 0.36;
'functions': 0.36; 'people': 0.36; 'received:192.168': 0.37;
'put': 0.38; 'two': 0.39; 'use': 0.39; 'received:213': 0.40;
'wishes': 0.40; 'best': 0.61; 'true': 0.63; 'respond': 0.67;
'per': 0.68; '3rd': 0.81; 'rob': 0.84; '"do': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=btinternet.com;
s=btmx201904; t=1650669911;
bh=p0s/7+AqSe8Tn4BmxGLhVK9CxEDI/bqgg28YSz6UMC8=;
h=Message-ID:Date:MIME-Version:Subject:To:References:From:In-Reply-To;
b=T8Y2L5Oq/DAYZXxNls79rWHmJHeBFO28NcJxUjA6aIYshUT2/P797oo1z4k8PyP93nKc2F6x1/wBX2E0YXDFlyQjQ9nPS9u5xDM4Y2s6MKQ3ex6WsNQnpmHETd41UeO/vUVmOtQfq5Lo+dZ6jsBNsK+QXf9GRbUWv6hNGfbckAYvlX91o1c/mJuDwm+YKTBory9hOrtnCWjBCAY0cQXogJM7rIS3lULHCjQeORuFk83eEq8SwA+abGsKCHe7AaKOWlpHdtQxBs30NrOTcxMbNoht8vqoLY77yg7hkq5TFS1gmqE8BnrSLgkt+k4N0CZ5qJtzyzD9aZ4ooJDHATtOUg==
Authentication-Results: btinternet.com;
auth=pass (PLAIN) smtp.auth=rob.cliffe@btinternet.com;
bimi=skipped
X-SNCR-Rigid: 613A91241F91EB4D
X-Originating-IP: [86.141.29.3]
X-OWM-Source-IP: 86.141.29.3 (GB)
X-OWM-Env-Sender: rob.cliffe@btinternet.com
X-VadeSecure-score: verdict=clean score=0/300, class=clean
X-RazorGate-Vade: gggruggvucftvghtrhhoucdtuddrgedvfedrtdehgddvvdcutefuodetggdotefrodftvfcurfhrohhfihhlvgemuceutffkvffkuffjvffgnffgvefqofdpqfgfvfenuceurghilhhouhhtmecufedtudenucenucfjughrpefkffggfgfuvfhfhfgjtgfgsehtkeertddtfeejnecuhfhrohhmpeftohgsucevlhhifhhfvgcuoehrohgsrdgtlhhifhhfvgessghtihhnthgvrhhnvghtrdgtohhmqeenucggtffrrghtthgvrhhnpedvteduhfetgfevgeeiffelledvuefgieekveevhedutefgveeijeeftdetvedtgeenucfkphepkeeirddugedurddvledrfeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhephhgvlhhopegludelvddrudeikedruddrieegngdpihhnvghtpeekiedrudeguddrvdelrdefpdhmrghilhhfrhhomheprhhosgdrtghlihhffhgvsegsthhinhhtvghrnhgvthdrtghomhdpnhgspghrtghpthhtohepuddprhgtphhtthhopehphihthhhonhdqlhhishhtsehphihthhhonhdrohhrgh
X-RazorGate-Vade-Verdict: clean 0
X-RazorGate-Vade-Classification: clean
X-SNCR-hdrdom: btinternet.com
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:91.0) Gecko/20100101
Thunderbird/91.8.1
Content-Language: en-GB
In-Reply-To: <YmMz13q12bOvHl3y@scrozzle>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
 by: Rob Cliffe - Fri, 22 Apr 2022 23:25 UTC

I don't use docstrings much; instead I put a line or two of comments
after the `def ` line.
But my practice in such situations is as per the OP's 3rd suggestion, e.g.
    # Returns True if .....
I'm curious as to why so many people prefer "Return" to "Returns".
Checking out help() on a few functions in the stdlib, they all used
"Return" or a grammatical equivalent, so this does seem to be a Python
cultural thing.  But why?  To me, "Returns" begins a description as to
what the function does, whereas "Return" is an imperative.  But who is
it addresed to?  Is a function considered to be a sentient entity that
can respond to a command?  Is it an invocation to the lines of code
following the docstring: "Do this!" Might not the programmer mistakenly
think (if only for a moment) that the imperative is addressed to him?
Best wishes
Rob Cliffe

Re: Style for docstring

<mailman.205.1650671966.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17980&group=comp.lang.python#17980

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: ros...@gmail.com (Chris Angelico)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 09:59:13 +1000
Lines: 29
Message-ID: <mailman.205.1650671966.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
<5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
<CAPTjJmpNvCvZH8nOZ8YaVmLNg0YEqNR0gQz+TUyrPk=9hDQm_A@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
X-Trace: news.uni-berlin.de OZhD4rTkUltffHYDdoD0qQBc2usqU9oGJ/YHIcxcAmiQ==
Return-Path: <rosuav@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=gmail.com header.i=@gmail.com header.b=TJfLqISB;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.002
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'comments': 0.03; '2022':
0.05; 'e.g.': 0.07; 'programmer': 0.07; 'thing.': 0.07; 'broad':
0.09; 'git': 0.09; 'situations': 0.09; 'suggestion,': 0.09;
'applied,': 0.16; 'aside': 0.16; 'chrisa': 0.16; 'comments.':
0.16; 'commit': 0.16; 'does,': 0.16; 'from:addr:rosuav': 0.16;
'from:name:chris angelico': 0.16; 'received:209.85.221.47': 0.16;
'received:mail-wr1-f47.google.com': 0.16; 'to?': 0.16; 'wrote:':
0.16; 'python': 0.16; 'instead': 0.17; 'to:addr:python-list':
0.20; 'written': 0.22; 'returns': 0.22; 'sat,': 0.22; 'tools.':
0.22; 'code': 0.23; 'lines': 0.23; 'bit': 0.27; 'function': 0.27;
'seem': 0.31; 'think': 0.32; 'letter,': 0.32; 'python-list': 0.32;
'message-id:@mail.gmail.com': 0.32; 'but': 0.32; "i'm": 0.33;
'subject:for': 0.33; 'header:In-Reply-To:1': 0.34;
'received:google.com': 0.34; '"if': 0.35; 'following': 0.35;
'from:addr:gmail.com': 0.35; 'addressed': 0.36; 'functions': 0.36;
'people': 0.36; 'those': 0.36; 'received:209.85': 0.37; 'put':
0.38; 'read': 0.38; 'received:209': 0.39; 'two': 0.39; 'use':
0.39; 'otherwise,': 0.40; 'initial': 0.61; 'true': 0.63;
'complete': 0.64; 'respond': 0.67; 'per': 0.68; 'sentence': 0.69;
'too.': 0.70; '3rd': 0.81; '"when': 0.84; 'command?': 0.84; 'rob':
0.84; '"do': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112;
h=mime-version:references:in-reply-to:from:date:message-id:subject:to;
bh=Go66UjmaVumKR9muN1xsZ5unABIrLROtNhSjFFDL+7Y=;
b=TJfLqISBnrw9LFQ17UP6EdWWTk9gYsM9zAl7LMbyBQtei1GlUIDkTYvD7OnTQ4DWLa
zs3U7F7/CCNuJDjz7heexSFatDxV+8MfMZmceXxiZQX5BfM/BRuz2gx2k5ZKQyJjV+sP
XoJlF7/IDbuDjnGHrlJ5G0WKg+YoG5ShpMd/3M5pECr2Eyt4Nle5WdfsDB3JynXFBn/q
rZGUHFFUN0lX9/KKYZL28tf6gEc2h81piqjnyWQN0Rhj9xoMuGz9oOIhmGLFQsV/lMUh
e1N/lVR05ub3kc4pFMWOVJlUu2IhBIFP35HPh+aCLfSE0qR9MkKixgc8u6gP87hzQAGB
lwyA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:mime-version:references:in-reply-to:from:date
:message-id:subject:to;
bh=Go66UjmaVumKR9muN1xsZ5unABIrLROtNhSjFFDL+7Y=;
b=xQLxaGcDb9eR+tWdXrvEXWwsNbsrv+XjAsg6ZhVI/3Mn8On1nA+/tLaO6gzE2h0I4C
+y8M5Ob2pH7Qc0YtBssDiTSn9TQ8xy1181nJIRz5zgXodN7Z6KHURogX36fqtmjwlyjM
/8iNvdMmL3iV8u4I85+Lhe76o4AJb07GehG35/F3Lj1Ix55qwwDINGkYKrS+jLIcGs2P
Sisxscx2p2U5R7jqgqoY7tmeXK0j3CpXpJi9J8k/J69CcVCBlk1/chJoY0xmsAnyglrU
rH9F0VhxyVvZMkucJd/vmpaN4/H1H9yABHMK+SJnu3jLuOlq1m28wSQdbmW0SowOINND
bpfA==
X-Gm-Message-State: AOAM531bn2Q3VnWJT37GUpmiDeebIqJ9uxPStWU9TDCHiYnUrK7VfsEJ
gXV9bf4GGGRg3TIxsLZLpxANJCreZqKLd9OyuPFInAyn
X-Google-Smtp-Source: ABdhPJxQoboGV9z61kmVPmggYVRn74t/dFdBCjcYVLZP2nZ5MjIprwI9W4KdNxpnn03YgRB1UhC8FLmYiDsMZ5LJ828=
X-Received: by 2002:a5d:6da8:0:b0:20a:9377:c389 with SMTP id
u8-20020a5d6da8000000b0020a9377c389mr5781727wrs.495.1650671964477; Fri, 22
Apr 2022 16:59:24 -0700 (PDT)
In-Reply-To: <5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <CAPTjJmpNvCvZH8nOZ8YaVmLNg0YEqNR0gQz+TUyrPk=9hDQm_A@mail.gmail.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me>
<YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
<5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
 by: Chris Angelico - Fri, 22 Apr 2022 23:59 UTC

On Sat, 23 Apr 2022 at 09:31, Rob Cliffe via Python-list
<python-list@python.org> wrote:
>
> I don't use docstrings much; instead I put a line or two of comments
> after the `def ` line.
> But my practice in such situations is as per the OP's 3rd suggestion, e.g.
> # Returns True if .....

The point of docstrings is that they can be read by various tools.
Otherwise, they are every bit as good as comments.

> I'm curious as to why so many people prefer "Return" to "Returns".
> Checking out help() on a few functions in the stdlib, they all used
> "Return" or a grammatical equivalent, so this does seem to be a Python
> cultural thing. But why? To me, "Returns" begins a description as to
> what the function does, whereas "Return" is an imperative. But who is
> it addresed to? Is a function considered to be a sentient entity that
> can respond to a command? Is it an invocation to the lines of code
> following the docstring: "Do this!" Might not the programmer mistakenly
> think (if only for a moment) that the imperative is addressed to him?

That's a very broad convention; for instance, git commit messages are
conventionally written imperatively, too. You can think of a commit
message as "If applied, this patch will blah blah blah", and a
docstring as "When called, this function will blah blah blah". Aside
from the initial capital letter, an imperative sentence will nicely
complete those descriptions.

ChrisA

Re: Style for docstring

<mailman.207.1650675443.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17982&group=comp.lang.python#17982

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: pyt...@mrabarnett.plus.com (MRAB)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 01:57:13 +0100
Lines: 46
Message-ID: <mailman.207.1650675443.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
<5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
<120ff739-fecd-ad31-bc7d-5f5ff65bf4c1@mrabarnett.plus.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de g62oUPkrnOane8QEzpnBdQBFwBom4rzBfoxBmJosl4fA==
Return-Path: <python@mrabarnett.plus.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=plus.com header.i=@plus.com header.b=fnOMO5zY;
dkim-adsp=none (unprotected policy); dkim-atps=neutral
X-Spam-Status: OK 0.000
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'comments': 0.03; 'e.g.':
0.07; 'programmer': 0.07; 'string': 0.07; 'example:': 0.09;
'from:addr:python': 0.09; 'prints': 0.09; 'received:192.168.1.64':
0.09; 'situations': 0.09; 'string,': 0.09; 'suggestion,': 0.09;
'import': 0.15; '...,': 0.16; 'appended': 0.16; 'arguments:':
0.16; 'default.': 0.16; 'defaults': 0.16; 'does,': 0.16; 'file-
like': 0.16; 'found.': 0.16; 'from:addr:mrabarnett.plus.com':
0.16; 'from:name:mrab': 0.16; 'message-id:@mrabarnett.plus.com':
0.16; 'object,': 0.16; 'received:84.93': 0.16;
'received:84.93.230': 0.16; 'received:plus.net': 0.16; 'stream.':
0.16; 'values,': 0.16; 'wrote:': 0.16; 'python': 0.16; 'says':
0.17; 'values': 0.17; 'instead': 0.17; 'to:addr:python-list':
0.20; 'maybe': 0.22; 'returns': 0.22; 'code': 0.23; 'lines': 0.23;
'object': 0.26; 'function': 0.27; '>>>': 0.28; 'header:User-
Agent:1': 0.30; 'seem': 0.31; 'default': 0.31; 'module': 0.31;
'think': 0.32; 'keyword': 0.32; 'python-list': 0.32; 'returning':
0.32; 'received:192.168.1': 0.32; 'but': 0.32; "i'm": 0.33;
'subject:for': 0.33; 'header:In-Reply-To:1': 0.34; 'following':
0.35; 'addressed': 0.36; 'functions': 0.36; 'people': 0.36;
"it's": 0.37; 'received:192.168': 0.37; 'put': 0.38; 'two': 0.39;
'use': 0.39; 'file:': 0.40; 'match': 0.40; 'search': 0.61; 'skip:h
10': 0.61; 'true': 0.63; 'between': 0.63; 're:': 0.64; 'respond':
0.67; 'per': 0.68; '3rd': 0.81; 'rob': 0.84; '"do': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=plus.com; s=042019;
t=1650675436; bh=lWVjrlxzuuBgrHqfemxp3MaGNPBJ6xisPyqkayzg7J0=;
h=Date:Subject:To:References:From:In-Reply-To;
b=fnOMO5zYRx+2rR3NxrHSGCQdYP29LIOGq3tFAnGzbhhJ944s7nMUmriW3o1cDpklz
t94b2fL+tpbm+BokvQSSkGXL3to6KvX8NcvoVazIUEGK/WV4U1cSMmeLQ85lbSPr4A
/+S+Xqx6+SMeJSjuME4nqAO3JFSiJ5VTv7GYAn3RJA3gKM0Ne5hJc8yD10q0UXfl2U
7zAK5F3Ku1r0eMLW2RWf0YfbkOjwieXJnlVHWO6pbUZ52T8ipC8s2FRE3k/Gtge+Bw
SVmgAT1D7/grBjSVwDas389p6+VqmZgeWLtHyygOMBDhbeqOGlLwwC5n/cwdX8XgRN
Z4prnCm6LNB8A==
X-Clacks-Overhead: "GNU Terry Pratchett"
X-CM-Score: 0.00
X-CNFS-Analysis: v=2.4 cv=HttlpmfS c=1 sm=1 tr=0 ts=62634eec
a=0nF1XD0wxitMEM03M9B4ZQ==:117 a=0nF1XD0wxitMEM03M9B4ZQ==:17
a=IkcTkHD0fZMA:10 a=8sUeKzd6vG0zWBvNzzsA:9 a=QEXdDO2ut3YA:10
X-AUTH: mrabarnett@:2500
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:91.0) Gecko/20100101
Thunderbird/91.8.1
Content-Language: en-GB
In-Reply-To: <5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
X-CMAE-Envelope: MS4xfPF4DMkyjad2mJQrLzav4axjBxLqPQuhcDeDgeYzWECAlnfXFIle0uCUb8SxSTDfCbaCqi3HeseQYaGxHtTZDVHn05bwBLfvQVPHc1DWNk8p+TzvmMMl
h+r9GMZm+jTCjM57eMkp5aXf31m2CbQPxADnnniNpwP6Lw1XjYw9oh5pXDz2neM5GyI276Q7qO7M25RsiCWmjQ1Ay74fyqqcBXc=
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <120ff739-fecd-ad31-bc7d-5f5ff65bf4c1@mrabarnett.plus.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
<5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
 by: MRAB - Sat, 23 Apr 2022 00:57 UTC

On 2022-04-23 00:25, Rob Cliffe via Python-list wrote:
> I don't use docstrings much; instead I put a line or two of comments
> after the `def ` line.
> But my practice in such situations is as per the OP's 3rd suggestion, e.g.
>     # Returns True if .....
> I'm curious as to why so many people prefer "Return" to "Returns".
> Checking out help() on a few functions in the stdlib, they all used
> "Return" or a grammatical equivalent, so this does seem to be a Python
> cultural thing.  But why?  To me, "Returns" begins a description as to
> what the function does, whereas "Return" is an imperative.  But who is
> it addresed to?  Is a function considered to be a sentient entity that
> can respond to a command?  Is it an invocation to the lines of code
> following the docstring: "Do this!" Might not the programmer mistakenly
> think (if only for a moment) that the imperative is addressed to him?

Maybe it's because the function name is often also an imperative, e.g.:

>>> import re
>>> help(re.search)
Help on function search in module re:

search(pattern, string, flags=0)
Scan through string looking for a match to the pattern, returning
a Match object, or None if no match was found.

Note "Scan", not "scans".

I was going to use 'print' as the example:

>>> help(print)
Help on built-in function print in module builtins:

print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

but it says "Prints", not "Print"...

Re: Style for docstring

<mailman.208.1650682689.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17983&group=comp.lang.python#17983

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!weretis.net!feeder8.news.weretis.net!news.szaf.org!fu-berlin.de!uni-berlin.de!not-for-mail
From: avigr...@verizon.net (Avi Gross)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 02:58:05 +0000 (UTC)
Lines: 105
Message-ID: <mailman.208.1650682689.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<1761313929.296888.1650682685708@mail.yahoo.com>
Reply-To: Avi Gross <avigross@verizon.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
X-Trace: news.uni-berlin.de TmtsgjLT+T37DP7viLfWhgYIPOHNSCq3u0ySxLDewe/A==
Return-Path: <avigross@verizon.net>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=verizon.net header.i=@verizon.net header.b=QvJxYbye;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.001
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'looks': 0.02; 'argument':
0.04; 'knows': 0.04; '2022': 0.05; 'fairly': 0.05; 'is.': 0.05;
'string': 0.07; '().': 0.09; 'angelico': 0.09; 'deeper': 0.09;
'implicit': 0.09; 'numeric': 0.09; 'obviously': 0.09; 'theory':
0.09; '&gt;': 0.14; 'url:mailman': 0.15; '(eg': 0.16; '05:56,':
0.16; 'assuming': 0.16; 'assumption': 0.16; 'breakfast,': 0.16;
'chrisa': 0.16; 'default.': 0.16; 'determines': 0.16; 'done."':
0.16; 'enumeration,': 0.16; 'false.': 0.16; "isn't,": 0.16;
'object,': 0.16; 'odd': 0.16; 'option.': 0.16; 'python;': 0.16;
'resources,': 0.16; 'sounds': 0.16; 'strategies,': 0.16; 'think.':
0.16; 'written.': 0.16; 'wrote:': 0.16; 'python': 0.16; 'says':
0.17; 'values': 0.17; 'uses': 0.19; 'to:addr:python-list': 0.20;
'exception': 0.22; 'fri,': 0.22; 'returns': 0.22; 'sat,': 0.22;
'skip:& 40': 0.22; 'version': 0.23; "i'd": 0.24; 'to:name:python-
list@python.org': 0.24; 'anything': 0.25; 'skip:- 10': 0.25; 'url-
ip:188.166.95.178/32': 0.25; 'url-ip:188.166.95/24': 0.25;
'saying': 0.25; 'url:listinfo': 0.25; 'url-ip:188.166/16': 0.25;
'anyone': 0.25; 'normally': 0.26; 'object': 0.26; 'leave': 0.27;
'function': 0.27; 'chris': 0.28; 'goes': 0.28; 'error': 0.29;
'seem': 0.31; 'raise': 0.31; 'url-ip:188/8': 0.31; 'think': 0.32;
"doesn't": 0.32; 'assume': 0.32; 'concept': 0.32; 'empty': 0.32;
'programmers': 0.32; 'structure': 0.32; "wouldn't": 0.32; 'but':
0.32; "i'm": 0.33; 'subject:for': 0.33; 'there': 0.33; 'core':
0.34; 'header:In-Reply-To:1': 0.34; 'complex': 0.35; 'definitely':
0.35; 'meaning': 0.35; 'yes,': 0.35; 'errors': 0.36; 'functions':
0.36; 'possibly': 0.36; 'people': 0.36; "it's": 0.37; 'could':
0.38; 'means': 0.38; '8bit%:14': 0.38; 'two': 0.39; 'enough':
0.39; 'valid': 0.39; 'list': 0.39; 'methods': 0.39; 'neither':
0.39; 'still': 0.40; '22,': 0.40; 'true.': 0.40; 'both': 0.40;
'something': 0.40; 'want': 0.40; 'michael': 0.60; 'including':
0.60; 'best': 0.61; 'likely': 0.61; 'method': 0.61; 'skip:o 10':
0.61; 'from:': 0.62; 'to:': 0.62; 'reasonable': 0.62; 'skip:o 20':
0.63; 'true': 0.63; 'clear': 0.64; 'deliver': 0.64; 'others,':
0.64; 're:': 0.64; 'let': 0.66; 'nearly': 0.67; 'accept': 0.67;
'items': 0.68; 'and,': 0.69; 'obvious': 0.69; 'manual': 0.70;
'raised': 0.70; 'them,': 0.70; 'too.': 0.70; 'ignore': 0.71;
'direct': 0.73; '8bit%:31': 0.73; 'name,': 0.75; 'sent:': 0.78;
'header:Reply-To:1': 0.79; 'returned': 0.81; 'happens': 0.84;
'noted': 0.84; 'say,': 0.84; 'false;': 0.91; 'true;': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=verizon.net; s=a2048;
t=1650682686; bh=w9v3/JrqcMrborJPGaXL6OOAi3fjA/X+ouXnDjHio9M=;
h=Date:From:Reply-To:To:In-Reply-To:References:Subject:From:Subject:Reply-To;
b=QvJxYbyeAceg5Uw6WrzXkzztSqc+om7iXGXzzCBrfYbfbaEn7eGrxXdeJ1mSZtl7nB/o92eciXhkNF6zKWcCEkgycP3MlG8LaKngR0l0gT8Aui4rlUXc30RadwNs5mXxfXeC3a2Mc5kCANdv8MPnZB4JC+kg277dSHrcv76JcBmvVULqpPx9VnwlL1k5E6qYim6xjNLcRYPqiWyb8R7wYivSLq3nWm86cnQUwfsR20C1SXh1kjPjtYYmmp1hvLnKw/PitUYNkIOPV1NQlREWuHZ7s70T5OgQbsBmiLIpNvarYTqnYWdB5h/oic5LuOSxTqmEoDDqyvBQNK+QVCn21w==
X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048;
t=1650682686; bh=rEtA9Gc3UT5JYaXQW7+JwASg3Jrf0XeIVfAA+vUMwjI=;
h=X-Sonic-MF:Date:From:To:Subject:From:Subject;
b=YYXOUNItu0TxAk2LaFq00TtXS/gku32sAfd9tsrowVz4UAWbABGds1QFJz229Cn+H80Ovjj4dUJ5TAJ7FzrirywcQAu34V6YZJSBX5/bin1KcoU1Vyd1RiHCfFhdqqIkMFinukzcgZM67hkU6znUYgihP8k6e9ZkV+6CesrHB7LPx5rb8sMuxbbIpL492NHYLKYoKk0FqNYjTp6gtMWAJa7vPTQls4Y6BIvHTITcedWgfSRzO1yd/k7qetwUQVXIHT169UNs3FssSVYy4dJo86xYWyjuVn11xmLqYEHi5Qb6rOR+wmA4TrsDA+1QiRkDC/cK+g9app2D0uDiP7NpuA==
X-YMail-OSG: wRuracUVM1nrjcBnkN2PF1WpqPBWIwDojv7E41UAfntbyNxo0.5a6vFp97IqL85
10qJkVKysRuqYiIkpPIootzzWA9dJ4jZ5rbhXwP_wuP9l.Scowa_NfqH9YBEWE_lODn9UJR7d_Am
FEJcAt55z0R3DKfsbdcHmW_c3EAShPQ9caQrSFfauUujb_U4758JQzPOlMbdD4cqa_FeNoM8QoRh
WRs4nA86WGOHgVcY93YoVswY3BulUws8CUFOqpJ.FIMslLAx.GTqX3fQ1IB.lSQkDEpBJBWVorJJ
IT37MjD2Wrw0nmHVd14iGZFaSLjKb2uf0OIq.QoZeTUU5K6O4ji86a.dOXVtBb4bEEqKOlVWAgFY
ckbyvl6ebQPzm.P.c1JecVPkttr9mqYbYGfEQYQjVi0FtxYwzwGScBaYWUyRkan5exw1AfOcncDi
wWikPPrW0_fs_4V_C9xak4C5ocUBiQ1LuF3E35Ik6LBgeETQgov3PUpRdO4X452wbKdvXloEFCJV
9ThrE7Wt5BZJaI0rKMDnyNTRdgHbm5KgQR_Fj.h.cg_8Aut3HZHHnGZkOK9cFTZA88vKZQTIkpdp
eu2vkGSgEBwSJO278YAyPM3oIkKGkHUWwC1duWkPraps6Kvi4lEKKICzNYJfDZycJfs87SKHsx3C
qVmysj7JkHFzKhjyjArSjRlCcfX4vwrPQW3AfLj_BMy3Kpon1U1H0mW.HvDRsbd.rN2bBYsNvVS_
rIeMk3yp2P0na.WvwMA5xK.SOnF.UasEr2QwOwzWEREK1uoUjxQ03F9yLu3suK66Rwd3moaesAc9
UPQP2SOMmhoWEJ4UBMNmEingiTneTHE3dvMZRfDUx21P_wnnEmK3.UoCKkSCztTypKofZMqvUpZ6
7NeRWowvCAqVEKtCm4BXo4kEggqlkbLlHiFTxsyspl4D8dx.5yn6uoxKaRFbikFntHZWpm9MCXr4
nKFohunBSDn.7fcLB7gMGm2RJW_VOuh_v4yoAdNu8sxcrkVQFYHdIRD.uiPxnH0v8InPJA4SRpap
Nk7Op9kO.6oXvmi1lJgREMLhCU8GHflfq7DpexuoOU8oXrcG8tMnSLw2GIKZgi055hI5v1eEWAwj
0Meq7PLyDyb_rF2TB4URIGGfUBLKFvP9mZ62Nol7Dd_ohjPZ7BmpzT0ARbadTMA8IUqLXnCGUoF3
dua4N29qpBxOXqWVAbe96dmZ9giDtBZvMY6HHZ_6cWu3xvGG4APh_FOFDWaH3qGv.TVvVFon79ZK
jmrAVD4qsx4ZcnnbuRodRPkrB0VoVrvz6_5bzpPuGZy9_pHJYOxFo8VI6fYiarbdFYJ4pNO7GodP
hnN5O2q67BnVi3Wkngc.13YxD4wR1GqrEqzOIDpqjwqXLY7PDLFpyd.wxafsyN1JYIojwY0e37Kf
N9ZiDUjDMlOd55IUUUld.dDHK2Ffs3uv2ewH7BsRNpmWGXpB08vmgM9GuupPAob8xMGKhSKSeeLQ
jZ.HzoleYym38rUfYGuAVBJEFH2wvfMqlnf_81QTpNC21B7QQUguxagS61g4eFEcn02ojga2l_83
.YEd999ugtR6j0tR5pqdxWZmB.BSfjo3HCKmyHiLiaQb3mpRKo7gLcFKN2mpRBEAEBSPp0rQpI9z
X0uHspxyYLqhv9vgRjKimWKEhQgRuufy0UiVbK15LxXDXBOd06V_d2N4WO1UwfLQaaOPEl4.jaf6
b3W4rmNkrAucxaK74B05NP3iGzhDrZiSdHsULpCgzCGDMLB3nPRPmqmDAYSxnLGlwtruooNKcI5K
qfTiJq9Jp1cxtav1GjMdqVNUDrtgi3NMXU0znoIILMIHo88eLX1SvnreBy_GXydy4_NWB3QCnTpU
IxpY8_b3hqKfugnso0rEopIGt2VzUsvbepECDFWU4CZPIqHmgt1SI1Bd5Iz9sW2YwV21K47guxx4
.EECodS23cEqxTPizck5SyTOQQhO5Fs.2PTkooPXgwQGvslz9UuQV1il7xUmku2oIkP0u8TOx99n
kfkMzS4DMgroBvD4V1Kue7UsvpHKt_Pig9P_lF67AJFpUC3laqc53_pQf28pXz51eMndqQ777zY_
C7m0iYP.04q1nfbgqw86L33_2OCaMIAcQGo5e_uh1.L3SCCfb3Cv9rsax85W3.wzjIExfM9BiaNA
pj1R9abY7p0fHco0jCMhEnxxaFCT0q8lRZ9QIE0ZA1sYLgdBpZtkxu8_Lrqb70QqM1EKOwNaiRwo
f1LCaCRuRMrK_1s_jEHVI9CAIyhr8_Q--
X-Sonic-MF: <avigross@verizon.net>
In-Reply-To: <CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
X-Mailer: WebService/1.1.20118 aolwebmail
X-Content-Filtered-By: Mailman/MimeDel 2.1.39
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <1761313929.296888.1650682685708@mail.yahoo.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
 by: Avi Gross - Sat, 23 Apr 2022 02:58 UTC

Python does have a concept of "truthy" that includes meaning for not just the standard Booleans but for 0 and non-zero and the empty string and many more odd things such as an object that defines __bool__ ().
But saying it returns a Boolean True/False valuesounds direct and simple and informative enough if that is True.
What bothers me is the assumption that anyone knows not so muchjust group theory  but what the argument to the function looks like as a Python object of some kind. 
Does the function accept only some permutation object managed by a specific module? Will it accept some alternate representation such as a list structure or other iterator?
Obviously deeper details would normally be in a manual page or other documentation but as "permutations" are likely not to be what most people think about before breakfast, or even  after, odd as that may seem, ...
And, yes, I know what it means and some users will too. But as all permutations must be even or odd, errors thrown might be based on whether the data structure has valid contents or is so complex that it uses up all system resources, I would think.

So the docstring could be fairly short and something like:
Given a permutation in <FORM> Returns the Boolean value True if it is graded as <EVEN> or False if <ODD> or an exception if the argument is not valid.

As noted by others, Many things can be returned including multiple values where perhaps the second one tells if there was an error but thatthe user can ignore or not even catch.
-----Original Message-----
From: Chris Angelico <rosuav@gmail.com>
To: python-list@python.org
Sent: Fri, Apr 22, 2022 6:33 pm
Subject: Re: Style for docstring

On Sat, 23 Apr 2022 at 08:24, <2QdxY4RzWzUUiLuE@potatochowder.com> wrote:
>
> On 2022-04-22 at 15:35:15 -0500,
> "Michael F. Stemper" <michael.stemper@gmail.com> wrote:
>
> > On 22/04/2022 14.59, Chris Angelico wrote:
> > > On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper
> > > <michael.stemper@gmail.com> wrote:
> > > >
> > > > I'm writing a function that is nearly self-documenting by its name,
> > > > but still want to give it a docstring. Which of these would be
> > > > best from a stylistic point of view:
> > > >
> > > >
> > > >    Tells caller whether or not a permutation is even.
> > > >
> > > >    Determines if a permutation is even. (Alternative is that it's odd.)
> > > >
> > > >    Returns True if permutation is even, False if it is odd.
> >
> >
> > >
> > > I'd go with the third one, but "Return" rather than "Returns". Or
> > > possibly "Test whether a permutation is even".
> >
> > "So let it be written. So let it be done."
>
> "Test whether a permutation is even," while technically factual, leaves
> the reader to wonder what form the result takes, and what happens to
> that result.

While it's definitely possible to have other results and other ways to
deliver them, the return of a boolean would be the most obvious
default.

> Do you want callers of the function also to assume that True means that
> the permutation is even?  There are other reasonable strategies, such as
> an enumerated type (whose items are Even, Odd, and FileNotFound), or
> throwing an exception if the permutation is odd.

I'm assuming that the function is called something like "is_even()"
and that it either is a method on a permutation object, or its
parameters make it very clear what the permutation is.

If it returns an enumeration, I would say that in the docstring. If
the docstring doesn't say, I would assume it returns True or False.

> I prefer the "return" (rather than "returns") version of the third
> option.  Assuming that the programmers are familiar with the domain, the
> other two leave out important information.

Core Python methods and functions seem to prefer either "Return ..."
or "Verb the thing" where the result is implicit (eg str.zfill.__doc__
which says "Pad a numeric string..."). Both are used extensively.
Neither form leaves out anything that wouldn't be the obvious default.

We don't need to say "Figures out algorithmically whether the
permutation is even. If it is, will return True; if it isn't, will
return False; if something goes wrong, will raise an exception". This
is Python; we know that if something goes wrong, an exception is
raised. (Though it can help to say WHICH exception will be raised
under WHAT circumstances). Some things are obvious.

ChrisA
--
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

<mailman.209.1650684309.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17984&group=comp.lang.python#17984

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: avigr...@verizon.net (Avi Gross)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 03:26:57 +0000 (UTC)
Lines: 83
Message-ID: <mailman.209.1650684309.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
<5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
<120ff739-fecd-ad31-bc7d-5f5ff65bf4c1@mrabarnett.plus.com>
<2098309954.284734.1650684417423@mail.yahoo.com>
Reply-To: Avi Gross <avigross@verizon.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
X-Trace: news.uni-berlin.de vSSBNSjplWKIYEAVN9RkOA09Rc2/48dWWvMe78muTybA==
Return-Path: <avigross@verizon.net>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=verizon.net header.i=@verizon.net header.b=uYobk7sD;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.002
X-Spam-Evidence: '*H*': 1.00; '*S*': 0.00; 'comments': 0.03; '2022':
0.05; '&gt;&gt;&gt;': 0.07; 'programmer': 0.07; 'string': 0.07;
'thing.': 0.07; 'example:': 0.09; 'prints': 0.09; 'situations':
0.09; 'string,': 0.09; 'suggestion,': 0.09; 'textbook': 0.09;
'import': 0.15; 'url:mailman': 0.15; '...,': 0.16; 'appended':
0.16; 'arguments:': 0.16; 'default.': 0.16; 'defaults': 0.16;
'does,': 0.16; 'file-like': 0.16; 'found.': 0.16; 'object,': 0.16;
'shorter': 0.16; 'stream.': 0.16; 'things,': 0.16; 'to?': 0.16;
'values,': 0.16; 'wrote:': 0.16; 'python': 0.16; 'says': 0.17;
'values': 0.17; 'instead': 0.17; 'to:addr:python-list': 0.20;
'language': 0.21; 'fri,': 0.22; 'maybe': 0.22; 'returns': 0.22;
'way.': 0.22; 'code': 0.23; 'lines': 0.23; 'to:name:python-
list@python.org': 0.24; 'skip:- 10': 0.25; 'url-
ip:188.166.95.178/32': 0.25; 'url-ip:188.166.95/24': 0.25;
'url:listinfo': 0.25; 'programming': 0.25; 'url-ip:188.166/16':
0.25; 'object': 0.26; 'function': 0.27; '>>>': 0.28; 'sense':
0.28; 'seem': 0.31; 'default': 0.31; 'module': 0.31; 'url-
ip:188/8': 0.31; 'think': 0.32; 'instructor': 0.32; 'keyword':
0.32; 'python-list': 0.32; 'realize': 0.32; 'returning': 0.32;
'but': 0.32; "i'm": 0.33; 'subject:for': 0.33; 'same': 0.34;
'header:In-Reply-To:1': 0.34; 'english,': 0.35; 'particularly':
0.35; 'yes,': 0.35; 'following': 0.35; 'addressed': 0.36;
'functions': 0.36; 'people': 0.36; 'using': 0.37; "it's": 0.37;
'others': 0.37; 'put': 0.38; 'read': 0.38; 'two': 0.39;
'otherwise': 0.39; 'use': 0.39; '22,': 0.40; 'file:': 0.40;
'match': 0.40; 'something': 0.40; 'want': 0.40; 'english': 0.60;
'view': 0.60; 'tell': 0.60; 'search': 0.61; 'skip:o 10': 0.61;
'skip:h 10': 0.61; 'from:': 0.62; 'to:': 0.62; 'skip:o 20': 0.63;
'true': 0.63; 'between': 0.63; 'skip:b 10': 0.63; 'others,': 0.64;
're:': 0.64; 'company': 0.64; 'well': 0.65; '8bit%:7': 0.67;
'respond': 0.67; 'per': 0.68; 'documenting': 0.69; 'sent:': 0.78;
'header:Reply-To:1': 0.79; '3rd': 0.81; 'bothered': 0.84;
'command?': 0.84; 'rob': 0.84; '"do': 0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=verizon.net; s=a2048;
t=1650684306; bh=qu9qicMJQ14JIcRKQBIKaMgBliEbbtxoV6vwE0XMvR0=;
h=Date:From:Reply-To:To:In-Reply-To:References:Subject:From:Subject:Reply-To;
b=uYobk7sDHJngCtMRVuL6XgbjOzccHZ+P24ZPToj1QINU7o5DdEI6ZU+3bK2YBiSFR1j/chyBxLRL9Q+XkrnX3vJ+zOZxI6SeyowntWVtN6Uqxd8bnrjsgNxiz260RgE90VSmq2dgRrAdfdxD1bH4eHQXydGieLv+itTghea5yTWOu0JudVJ4m9bHdP/evCt96WANPRl6NKASc1UH3sgsPK0q4Mt9uABva9NdEPI5WdrpEdjFbpmhoZI8elHEPHSuNEe9B1rvDCJdzCKCM50nBURhiAhOyWf/XBnNuBJr+RDKg7wnR0qkrni/jBDLih/EiYRMOFHZw+oydjsIxJDzgQ==
X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048;
t=1650684306; bh=B4nVxPq2iLpbORS/VxVf5CpeEXGXTw6seWTO5iUVHWt=;
h=X-Sonic-MF:Date:From:To:Subject:From:Subject;
b=Gq9wpbPElqh2eGESuyEqOKOKpW/Un+xWc62w0lAJq3cismSDZBeSLzUmJGYy4il2HoYjP/Lrh68GjVgXOQ73t9yjAXVGNf20QFOrZ8YbSD9wqoDECOluvL6G5I+6KWWftjm2vX6+ZqIU7d5Q9lWfI+R0qYEzdE35bMjeygZ8ajeI6iQvOXByx5m8s+zNa+5mgZupIHAjrHEv61edbQsIUBmaR76sc3blDUGuCh0sfdPHcgUO2WCfyoDh5Y6hvvQkIUgHWdrmjqWZRUsCrwbB+fIefYsgGhkmiJLrb2uER2kDrqIgTvm3IiaGMF5EtAvQ+/pIIsXsRVvqwW9mqWQyhQ==
X-YMail-OSG: mAr1socVM1nD01MgP20AAar2Kh.SLuKfAEbptiWZSYfO9zc1k3rQFSn76HUstca
5U2q2i4O8qxcv0XtZLM0QqoKyVm2J2ubocYu6ygvB019hJfLhm2tWsM2bbF4zOijZHVUgy2yIeEb
BrnW5pnJlNV27Me2qHm.SvxezI9X48IOlDazl6rh24kWQdYq3yLZfDkvPHs5pSEQVim0ml3M_TXu
oYFzKkJolTyP9p.Ucj4Xh6mJfpmo6eVEcSQgeIG9brcoJK1Lr8rjHOxjgKxWoDgsAqyX_UV4DBpZ
YdFHcd9uBos_ZB1lfdFhl19MWeviC7iXD8pfsaMesmiGiZu1akHdL4tz.SVR4SHV9G0.LsYNXAca
dnqsc3Tb_trmEUDCZct04Ogq9sfGRfYHJH8IVd8lKkHcdPL.qn9LK92gvtaCWQE1Ozwg5n6ka8l.
95joXwVWhfy3lHvq8UkHvQrsctg3NE3w258S7Xt_mddhRUkHLedSvDZ9rdj15ZZbo75YxXes5Y7B
Cu2L0GHZkgCoA96a416P5VDjMig6YNihC.Tsg44shto57HdV3ryxLXqVXNbETdR9aBeEF98l7.sq
2woJZH3ullqV4RUuOTbOlbPWV6woYPaMuWSkj62F80YMChSj0SLAIH4PTmDwtowYSGn6aUo0maqm
SuX5IRjuS_X2j1ZVQ9fBbQgCQIbXyg5kWdiidDjzgX_0CxjopLmmaYYMywe2uyjIaa2fd0nkVxrj
jfmi37.QwWI11zHa4C_882HfXDtDI89byFA_n.qQHG8omwE7yLr6TmaRvxWouD0kHLTA9M7xEz_t
A6yYbumV.0Fqy0ahzBBRhrVa7lY3WNzDw4XWp4CW93gKHrA6maQEUKINC_ZYPtA6fVNcRxC6SlSa
DFcn3XH1lhfXF3Phvz7kzJrLkWQ4nFkIF88PJUzmPH1dzHJ7dYeTZQx6kQvAJfTXDpLw3KHTuBDb
DnnN5Uam5RtmObNmHXzaU1JJEog4tBrMzJudIQd_5FM6EIYeZvOOtZmOdubNoTNLR09_A2t1IQfp
sijuSpDX_8o6GGAWwVjgiVwDddsiGsVV7BgWaw_DHcnxKZp4MFcxevwAXOKkj1YTm_pCqxbMAn0c
QwbDWsGe2Nx1fPRMNoxuJL6bDeaw2BnyHzYhzg3rDfO8AJjFZsoTqmShE3B6DzMW8o9KWY48ATkb
ysyAsNuLEJ_8iCe2q_gXXX5CbkeKzWqiayH7cLTDuz87P29UXxAYPDGgxY1jJbEc0h1aJMozZFfY
C7N3LokO3eNZlTvivh9cLLNmYlwKYqXAQhK74mZc4aol3rzKpX2F_nnOf.LMllxqszus3tDJJhCl
2.h27Rj7MVvxG0K2Nl57bjD24heEo8Xr4XF8.THpDjMwLD7whV0LvO2bKGIEblz8DurDnympSdgt
T.rw5gWN3UOKE_J.uPIz72wqN1xafMW3zHpuRN9r7OzU_IY9KvjMAlPd02Bqq9eNksXXMr1OmaPJ
9Q3QQ.EZQN.WwU_8dYd6AYmL26yY800bDm1c493KHF_bY5ac4ucI4A1KQvrtCHzYMYhCENfUB0c2
g6XcEzf5L_6Y.A5Gy1VlfGr19jd1RRSsTgH1UB4ilvuMRIjn036kxyzs0pITrULGa_99WDCq90V8
2ddOcji6gvFN1xowTF6jUoKB7xTeaFz5E3AJHCrqErs451yJwzQO9DqCbEi3KGg--
X-Sonic-MF: <avigross@verizon.net>
In-Reply-To: <120ff739-fecd-ad31-bc7d-5f5ff65bf4c1@mrabarnett.plus.com>
X-Mailer: WebService/1.1.20118 aolwebmail
X-Content-Filtered-By: Mailman/MimeDel 2.1.39
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <2098309954.284734.1650684417423@mail.yahoo.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
<5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
<120ff739-fecd-ad31-bc7d-5f5ff65bf4c1@mrabarnett.plus.com>
 by: Avi Gross - Sat, 23 Apr 2022 03:26 UTC

We know some people using "professional" language make things shorteror talk from a point of view different than others and often in otherwise incomprehensible jargon.
If a programmer is taking about the algorithm that a function implements, then, yes, they may write "scan" and "return".
But if they realize the darn documentation is for PEOPLE asking how to use the darn thing, and want to write in more informal and understandable English, I think it makes more sense to say what the function does as in "scans" and importantly what it "returns" to the user as a result.
So if you are taking a programming course and the instructor or textbook is giving imperitave commands, they may well tell youto scan something then calculate something and use a return statement a certain way.
I can read many ways and am not particularly bothered by either style but when documenting what is, I prefer proper English (or any otherlanguage) in communicating what it does for them.
As with many such things, if you work for a company or with groups of others, it is wise to find out what is expected and do the same as much as reasonable.

-----Original Message-----
From: MRAB <python@mrabarnett.plus.com>
To: python-list@python.org
Sent: Fri, Apr 22, 2022 8:57 pm
Subject: Re: Style for docstring

On 2022-04-23 00:25, Rob Cliffe via Python-list wrote:
> I don't use docstrings much; instead I put a line or two of comments
> after the `def ` line.
> But my practice in such situations is as per the OP's 3rd suggestion, e.g..
>      # Returns True if .....
> I'm curious as to why so many people prefer "Return" to "Returns".
> Checking out help() on a few functions in the stdlib, they all used
> "Return" or a grammatical equivalent, so this does seem to be a Python
> cultural thing.  But why?  To me, "Returns" begins a description as to
> what the function does, whereas "Return" is an imperative.  But who is
> it addresed to?  Is a function considered to be a sentient entity that
> can respond to a command?  Is it an invocation to the lines of code
> following the docstring: "Do this!" Might not the programmer mistakenly
> think (if only for a moment) that the imperative is addressed to him?

Maybe it's because the function name is often also an imperative, e.g.:

>>> import re
>>> help(re.search)
Help on function search in module re:

search(pattern, string, flags=0)
    Scan through string looking for a match to the pattern, returning
    a Match object, or None if no match was found.

Note "Scan", not "scans".

I was going to use 'print' as the example:

>>> help(print)
Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:  string inserted between values, default a space.
    end:  string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

but it says "Prints", not "Print"...
--
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

<afdf478c-6582-4d7a-baa2-eb389d333576n@googlegroups.com>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17985&group=comp.lang.python#17985

 copy link   Newsgroups: comp.lang.python
X-Received: by 2002:ac8:5984:0:b0:2f3:5aca:5844 with SMTP id e4-20020ac85984000000b002f35aca5844mr3765290qte.685.1650684541450;
Fri, 22 Apr 2022 20:29:01 -0700 (PDT)
X-Received: by 2002:a05:620a:2805:b0:67d:5c7e:c43a with SMTP id
f5-20020a05620a280500b0067d5c7ec43amr4686374qkp.84.1650684541327; Fri, 22 Apr
2022 20:29:01 -0700 (PDT)
Path: i2pn2.org!i2pn.org!weretis.net!feeder6.news.weretis.net!news.misty.com!border2.nntp.dca1.giganews.com!nntp.giganews.com!news-out.google.com!nntp.google.com!postnews.google.com!google-groups.googlegroups.com!not-for-mail
Newsgroups: comp.lang.python
Date: Fri, 22 Apr 2022 20:29:01 -0700 (PDT)
In-Reply-To: <t3v042$8s1$1@dont-email.me>
Injection-Info: google-groups.googlegroups.com; posting-host=93.41.97.190; posting-account=F3H0JAgAAADcYVukktnHx7hFG5stjWse
NNTP-Posting-Host: 93.41.97.190
References: <t3v042$8s1$1@dont-email.me>
User-Agent: G2/1.0
MIME-Version: 1.0
Message-ID: <afdf478c-6582-4d7a-baa2-eb389d333576n@googlegroups.com>
Subject: Re: Style for docstring
From: jul...@diegidio.name (Julio Di Egidio)
Injection-Date: Sat, 23 Apr 2022 03:29:01 +0000
Content-Type: text/plain; charset="UTF-8"
Lines: 29
 by: Julio Di Egidio - Sat, 23 Apr 2022 03:29 UTC

On Friday, 22 April 2022 at 21:36:53 UTC+2, Michael F. Stemper wrote:
> I'm writing a function that is nearly self-documenting by its name,
> but still want to give it a docstring. Which of these would be
> best from a stylistic point of view:
>
> Tells caller whether or not a permutation is even.
>
> Determines if a permutation is even. (Alternative is that it's odd.)
>
> Returns True if permutation is even, False if it is odd.
>
> (Before somebody suggests it, I'm not going to put six weeks' worth
> of a course in group theory in there to help somebody who doesn't
> know what those standard terms mean.)

You just need to learn some professional programming.

"Return*s* true if the permutation is even, otherwise false"
or better:
"Returns whether the permutation is even"
or even better:
"Returns whether the given permutation is even"

> 87.3% of all statistics are made up by the person giving them.

No shit...

HTH, you and the whole resident brigade of geniuses.

Julio

Re: Style for docstring

<d04ef695-648c-4fbe-9edd-a11efecdc5cdn@googlegroups.com>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17986&group=comp.lang.python#17986

 copy link   Newsgroups: comp.lang.python
X-Received: by 2002:ac8:5a89:0:b0:2f3:5ab1:3e4f with SMTP id c9-20020ac85a89000000b002f35ab13e4fmr3756799qtc.528.1650685718925;
Fri, 22 Apr 2022 20:48:38 -0700 (PDT)
X-Received: by 2002:a05:622a:6098:b0:2f0:f0d2:b5f0 with SMTP id
hf24-20020a05622a609800b002f0f0d2b5f0mr5305418qtb.583.1650685718803; Fri, 22
Apr 2022 20:48:38 -0700 (PDT)
Path: i2pn2.org!i2pn.org!weretis.net!feeder6.news.weretis.net!news.misty.com!border2.nntp.dca1.giganews.com!nntp.giganews.com!news-out.google.com!nntp.google.com!postnews.google.com!google-groups.googlegroups.com!not-for-mail
Newsgroups: comp.lang.python
Date: Fri, 22 Apr 2022 20:48:38 -0700 (PDT)
In-Reply-To: <mailman.209.1650684309.20749.python-list@python.org>
Injection-Info: google-groups.googlegroups.com; posting-host=93.41.97.190; posting-account=F3H0JAgAAADcYVukktnHx7hFG5stjWse
NNTP-Posting-Host: 93.41.97.190
References: <t3v042$8s1$1@dont-email.me> <CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org> <t3v3i3$32j$1@dont-email.me>
<YmMqqecSN67EM3Dg@scrozzle> <CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle> <5cb9890e-02f4-9746-3e80-784aa95adf4c@btinternet.com>
<2098309954.284734.1650684417423@mail.yahoo.com> <120ff739-fecd-ad31-bc7d-5f5ff65bf4c1@mrabarnett.plus.com>
<mailman.209.1650684309.20749.python-list@python.org>
User-Agent: G2/1.0
MIME-Version: 1.0
Message-ID: <d04ef695-648c-4fbe-9edd-a11efecdc5cdn@googlegroups.com>
Subject: Re: Style for docstring
From: jul...@diegidio.name (Julio Di Egidio)
Injection-Date: Sat, 23 Apr 2022 03:48:38 +0000
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Lines: 17
 by: Julio Di Egidio - Sat, 23 Apr 2022 03:48 UTC

On Saturday, 23 April 2022 at 05:25:29 UTC+2, Avi Gross wrote:

> As with many such things, if you work for a company or with groups of others, it is wise to find out what is expected and do the same as much as reasonable.

If you work for a company that sucks at it, as more and more do (compared to today, if you think in the 80's we had a software crisis, you have no clue), you do NOT abide to it: that's not the mission unless you ask HR or your local counsellors... Indeed if you do that in general, you just get the insane society that we do have.

"87.3% of all statistics are made up by the person giving them." No shit....

HTH and good luck.

Julio

Re: Style for docstring

<imperative-20220423113313@ram.dialup.fu-berlin.de>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17987&group=comp.lang.python#17987

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: ram...@zedat.fu-berlin.de (Stefan Ram)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: 23 Apr 2022 10:35:26 GMT
Organization: Stefan Ram
Lines: 25
Expires: 1 Apr 2023 11:59:58 GMT
Message-ID: <imperative-20220423113313@ram.dialup.fu-berlin.de>
References: <t3v042$8s1$1@dont-email.me> <CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com> <mailman.197.1650657557.20749.python-list@python.org> <t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle> <CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com> <YmMz13q12bOvHl3y@scrozzle> <mailman.204.1650670232.20749.python-list@python.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de PPafuHWImYyrGrr0LHo//AJqznJ5l7PYbO67CyL76f1Do7
X-Copyright: (C) Copyright 2022 Stefan Ram. All rights reserved.
Distribution through any means other than regular usenet
channels is forbidden. It is forbidden to publish this
article in the Web, to change URIs of this article into links,
and to transfer the body without this notice, but quotations
of parts in other Usenet posts are allowed.
X-No-Archive: Yes
Archive: no
X-No-Archive-Readme: "X-No-Archive" is set, because this prevents some
services to mirror the article in the web. But the article may
be kept on a Usenet archive server with only NNTP access.
X-No-Html: yes
Content-Language: en-US
Accept-Language: de-DE, en-US, it, fr-FR
 by: Stefan Ram - Sat, 23 Apr 2022 10:35 UTC

Rob Cliffe <rob.cliffe@btinternet.com> writes:
>I'm curious as to why so many people prefer "Return" to "Returns".

The commands, er, names of functions, use the imperative mood
("print", not "prints"). So, "return" aligns with that mood
as a paraphrase of such names.

In Java, at one point, they decided to start to use the
third person at one point and then half-heartedly converted
all the documentation, as in

|void println(boolean x)
|Prints a boolean and then terminate the line.

, where they modified "print" but did not bother do modify
"terminate".

And instead of "return true if this, false if not this",
I might be inclined to write "return true iff this".

BTW: As a language element that helps to construct a boolean
expression from a file name, some languages, like SQL, use
"EXISTS", while others, like MS-DOS-batch, use "EXIST".

Re: Style for docstring

<t40t3c$vb0$1@dont-email.me>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17988&group=comp.lang.python#17988

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!eternal-september.org!reader02.eternal-september.org!.POSTED!not-for-mail
From: michael....@gmail.com (Michael F. Stemper)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 07:57:07 -0500
Organization: A noiseless patient Spider
Lines: 19
Message-ID: <t40t3c$vb0$1@dont-email.me>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<1761313929.296888.1650682685708@mail.yahoo.com>
<mailman.208.1650682689.20749.python-list@python.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Injection-Date: Sat, 23 Apr 2022 12:57:16 -0000 (UTC)
Injection-Info: reader02.eternal-september.org; posting-host="4748c91e313d8f571d8453cfd6db7589";
logging-data="32096"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX196d6nSUlvbaa3cnrGI//+hueNkS33Kq5I="
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
Thunderbird/68.10.0
Cancel-Lock: sha1:+kCZza2XeoMCdA56jfHq1Azskno=
In-Reply-To: <mailman.208.1650682689.20749.python-list@python.org>
Content-Language: en-US
 by: Michael F. Stemper - Sat, 23 Apr 2022 12:57 UTC

On 22/04/2022 21.58, Avi Gross wrote:
> Python does have a concept of "truthy" that includes meaning for not just the standard Booleans but for 0 and non-zero and the empty string and many more odd things such as an object that defines __bool__ ().
> But saying it returns a Boolean True/False valuesounds direct and simple and informative enough if that is True.
> What bothers me is the assumption that anyone knows not so muchjust group theory  but what the argument to the function looks like as a Python object of some kind.
> Does the function accept only some permutation object managed by a specific module? Will it accept some alternate representation such as a list structure or other iterator?

That's a fair point. However, this function will be the 22nd one in
a module for dealing with permutations and groups of permutations.
The module has a lengthy docstring explaining the several ways provided
to specify a permutation. That way, the same information doesn't need
to be written twenty-plus times.

> Obviously deeper details would normally be in a manual page or other documentation but as "permutations" are likely not to be what most people think about before breakfast, or even  after, odd as that may seem, ...

I see what you did there :->

--
Michael F. Stemper
Psalm 94:3-6

Re: Style for docstring

<t413o7$ipm$2@dont-email.me>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17990&group=comp.lang.python#17990

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!eternal-september.org!reader02.eternal-september.org!.POSTED!not-for-mail
From: michael....@gmail.com (Michael F. Stemper)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 09:50:47 -0500
Organization: A noiseless patient Spider
Lines: 18
Message-ID: <t413o7$ipm$2@dont-email.me>
References: <t3v042$8s1$1@dont-email.me> <t3v5oo$4qj$1@gioia.aioe.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Injection-Date: Sat, 23 Apr 2022 14:50:47 -0000 (UTC)
Injection-Info: reader02.eternal-september.org; posting-host="4748c91e313d8f571d8453cfd6db7589";
logging-data="19254"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX19ozArEFgyrk4HmtN8femUELSWQJIWslrY="
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
Thunderbird/68.10.0
Cancel-Lock: sha1:m3eZQDX2hOdXjRs3M+jaRlkMk4Q=
In-Reply-To: <t3v5oo$4qj$1@gioia.aioe.org>
Content-Language: en-US
 by: Michael F. Stemper - Sat, 23 Apr 2022 14:50 UTC

On 22/04/2022 16.12, alister wrote:
> On Fri, 22 Apr 2022 14:36:27 -0500, Michael F. Stemper wrote:
>
>> I'm writing a function that is nearly self-documenting by its name,
>> but still want to give it a docstring. Which of these would be best from
>> a stylistic point of view:

> for guidance I would sugest Pep257 as a start point
> which would suggest "Return True if permutation is even"

I'll take a look at the PEP. Thanks.

--
Michael F. Stemper
This email is to be read by its intended recipient only. Any other party
reading is required by the EULA to send me $500.00.

Re: Style for docstring

<mailman.211.1650735794.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17991&group=comp.lang.python#17991

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: avigr...@verizon.net (Avi Gross)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 17:43:06 +0000 (UTC)
Lines: 59
Message-ID: <mailman.211.1650735794.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<1761313929.296888.1650682685708@mail.yahoo.com>
<mailman.208.1650682689.20749.python-list@python.org>
<t40t3c$vb0$1@dont-email.me>
<214129016.357437.1650735786870@mail.yahoo.com>
Reply-To: Avi Gross <avigross@verizon.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
X-Trace: news.uni-berlin.de 7gO3akW8UjgWPY6VhETUAAp04EKR9Q2rItYJB3k1YqkA==
Return-Path: <avigross@verizon.net>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=verizon.net header.i=@verizon.net header.b=IK/XUpRX;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.004
X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; 'looks': 0.02; 'argument':
0.04; 'knows': 0.04; '2022': 0.05; 'class.': 0.07; 'string': 0.07;
'().': 0.09; 'deeper': 0.09; 'numpy': 0.09; 'obviously': 0.09;
'skip:[ 20': 0.09; 'theory': 0.09; '&gt;': 0.14; 'url:mailman':
0.15; 'assumption': 0.16; 'avi': 0.16; 'breakfast,': 0.16;
'customized': 0.16; 'easiest': 0.16; 'explaining': 0.16; 'gross':
0.16; 'odd': 0.16; 'specify': 0.16; 'vector': 0.16; 'wrote:':
0.16; 'problem': 0.16; 'python': 0.16; 'larger': 0.17; 'to:addr
:python-list': 0.20; 'written': 0.22; 'returns': 0.22; 'sat,':
0.22; 'to:name:python-list@python.org': 0.24; 'skip:- 10': 0.25;
'url-ip:188.166.95.178/32': 0.25; 'url-ip:188.166.95/24': 0.25;
'saying': 0.25; 'url:listinfo': 0.25; 'url-ip:188.166/16': 0.25;
'anyone': 0.25; 'normally': 0.26; 'object': 0.26; 'suspect': 0.26;
'function': 0.27; 'done': 0.28; 'module': 0.31; 'url-ip:188/8':
0.31; 'think': 0.32; "doesn't": 0.32; 'concept': 0.32; 'empty':
0.32; 'structure': 0.32; 'but': 0.32; 'subject:for': 0.33;
'there': 0.33; 'same': 0.34; 'package': 0.34; 'header:In-Reply-
To:1': 0.34; 'meaning': 0.35; 'errors': 0.36; 'functions': 0.36;
'people': 0.36; 'others': 0.37; 'could': 0.38; 'enough': 0.39;
'handle': 0.39; 'valid': 0.39; 'list': 0.39; 'forms': 0.40;
'true.': 0.40; 'something': 0.40; 'michael': 0.60; 'likely': 0.61;
'skip:h 10': 0.61; 'from:': 0.62; 'to:': 0.62; 'point.': 0.62;
'skip:o 20': 0.63; 'skip:b 10': 0.63; 're:': 0.64;
'received:74.6.135': 0.64; 'times.': 0.64; 'your': 0.64; 'bad':
0.67; 'accept': 0.67; 'and,': 0.69; 'manual': 0.70; 'direct':
0.73; 'deal': 0.73; '8bit%:31': 0.73; 'handles': 0.76; 'sent:':
0.78; 'header:Reply-To:1': 0.79; 'converts': 0.84; 'cycle': 0.84;
'ideally': 0.84; 'michael,': 0.84; 'storage': 0.95
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=verizon.net; s=a2048;
t=1650735791; bh=OaznmsAQcWSi3ZBs5K4WX5TOLwvfPYqnAJmHWmK+FnI=;
h=Date:From:Reply-To:To:In-Reply-To:References:Subject:From:Subject:Reply-To;
b=IK/XUpRXW8plX9y3Er+t8kevHjvmqiVJLhjdm9A7ZCZgcoUnej6ovFY3RIQ83VjYIx5TC1hjv/hHC4vcEeLWE09SqVl9dir3cF4FUN2+zK0VDIFDFB8RifwgqlpeJBLiUHDfXP1fDo5y3o26E4ZBJ7vuYEYje/v0LIGNdrMBYrLwxybqPFdfJ4EujWE4wU1C6XiKmJXOJJcuSRcKQ5nMGf9So3kLVsxy5eMf1YkoGLqqZkeadK/a7hOZEO3S+EAJJAVp1EPnOu2FdaKNTqKzVoLaRrxBt9R3WTp2HoY5HwurNxToC8dxvhcP9IYgZ3KU5bOaiPOevyCM7G4y5rGWJQ==
X-SONIC-DKIM-SIGN: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048;
t=1650735791; bh=g81SgLn4LXcvbDAGd5eJM4c/KnITSAA7K2t9aWG670a=;
h=X-Sonic-MF:Date:From:To:Subject:From:Subject;
b=I/4mhtfQtH+pxQOIkGW3X4X7fJKjEWv3bacR1NTyaBfkx5b8j3wnF3GQd2UFgTjBncwlZNVADNQH0P8atowuQYDbMpVSbnq0di0+uOs0OQkpvdpALE7YTwLSvuCw4IBuOP1bXTQhkYWm4yKG6ZEvTsH0EG6rMPM3iMVL46fgiWAmaULTIZm0TMHIXlnH15kIZbaAlY1kMwDpPEMewBUvRVol3gvYaj1zf0OxXC9obljzEPLkzQ9QTClqVpRE2ScJadEwH/6r2kvjXKIaw5wRlHOTuehIPxNjbK/93alnDemLwKq41wbxD4Klg8pmZ4Xv6OXu2HiIERgp+2yquWkAew==
X-YMail-OSG: PnH50IYVM1kQBa4VDTnxlwK5levsqUldkaPiMh_iSGC8lcMaevgPRzm3EG._5Em
apAnG0Cx9BSHWURJJJFsgRXZzudczFJY89H9lvfwrMdPbLGmtGUnlKN2MoA.xmlWEkKN.OwEDPt9
ORsuV2k7NWGWUlVNJmFVA2AJAxQlcutiHim9QzC4QI.a_JCeXF37JULwSi7w.wu4NiwYcYdGSpiB
ToiwGCvL6sOEOzNW91KXe5i8rnFvvT83JpzW8WqlO8M8Mucu5GbXWB9H8g3WR84rh5H6s.zp4rh5
VFh0dH6c_X0ZtANFm5Aph.cPT2Anl0CWvei1C3Vp6z5MwsXzl94jhFGluZnOvj7a23Rawmw7smGA
wE7kCYH8LM.RxkHBV1uhViyerT9bSvwVZcFmHEHOinA03rEaLlB9.6nW.gMYWTw_H9Ygy_ymZx3l
TzCbJIjLkZSP.PDkVFAy6nOCZmmU8OfBwJlx2TWrfXXDqFUJvV4wg6L925AyeoPmlFHpmK2aUxNP
AmZ2Gen5yZKYPqVpY97fh1hzr3x1JtQTUoiz0eiFzyVpA8mLiowzsK9YbKgNwDAVrOWtbef3AWd2
6FLxgNOKUO59wSYzV5XccxpSDWspsnLUB7wOkrgV0iuH5_tTFEDja9N0fFA9n6DreJY5Q.BFO2YW
fgOPrLjO3Xq7.dyu2EHwPd0UZSfFT3s9rHQ6KR9hdJS7Ijnd9asrRi_vCagLzN1AOg6dRvmlSPgJ
sDlPKDzhw7blXZ5kf7ktBfp.Qp0ZL56h_yx71xvaMoKSFGvh6SUU2MVuHyVu7JnSBHQHMtAdAGK8
TvnoDQh1qkQtCujFXOV_Pt8WaHPGLqZnVntImkPRtkJ8uZEUhuV9_dlGVQpjww3zSkBgpZo0eJ_n
ZJUb8pR.pzK0K6YwaaYx9yHIYxc_ddMDk9qMkD6MEwgEnqvgXz7Jp9XA7b1eCdLuy1LBKVRGRy0X
aEiicGe2C4m987jJdYjSUnWzQeo3_yGjbLnqaRSahlGQuG24K_B8ot5cRcdiE8pMhJs51FsbJAzo
OVDpDhN38SXY4CzcJEG3.FgA32AnufqXk_a_MfjLQwTY5m2GLIOsFMcc1WTKCYClE7vxSu1sHgHx
iFdmutknvdFpTJBsuCiN.Y7AQ6nUcbQHdUdI1PfhVA88HgliMyzIBy2kTNWuYSRM42Bd5eTuQM4E
qJL9awDgridgXVjmvgY7sILz60g8UwEdiPA_uULHIpKZkgKfasIyO.byCZzEneZfgsbszpfl35W9
aOv6LbtULuC1m2By7auitmw5bDkyRxLTyxr10OeeZS2cZDvS78..2mFZUbaMImCBlNX8z3TyFoqs
Uhpy0HG1qF1XDwN5nQ3EuXVHxRsx4DU3A1a2pOtTdA.Akx2alCsWLOstTikDqIu5MWJiEe5pDN2B
LtdYY.fnRcgWDXGsPDhqN0111FvhGQ0PhSnzv0etBYczz_Cl21MkxtzTsAS4jTgpSdQvkCue47Fg
LmvOFGDs2aovVe.3ipJk5JKxqZ4STON5aINUZCZ0V2mWyGKPZVBPL2225z1LLGWeOjQ5fZG9GHqb
QDno76Y_bru9vGCklbcUONCGNkg1c2U4Fn7YbOBTcDTVVRM0lE45RDcAwll9hq7ug8K59kDmEM_O
_oGtbCzzzX_KZjz0HAENozN1AQ8mjM2UzaFf8WbFWOly7XTFC_E8ezXtIROvRaqQ93M9rWU3AlXl
2RvgKZWaDh2i9FlJYOA.uSUJLlDsX0i5LATBIsJwLCSddq_TH50tq4SZRFbb44Q_ASfbVLcsa0HO
ZyJ6oK1vYU8d.VwlazlOsWJhGSvKwdqd8L4eGDMrKsUbqIlnxQPILX4big5rjyk5cjcym1YCbLmE
S_VtL33dYn_wYykFS0fXBGNvvJycCaKTJ3VvbKQJZr2rgH36k1p4KGltHURN59mWHWGkFw6U3JpA
lfR_bwNNS2wPzmYFP78vZswGGs5yW6P1dRiv4fQuL1YWCR8cU0qn8bQWmUB_xJ2lmTAnsmFlXSlL
AxTCnLlXnAXJmXVmGnMq5nLBwZDyvDlamenIIJjvEOk0l8dGYxA4GxdRbc6trGaGzlmmGdnMxxRx
vQ0TbH9DBEarpsOUgGrmn9tPKK5qoWAzYwTvFZRISf2koa_rFvkmIsyDLrppgTbU_r39e8odJSV0
BtGjdSEL3GCXltQ7ImU_XylYFZ_TgD7wyH0UcTxIYffWQRiIoGF6lZdVBHILEai9YX3YAfWIyjQ-
-
X-Sonic-MF: <avigross@verizon.net>
In-Reply-To: <t40t3c$vb0$1@dont-email.me>
X-Mailer: WebService/1.1.20118 aolwebmail
X-Content-Filtered-By: Mailman/MimeDel 2.1.39
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <214129016.357437.1650735786870@mail.yahoo.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<1761313929.296888.1650682685708@mail.yahoo.com>
<mailman.208.1650682689.20749.python-list@python.org>
<t40t3c$vb0$1@dont-email.me>
 by: Avi Gross - Sat, 23 Apr 2022 17:43 UTC

Given what you added, Michael, your function is part of a larger collection of functions and being compatible with the others is a valid consideration. Whatever you decide, would ideally be done consistently with all or most of them.
And, of course, it others in the collection also can handle multiple ways to specify a permutation, it may be simpler to have each call something like as.permutation() that handlesmultiple forms and converts to the one easiest for you to use.
I am not sure that is needed as I suspect the simplest storage is something like a list:  [0,3,2,4,5,6,7,1,9,8] but could also be shown with each cycle as a sub-list or something like anumpy vector or a customized class.
Clearly if you control the package and how it is used, errors from bad data may not be a concern. But like many Boolean return(s) it is always a problem how to deal with a third possibility.

-----Original Message-----
From: Michael F. Stemper <michael.stemper@gmail.com>
To: python-list@python.org
Sent: Sat, Apr 23, 2022 8:57 am
Subject: Re: Style for docstring

On 22/04/2022 21.58, Avi Gross wrote:
> Python does have a concept of "truthy" that includes meaning for not just the standard Booleans but for 0 and non-zero and the empty string and many more odd things such as an object that defines __bool__ ().
> But saying it returns a Boolean True/False valuesounds direct and simple and informative enough if that is True.
> What bothers me is the assumption that anyone knows not so muchjust group theory  but what the argument to the function looks like as a Python object of some kind.
> Does the function accept only some permutation object managed by a specific module? Will it accept some alternate representation such as a list structure or other iterator?

That's a fair point. However, this function will be the 22nd one in
a module for dealing with permutations and groups of permutations.
The module has a lengthy docstring explaining the several ways provided
to specify a permutation. That way, the same information doesn't need
to be written twenty-plus times.

> Obviously deeper details would normally be in a manual page or other documentation but as "permutations" are likely not to be what most people think about before breakfast, or even  after, odd as that may seem, ...

I see what you did there :->

--
Michael F. Stemper
Psalm 94:3-6
--
https://mail.python.org/mailman/listinfo/python-list

Re: Style for docstring

<mailman.213.1650739385.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17993&group=comp.lang.python#17993

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: drsali...@gmail.com (Dan Stromberg)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 11:42:51 -0700
Lines: 21
Message-ID: <mailman.213.1650739385.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAGGBd_q12HeSc-115VkdPDr2n=vwLAjEZ4j++rh23obDzrxzjQ@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
X-Trace: news.uni-berlin.de Pk6V21w/szOI/3JqDLSEfgylVVlwBHnoxhUPBoP7xIbA==
Return-Path: <drsalists@gmail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=gmail.com header.i=@gmail.com header.b=JcHoqQt8;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.059
X-Spam-Evidence: '*H*': 0.88; '*S*': 0.00; '2022': 0.05; 'cc:addr
:python-list': 0.09; 'theory': 0.09; 'cc:name:python list': 0.16;
'determines': 0.16; 'from:addr:drsalists': 0.16; 'from:name:dan
stromberg': 0.16; 'wrote:': 0.16; 'cc:addr:python.org': 0.20;
'fri,': 0.22; 'maybe': 0.22; 'returns': 0.22; 'cc:2**0': 0.25;
'function': 0.27; 'it,': 0.29; "doesn't": 0.32; 'message-
id:@mail.gmail.com': 0.32; 'but': 0.32; "i'm": 0.33;
'subject:for': 0.33; 'there': 0.33; 'header:In-Reply-To:1': 0.34;
'received:google.com': 0.34; 'from:addr:gmail.com': 0.35; 'those':
0.36; "it's": 0.37; 'received:209.85': 0.37; 'put': 0.38;
'received:209': 0.39; 'still': 0.40; '22,': 0.40; 'want': 0.40;
'try': 0.40; 'michael': 0.60; 'best': 0.61; 'true': 0.63; 'six':
0.65; 'nearly': 0.67; 'terms': 0.70; 'name,': 0.75; 'somebody':
0.91
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112;
h=mime-version:references:in-reply-to:from:date:message-id:subject:to
:cc; bh=/2Syu/0tHZ+FqC9Z7Oj++PiaPq/enypD7JjtA+ncBwA=;
b=JcHoqQt8XkiaceYPyNnRnkcPHZNeKKuWwwQhW0oz+XZyFEIfEJM+3AyRQ0+2NPe2s3
kx5mDQfZ4V4LJ7heOVcFQp9fIsXrhbmYdSKZEwdeo6QdDwZd9JMOaUco1VQ+Gk49ljTe
MJ9tP9hMdi5pgDaqlRY1shHOYmSunAKzmiWBl8khCLyqLpN+iX3b0vrCzYUkPlPKlL30
bVAYdWgEhDL3s4JuRoKWuXoAPZ/MEBTnz3xLTj+o338oBj2DiioVBeR2Mh1JrCjORYfG
URoWYmHLVs7SWUOFwduDnKXSEVRBLvoZZHKj20M97DjDMYBcHt6iLa/JKcu37HK2Na98
lilA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:mime-version:references:in-reply-to:from:date
:message-id:subject:to:cc;
bh=/2Syu/0tHZ+FqC9Z7Oj++PiaPq/enypD7JjtA+ncBwA=;
b=lV1qIzDON5q64p8rkwSH0zpLgVIg+rd0AQkOT1U1M2WWP5QCn2HfTF4fb2nEWOI0Nz
zpSbtB4Ds9E3qdHFBRx02io4AU/MdnABpkNjLugkBM7N/lpLF9Rhich4njGxrjJuT2pa
3lwiWfIuaWrEgs9YGy1h9EHXYeHd6OTTevuye2ykwQFimcSM/7TZiXJ+i57NtwsLwEp5
T7Z+SRBW/0cKJQFZ7JLllgEccoM1I6TS/RFrf7sG6EKWbJA4g+vL5CWgX/SLhEb1jLNN
kJgkfNnMXLgobn7M0AIzFl0yNId2pt4Q+JW7CaPYFra+kujN+nSA8rlNJWfDgRWAqJyE
1AqQ==
X-Gm-Message-State: AOAM531pKt/SyK+fQpm9KiT9ARtrbr8rc80oPc1JScu4mrknqTbRYYMO
hHyVeiuO7Qh3LvosPLOm0oYekOJG64NLRaXcTtIIefdMxzg=
X-Google-Smtp-Source: ABdhPJzVsTf08DsFSs09SfwX/2E9CFw2kiE1AkXT6IcPeFWVyjKgCpc5SB4NMxoZte5a+Au48He25StqPjwxjeO+NMk=
X-Received: by 2002:a1f:50c4:0:b0:336:e84d:2873 with SMTP id
e187-20020a1f50c4000000b00336e84d2873mr3333274vkb.30.1650739383250; Sat, 23
Apr 2022 11:43:03 -0700 (PDT)
In-Reply-To: <t3v042$8s1$1@dont-email.me>
X-Content-Filtered-By: Mailman/MimeDel 2.1.39
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <CAGGBd_q12HeSc-115VkdPDr2n=vwLAjEZ4j++rh23obDzrxzjQ@mail.gmail.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
 by: Dan Stromberg - Sat, 23 Apr 2022 18:42 UTC

On Fri, Apr 22, 2022 at 12:56 PM Michael F. Stemper <
michael.stemper@gmail.com> wrote:

> I'm writing a function that is nearly self-documenting by its name,
> but still want to give it a docstring. Which of these would be
> best from a stylistic point of view:
>
>
> Tells caller whether or not a permutation is even.
>
> Determines if a permutation is even. (Alternative is that it's odd.)
>
> Returns True if permutation is even, False if it is odd.
>
>
> (Before somebody suggests it, I'm not going to put six weeks' worth
> of a course in group theory in there to help somebody who doesn't
> know what those standard terms mean.)
>

Maybe try pydocstyle?

Re: Style for docstring

<mailman.215.1650740954.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=17995&group=comp.lang.python#17995

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: rtm4...@googlemail.com (jan)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sat, 23 Apr 2022 20:09:11 +0100
Lines: 35
Message-ID: <mailman.215.1650740954.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
<mailman.204.1650670232.20749.python-list@python.org>
<imperative-20220423113313@ram.dialup.fu-berlin.de>
<CADJx9Ldo3ariS+jurcbGs64MdD4pu8nQ+QhXD5A+nF4gFcyr9A@mail.gmail.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
X-Trace: news.uni-berlin.de fgRKpkCVv0h2B5NIet2BfgZp9HIkG14Hz9ZpTabUdZrw==
Return-Path: <rtm443x@googlemail.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=googlemail.com header.i=@googlemail.com header.b=grbyfIbR;
dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.022
X-Spam-Evidence: '*H*': 0.96; '*S*': 0.00; 'ram': 0.07; 'cc:addr
:python-list': 0.09; 'construct': 0.09; 'expression': 0.09;
'from:addr:googlemail.com': 0.09; 'writes:': 0.09; 'cc:no real
name:2**0': 0.14; 'url:mailman': 0.15; 'functions,': 0.16;
'to:addr:ram': 0.16; 'to:addr:zedat.fu-berlin.de': 0.16;
'to:name:stefan ram': 0.16; 'wrote:': 0.16; 'instead': 0.17;
'cc:addr:python.org': 0.20; 'language': 0.21; 'url-
ip:188.166.95.178/32': 0.25; 'url-ip:188.166.95/24': 0.25;
'url:listinfo': 0.25; 'cc:2**0': 0.25; 'url-ip:188.166/16': 0.25;
'stefan': 0.26; 'modify': 0.31; 'url-ip:188/8': 0.31; 'modified':
0.32; 'point,': 0.32; 'message-id:@mail.gmail.com': 0.32; 'but':
0.32; 'subject:for': 0.33; 'header:In-Reply-To:1': 0.34;
'received:google.com': 0.34; 'people': 0.36; 'received:209.85':
0.37; 'this.': 0.37; 'file': 0.38; 'received:209': 0.39; 'this,':
0.39; 'use': 0.39; 'helps': 0.60; 'skip:h 10': 0.61; 'true': 0.63;
'others,': 0.64; 'decided': 0.67; 'name,': 0.75; 'languages,':
0.76; 'converted': 0.84; 'inclined': 0.84; 'mood': 0.84; 'rob':
0.84
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=googlemail.com; s=20210112;
h=mime-version:in-reply-to:references:from:date:message-id:subject:to
:cc; bh=zCS7kerLy0wBRjsgMqDSl8PvDBLKrbha4Bb2Up992Fw=;
b=grbyfIbR1X9FGZTblCSLfxw8kgPKdT2ZMtSBgCuzMJ+Sc12bcMZwYsPSSOLlTNuxG2
PqXaq93w6Icvco0CYgvw/KAVpiloq3eAxMwtXqZR1DRpcp1tT+J0SOpamrnV7O4Hi/vc
R/efClob10d8Us38ddW6+ik5Z8CSwXc2ipcr+nzrcGFVWrxJEzfQZH2PzmP28x91N8W4
RDPnsZTOZhf+Qpawb827RiR+P1AYU4ovp+JqlqRzwuVErqyIFD13QgJBlApq8zPmfk24
7aaMTi1oVsoA1OOsjnWZnoYeuPyyGTNu0Mk5Ssr7WOClx26fAiZp2ip/cNcy+RXJTnVT
vGNA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:mime-version:in-reply-to:references:from:date
:message-id:subject:to:cc;
bh=zCS7kerLy0wBRjsgMqDSl8PvDBLKrbha4Bb2Up992Fw=;
b=r5Ust4ee7x3+RDc4wG6JY3Q1nXYEQe4B0XbqtTUcIPebfcnauLuqDT7gi/qBuZGNsu
3gU7eqssrWlv8jX6/EA5t/WDB9zBlNIxvYSwak7AuVz206L9ZV38BWfSq58GY7fWeMXI
Zo5vpiTQrwSQBNmjisA2aKfrpl8+tJXDQtPlcvL/szqY7rSBwWbmNhwP/6IRoSaP5adT
7YtyQNyozCn+sCw6zuT5goRc2gCBNwuXq4V1SsAlhuroxLd0b0qx/hNFBFecqbhA7KwL
at3awoOkC8CG3boEUCNV3C2T8fO6TdMBuzH22ADa8Xu4H2htpfmvsjCs43s6UQsBHTI6
s+DQ==
X-Gm-Message-State: AOAM532DnAFtmdrr105YZqq11ZEwO4R6uFEnKHd9ksfCp7wCIWfBLcnI
d66ndqLrDpuMikp5cPM0ThbeqHCSJyY67AUeQkneAEQz
X-Google-Smtp-Source: ABdhPJzc75xpT37i9Ag8rqqMNA6dx4pcaweYy5tLi2L6iRGAfw5d8PVGoYwpX6d+gVfDvLex8zrupZQN2bHF30trvsM=
X-Received: by 2002:a63:c49:0:b0:3aa:1ad6:2c9f with SMTP id
9-20020a630c49000000b003aa1ad62c9fmr8910277pgm.360.1650740951759; Sat, 23 Apr
2022 12:09:11 -0700 (PDT)
In-Reply-To: <imperative-20220423113313@ram.dialup.fu-berlin.de>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <CADJx9Ldo3ariS+jurcbGs64MdD4pu8nQ+QhXD5A+nF4gFcyr9A@mail.gmail.com>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me>
<YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<YmMz13q12bOvHl3y@scrozzle>
<mailman.204.1650670232.20749.python-list@python.org>
<imperative-20220423113313@ram.dialup.fu-berlin.de>
 by: jan - Sat, 23 Apr 2022 19:09 UTC

"return true iff this".

I like this.

jan

On 23/04/2022, Stefan Ram <ram@zedat.fu-berlin.de> wrote:
> Rob Cliffe <rob.cliffe@btinternet.com> writes:
>>I'm curious as to why so many people prefer "Return" to "Returns".
>
> The commands, er, names of functions, use the imperative mood
> ("print", not "prints"). So, "return" aligns with that mood
> as a paraphrase of such names.
>
> In Java, at one point, they decided to start to use the
> third person at one point and then half-heartedly converted
> all the documentation, as in
>
> |void println(boolean x)
> |Prints a boolean and then terminate the line.
>
> , where they modified "print" but did not bother do modify
> "terminate".
>
> And instead of "return true if this, false if not this",
> I might be inclined to write "return true iff this".
>
> BTW: As a language element that helps to construct a boolean
> expression from a file name, some languages, like SQL, use
> "EXISTS", while others, like MS-DOS-batch, use "EXIST".
>
>
> --
> https://mail.python.org/mailman/listinfo/python-list
>

Re: Style for docstring

<mailman.230.1650756210.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=18010&group=comp.lang.python#18010

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: PythonL...@DancesWithMice.info (dn)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sun, 24 Apr 2022 11:23:13 +1200
Organization: DWM
Lines: 105
Message-ID: <mailman.230.1650756210.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me>
<6e66877b-8965-bb9a-3c72-e4a82e73d77a@DancesWithMice.info>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de ZzBMZ9fYcF6MTkGgV7lsfgJT6AnxHw0oe+CYMN5fzQkQ==
Return-Path: <PythonList@DancesWithMice.info>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=danceswithmice.info header.i=@danceswithmice.info
header.b=Nt4oEtU7; dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.009
X-Spam-Evidence: '*H*': 0.98; '*S*': 0.00; '2022': 0.05; 'thread':
0.05; 'clarify': 0.07; 'pep': 0.07; 'python.': 0.08; '=dn': 0.09;
'angelico': 0.09; 'depend': 0.09; 'fact,': 0.09; 'forced': 0.09;
'from:addr:danceswithmice.info': 0.09; 'from:addr:pythonlist':
0.09; 'progress,': 0.09; 'readable': 0.09; 'situations': 0.09;
'05:56,': 0.16; 'be,': 0.16; 'by,': 0.16; 'computers': 0.16;
'descriptive': 0.16; 'determines': 0.16; 'done."': 0.16; 'message-
id:@DancesWithMice.info': 0.16; 'point)': 0.16; 'rationale': 0.16;
'recall': 0.16; 'received:51.254': 0.16; 'received:51.254.211':
0.16; 'received:51.254.211.219': 0.16; 'received:cloud': 0.16;
'received:rangi.cloud': 0.16; 'somewhat': 0.16; 'typing': 0.16;
'wider': 0.16; 'written.': 0.16; 'wrote:': 0.16; 'code.': 0.17;
"aren't": 0.19; 'to:addr:python-list': 0.20; 'language': 0.21;
"i've": 0.22; 'first,': 0.22; 'progress': 0.22; 'returns': 0.22;
'sat,': 0.22; "i'd": 0.24; '(and': 0.25; 'discussion': 0.25;
'stuff': 0.25; 'seems': 0.26; 'brought': 0.26; 'task': 0.26;
"wasn't": 0.26; 'function': 0.27; 'old': 0.27; 'done': 0.28;
'>>>': 0.28; 'chris': 0.28; 'etc': 0.28; 'thinking': 0.28;
'this?': 0.29; 'header:User-Agent:1': 0.30;
'header:Organization:1': 0.31; "doesn't": 0.32; 'but': 0.32;
"i'm": 0.33; 'subject:for': 0.33; 'there': 0.33; 'able': 0.34;
'work.': 0.34; 'header:In-Reply-To:1': 0.34; 'particularly': 0.35;
'preparing': 0.35; 'respect': 0.35; 'functions': 0.36; 'possibly':
0.36; 'room': 0.36; 'those': 0.36; "skip:' 10": 0.37; "it's":
0.37; 'author': 0.37; 'class': 0.37; 'others': 0.37;
'received:192.168': 0.37; 'could': 0.38; 'thanks': 0.38; 'two':
0.39; 'quite': 0.39; 'added': 0.39; 'use': 0.39; '(with': 0.39;
'still': 0.40; '(see': 0.40; 'want': 0.40; 'should': 0.40;
'michael': 0.60; 'best': 0.61; 'me.': 0.62; 'true': 0.63; 'copy':
0.63; 'once': 0.63; 'between': 0.63; 'authors': 0.64;
'definition': 0.64; 'finished': 0.64; 'opinion': 0.64; 'others,':
0.64; 'received:51': 0.64; 'upon': 0.64; 'let': 0.66;
'received:userid': 0.66; 'nearly': 0.67; 'stand': 0.67;
'accurately': 0.69; 'longer': 0.71; 'relevant': 0.73; 'tools':
0.74; 'name,': 0.75; 'short,': 0.76; 'discuss': 0.78; 'powerful':
0.84; 'publish': 0.84; 'assumptions,': 0.84; 'assurance': 0.84;
'became': 0.84; 'disagree': 0.84; 'distinction': 0.84;
'extracted': 0.84; 'intends': 0.84; 'realise': 0.84; 'thus,':
0.84; 'two.': 0.91; 'aspects': 0.93; 'storage': 0.95
DKIM-Filter: OpenDKIM Filter v2.11.0 vps.rangi.cloud 08047C9F2
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=danceswithmice.info;
s=staff; t=1650756209;
bh=yPis1eceZOZQBKpd2bwnogtnkkgGqEdz+s8HWmLXnS4=;
h=Date:Subject:To:References:From:In-Reply-To:From;
b=Nt4oEtU73LXKWUD+/wauLQ2iq2OISX5Oz3JWfugnwm2IhoyUWhGd/g6GaymKzgcNX
s7n+VO6trE8+MIz244CtSXbzst0y2iTCG3zI7kQRn7hPxiVdxrDxJjmCNzA2qc+XT8
A9Vh5n1uBiAGHb5VB0R+hXNXjPMzthNMjmBrqON0xvWoMo9LxnmBSaiVBXAHQV0W4i
UN9W4FCTKlJCN97qx20WNraCJHGlLdcbJ7HgKg0STSeQkSzvWukiiXcecnD8RLtamN
ZqLl9/s9OrtVr2SHKNJy9/qnAiWoSffnVwb17zLBH6C/dhnbeV+jHQUNqJ87Sy3Fss
TjCoZUYkz2lnw==
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on vps517507.ovh.net
X-Spam-Level:
X-Spam-Status: No, score=-4.9 required=5.0 tests=ALL_TRUSTED,BAYES_00,
DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,NICE_REPLY_A autolearn=ham
autolearn_force=no version=3.4.0
DKIM-Filter: OpenDKIM Filter v2.11.0 vps.rangi.cloud 0226BC9EE
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=danceswithmice.info;
s=staff; t=1650756207;
bh=yPis1eceZOZQBKpd2bwnogtnkkgGqEdz+s8HWmLXnS4=;
h=Date:Subject:To:References:From:In-Reply-To:From;
b=ZULGW7FNF4i1+pRsHzSvJPnP/BABf/dggBtONrASWbi+8+MJddwKIemOhIAiRXp/g
0o44ntLSwifEbghi1eg0yK7n+Ekl/brUqsELjlrOAYQG+iY8gPblTJQmP47Tb286VK
vPjZ7Q54f7/Of4lknquHbqgrHDQKNZb31chFL69tVOjO84ZWMaBaahEZPVKsoGxffC
g4QHr30DxEsUED/NqhMpk4wllOuURoOqO4jkKG4u+mDUMFfTuJWNF4ah4Xk8Ka0KSK
yoO+LWVQRDOHrDL6KdbzUDoVi0aRlTpBWiF4OP96ar4y3zL7/nWzSjAViLG65nHEfd
8ramzIxk4pCoQ==
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
Thunderbird/91.8.1
Content-Language: en-GB
In-Reply-To: <t3v3i3$32j$1@dont-email.me>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <6e66877b-8965-bb9a-3c72-e4a82e73d77a@DancesWithMice.info>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me>
 by: dn - Sat, 23 Apr 2022 23:23 UTC

On 23/04/2022 08.35, Michael F. Stemper wrote:
> On 22/04/2022 14.59, Chris Angelico wrote:
>> On Sat, 23 Apr 2022 at 05:56, Michael F. Stemper
>> <michael.stemper@gmail.com> wrote:
>>>
>>> I'm writing a function that is nearly self-documenting by its name,
>>> but still want to give it a docstring. Which of these would be
>>> best from a stylistic point of view:
>>>
>>>
>>>     Tells caller whether or not a permutation is even.
>>>
>>>     Determines if a permutation is even. (Alternative is that it's odd.)
>>>
>>>     Returns True if permutation is even, False if it is odd.
>
>
>>
>> I'd go with the third one, but "Return" rather than "Returns". Or
>> possibly "Test whether a permutation is even".
>
> "So let it be written. So let it be done."
>
>> That's just one opinion though, others may disagree :)
>
> Two for two. Thanks.

I've always taken the PEP somewhat for granted (with belated thanks and
respect to the authors and others who exerted effort (or would that be,
efforts?) to publish the finished work.

One of the things that I've taken-as-read, is WHY we use docstrings.
That rationale is wider than Python. Like many others, I just brought
that sort thinking with me.

Have you noticed that the PEP doesn't discuss this? It has taken this
thread to make me realise such.

The elephant in the style room is PEP-008. It's quite old in
'Python-years'! As time went by, PEP-257 became relevant - and I don't
recall which was 'chicken' and which 'egg', between the PEP and the
docutils/help/etc tools which depend upon a level of docstring
uniformity. No matter, together they represent a step of progress, after
PEP-008.

Since then we have added typing. Where once there was an extensive
documentation system to clarify the use of parameters and the definition
of return-values, now much of that can be done on the def-line (or
equivalent).

Another 'development' (I'd prefer 'natural progression') is that as
computers have become more powerful and storage cheaper, we have been
able to first justify, and now habitually, use longer identifier-names.
This step of progress should enable more descriptive and readable code.

So, we can consider that there are (now) three aspects which overlap,
considerably:

1 the name of the function
- descriptive and readable (see OP's assurance on this point)
2 typing
- description and distinction of parameters and return-values
3 docstring
- even more information about the function, how the author intends it be
used, embedded assumptions, etc

Thus, aren't there situations where a short, sharp, DRY, and SRP,
function; once well-named and accurately typed, could stand on its own
merits without a docstring. (yes, others will suck in their breath and
start preparing a bon-fire, at the utterance of such 'heresy'...)

We all hate 'boiler-plate', ie feeling forced to type stuff 'just
because', and particularly when it seems like duplication/repetition
(see recent thread(s) 'here' about __init__() and dataclasses). In fact,
one reason why we have functions is to reduce/remove (code) duplication!
So, why would we indulge in documental 'duplication' just-because we
should?must have a docstring?

While I'm tilting at windmills, wasn't option-2 the best?
(ooh, those flames are starting to warm my feet...)

Why? First, see other discussion about "imperatives".

My habit is to take the Statement of Requirements and copy it into a
brand-new __main__. As development proceeds, various details will be
extracted and copied into function and class docstrings. The language of
a specification should be imperative, ie you will *do* 'this'.

A second reason, is that the docstring should document the function,
which is subtly-different from describing the return-value (and that has
become a task for typing anyway).
(OK, the flames are getting-good, and it's time to break-out the
marsh-mallows and crumpets...)

So, 'nr2' describes what the function DOES!

PS would you mind passing-over the fire-extinguisher?
--
Regards,
=dn

Re: Style for docstring

<t43j32$tov$1@dont-email.me>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=18021&group=comp.lang.python#18021

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!eternal-september.org!reader02.eternal-september.org!.POSTED!not-for-mail
From: michael....@gmail.com (Michael F. Stemper)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sun, 24 Apr 2022 08:24:40 -0500
Organization: A noiseless patient Spider
Lines: 45
Message-ID: <t43j32$tov$1@dont-email.me>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<1761313929.296888.1650682685708@mail.yahoo.com>
<mailman.208.1650682689.20749.python-list@python.org>
<t40t3c$vb0$1@dont-email.me> <214129016.357437.1650735786870@mail.yahoo.com>
<mailman.211.1650735794.20749.python-list@python.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Injection-Date: Sun, 24 Apr 2022 13:24:50 -0000 (UTC)
Injection-Info: reader02.eternal-september.org; posting-host="0ebff8262ab8a07c8297d634a250bb48";
logging-data="30495"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX1/N25d6Y9nfF+vxrc9tA2Ys+A1F0CyOpdM="
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
Thunderbird/68.10.0
Cancel-Lock: sha1:egsS6qjX6Z0CxHK8d40jAk6IP5k=
In-Reply-To: <mailman.211.1650735794.20749.python-list@python.org>
Content-Language: en-US
 by: Michael F. Stemper - Sun, 24 Apr 2022 13:24 UTC

On 23/04/2022 12.43, Avi Gross wrote:
> Given what you added, Michael, your function is part of a larger collection of functions and being compatible with the others is a valid consideration. Whatever you decide, would ideally be done consistently with all or most of them.
> And, of course, it others in the collection also can handle multiple ways to specify a permutation, it may be simpler to have each call something like as.permutation() that handlesmultiple forms and converts to the one easiest for you to use.
> I am not sure that is needed as I suspect the simplest storage is something like a list:  [0,3,2,4,5,6,7,1,9,8] but could also be shown with each cycle as a sub-list or something like anumpy vector or a customized class.

Since you ask, I'm using dictionaries as the internal representation.
If you think about it, a python dictionary *is* a function from one
finite set to another, mathematically. And a (finite) permutation is
a bijection from a (finite) set to itself.

For convenience, the module provides two methods of defining a permutation
other than just entering a dictionary:

>>> import PermGroups as pg
>>> a = {'1':'2', '2':'1', '3':'3'}
>>> b = pg.ParsePerm( '(12)(3)' )
>>> c = pg.ParseDomImg( '123', '213' )
>>> a==b
True
>>> b==c
True
>>>

All of the other functions work on these dictionaries.

I had thought about defining a permutation object, but the conceptual
match between "dict" and "permutation" was too good to discard.

> Clearly if you control the package and how it is used, errors from bad data may not be a concern.

An invalidly-constructed permutation will cause an exception, so
the function won't return.

>>> d = {'1':'2', '2':'2', '3':'3'}
>>> pg.ValidateDict(d)
False
>>>

If I was to do it over, I would have named this function something
like IsValidPermutation(), hiding the internal representation as
well as making the function's Boolean nature explicit.

--
Michael F. Stemper
No animals were harmed in the composition of this message.

Re: Style for docstring

<t43lsr$jcb$1@dont-email.me>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=18022&group=comp.lang.python#18022

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!eternal-september.org!reader02.eternal-september.org!.POSTED!not-for-mail
From: michael....@gmail.com (Michael F. Stemper)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Sun, 24 Apr 2022 09:12:35 -0500
Organization: A noiseless patient Spider
Lines: 54
Message-ID: <t43lsr$jcb$1@dont-email.me>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<1761313929.296888.1650682685708@mail.yahoo.com>
<mailman.208.1650682689.20749.python-list@python.org>
<t40t3c$vb0$1@dont-email.me> <214129016.357437.1650735786870@mail.yahoo.com>
<mailman.211.1650735794.20749.python-list@python.org>
<t43j32$tov$1@dont-email.me>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit
Injection-Date: Sun, 24 Apr 2022 14:12:43 -0000 (UTC)
Injection-Info: reader02.eternal-september.org; posting-host="0ebff8262ab8a07c8297d634a250bb48";
logging-data="19851"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX182UbNxlh8uz0XuFCl9TpWMDC2mwtt8hBo="
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
Thunderbird/68.10.0
Cancel-Lock: sha1:3Z3WxHfFWWWHAUVjM6oDcErVSKg=
In-Reply-To: <t43j32$tov$1@dont-email.me>
Content-Language: en-US
 by: Michael F. Stemper - Sun, 24 Apr 2022 14:12 UTC

On 24/04/2022 08.24, Michael F. Stemper wrote:
> On 23/04/2022 12.43, Avi Gross wrote:
>> Given what you added, Michael, your function is part of a larger collection of functions and being compatible with the others is a valid consideration. Whatever you decide, would ideally be done consistently with all or most of them.
>> And, of course, it others in the collection also can handle multiple ways to specify a permutation, it may be simpler to have each call something like as.permutation() that handlesmultiple forms and converts to the one easiest for you to use.
>> I am not sure that is needed as I suspect the simplest storage is something like a list:  [0,3,2,4,5,6,7,1,9,8] but could also be shown with each cycle as a sub-list or something like anumpy vector or a customized class.
>
> Since you ask, I'm using dictionaries as the internal representation.
> If you think about it, a python dictionary *is* a function from one
> finite set to another, mathematically. And a (finite) permutation is
> a bijection from a (finite) set to itself.
>
> For convenience, the module provides two methods of defining a permutation
> other than just entering a dictionary:
>
>  >>> import PermGroups as pg
>  >>> a = {'1':'2', '2':'1', '3':'3'}
>  >>> b = pg.ParsePerm( '(12)(3)' )
>  >>> c = pg.ParseDomImg( '123', '213' )
>  >>> a==b
>  True
>  >>> b==c
>  True
>  >>>
>
> All of the other functions work on these dictionaries.
>
> I had thought about defining a permutation object, but the conceptual
> match between "dict" and "permutation" was too good to discard.
>
>> Clearly if you control the package and how it is used, errors from bad data may not be a concern.
>
> An invalidly-constructed permutation will cause an exception, so
> the function won't return.

The below was *not* intended to illustrate what I said above. It
shows the validation function provided by the module. This allows
the user to avoid the consequences of an invalidly-constructed
permutation. (It's only for users who don't subscribe to "EAFP",
of course.)

>  >>> d = {'1':'2', '2':'2', '3':'3'}
>  >>> pg.ValidateDict(d)
>  False
>  >>>
>
> If I was to do it over, I would have named this function something
> like IsValidPermutation(), hiding the internal representation as
> well as making the function's Boolean nature explicit.
>

--
Michael F. Stemper
Psalm 82:3-4

Re: Style for docstring

<mailman.246.1650829950.20749.python-list@python.org>

 copy mid

https://www.novabbs.com/devel/article-flat.php?id=18030&group=comp.lang.python#18030

 copy link   Newsgroups: comp.lang.python
Path: i2pn2.org!i2pn.org!news.swapon.de!fu-berlin.de!uni-berlin.de!not-for-mail
From: PythonL...@DancesWithMice.info (dn)
Newsgroups: comp.lang.python
Subject: Re: Style for docstring
Date: Mon, 25 Apr 2022 07:52:04 +1200
Organization: DWM
Lines: 85
Message-ID: <mailman.246.1650829950.20749.python-list@python.org>
References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<1761313929.296888.1650682685708@mail.yahoo.com>
<mailman.208.1650682689.20749.python-list@python.org>
<t40t3c$vb0$1@dont-email.me> <214129016.357437.1650735786870@mail.yahoo.com>
<mailman.211.1650735794.20749.python-list@python.org>
<t43j32$tov$1@dont-email.me>
<42c27e30-fa42-0740-f170-5970c7989cef@DancesWithMice.info>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-Trace: news.uni-berlin.de B/pLQnIaEvve8KizEyVKUgbtfjQ32FgoT0WyZydchuNA==
Return-Path: <PythonList@DancesWithMice.info>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
Authentication-Results: mail.python.org; dkim=pass
reason="2048-bit key; unprotected key"
header.d=danceswithmice.info header.i=@danceswithmice.info
header.b=JiSIJoFr; dkim-adsp=pass; dkim-atps=neutral
X-Spam-Status: OK 0.014
X-Spam-Evidence: '*H*': 0.97; '*S*': 0.00; 'entering': 0.05; 'class.':
0.07; '=dn': 0.09; 'from:addr:danceswithmice.info': 0.09;
'from:addr:pythonlist': 0.09; 'python"': 0.09; 'skip:[ 20': 0.09;
'url-ip:151.101.0.223/32': 0.09; 'url-ip:151.101.128.223/32':
0.09; 'url-ip:151.101.192.223/32': 0.09; 'url-
ip:151.101.64.223/32': 0.09; 'import': 0.15; 'another,': 0.16;
'approach.': 0.16; 'avi': 0.16; 'conceptual': 0.16; 'customized':
0.16; 'dict': 0.16; 'dicts': 0.16; 'easiest': 0.16; 'gross': 0.16;
'hints': 0.16; 'message-id:@DancesWithMice.info': 0.16; 'object,':
0.16; 'over,': 0.16; 'received:51.254': 0.16;
'received:51.254.211': 0.16; 'received:51.254.211.219': 0.16;
'received:cloud': 0.16; 'received:rangi.cloud': 0.16; 'specify':
0.16; 'static': 0.16; 'sub-classing': 0.16; 'trey': 0.16;
'url:peps': 0.16; 'vector': 0.16; 'wrote:': 0.16; 'python': 0.16;
'to:addr:python-list': 0.20; 'idea': 0.24; '(and': 0.25;
'discussion': 0.25; 'suspect': 0.26; 'function': 0.27; 'it,':
0.29; 'header:User-Agent:1': 0.30; 'module': 0.31;
'header:Organization:1': 0.31; 'think': 0.32; 'nature': 0.32;
'but': 0.32; "i'm": 0.33; "i'll": 0.33; 'subject:for': 0.33;
'package': 0.34; 'header:In-Reply-To:1': 0.34; 'url-
ip:151.101.130.217/32': 0.35; 'url-ip:151.101.194.217/32': 0.35;
'url-ip:151.101.2.217/32': 0.35; 'url-ip:151.101.66.217/32': 0.35;
'url:)': 0.35; 'yes,': 0.35; 'functions': 0.36; "skip:' 10": 0.37;
'using': 0.37; 'others': 0.37; 'received:192.168': 0.37; 'could':
0.38; 'two': 0.39; 'this,': 0.39; "we've": 0.39; 'valid': 0.39;
'methods': 0.39; 'advantage': 0.40; 'forms': 0.40; 'match': 0.40;
'something': 0.40; 'try': 0.40; 'michael': 0.60; 'url-
ip:104.21/16': 0.61; 'skip:h 10': 0.61; 'skip:i 20': 0.62;
'gives': 0.62; 'url-ip:151.101.0/24': 0.62; 'url-
ip:151.101.128/24': 0.62; 'url-ip:151.101.192/24': 0.62; 'url-
ip:151.101.64/24': 0.62; 'internal': 0.63; 'between': 0.63;
'received:51': 0.64; 'representing': 0.64; 'thus': 0.64; 'your':
0.64; 'upon': 0.64; 'well': 0.65; 'named': 0.65;
'received:userid': 0.66; 'bad': 0.67; 'live': 0.68; 'advantages':
0.69; 'and,': 0.69; 'url:to': 0.69; 'ability': 0.71; 'offer':
0.71; 'free': 0.72; 'aka': 0.84; 'ask,': 0.84; 'converts': 0.84;
'cycle': 0.84; 'ideally': 0.84; 'itself.': 0.84; 'michael,': 0.84;
'return.': 0.91
DKIM-Filter: OpenDKIM Filter v2.11.0 vps.rangi.cloud 1EE91CA10
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=danceswithmice.info;
s=staff; t=1650829948;
bh=IkZdWO8zRp/1oBXZnKOsUFpNJJCOSZEtpD0oVQvN/Zs=;
h=Date:Subject:To:References:From:In-Reply-To:From;
b=JiSIJoFrZBvlrvo4VXiIjSOKZVcUA+ZYUdEYCSwFag7ezmD4EiQZcd235Ao1MeqGb
j2DpPridKR8B0Bsl21hgPnX8VRKMCH67xZnqPzcp8XaW5CG9z5H0KbTDn7DZncoMaM
N8b1gNDjTb8fTyPlq8V1PGmYemOqx2wSr5drrBn9Frb0p34g08BWN2X8g+RS2JFqYn
242FF0SHaK+TQKpNfOFcm1SysfgRUnrcb6Y8Q3KzRYGnLidJLcQYqh1awD+AneJc8I
+CiFEQQpbkm/jIB7clwnnvmBb7QD6ZYHwq+n0/uOracgwvQQdKy10P4nSiEwKqAB01
d7otDYYBp8vMg==
X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on vps517507.ovh.net
X-Spam-Level:
X-Spam-Status: No, score=-4.9 required=5.0 tests=ALL_TRUSTED,BAYES_00,
DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,NICE_REPLY_A autolearn=ham
autolearn_force=no version=3.4.0
DKIM-Filter: OpenDKIM Filter v2.11.0 vps.rangi.cloud 1DAACA275
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=danceswithmice.info;
s=staff; t=1650829946;
bh=IkZdWO8zRp/1oBXZnKOsUFpNJJCOSZEtpD0oVQvN/Zs=;
h=Date:Subject:To:References:From:In-Reply-To:From;
b=Hp9J1qUamkkOcI0gmnplNr+BzxZB+7fDeomEysCoYAFw8kNShSjJg45gOwojwgJsD
YSZ3Dz3eHqvzrkW/yE1eI/9n8aUBvxIXx8ObawOaTQ5+s45178/shTZDHxLtMXLdE9
dQaLnHkSqWZa1KHu4avTlEFMSew+WL0Hu6hPSklu8U0IPP+M8ePUc91tlDams+BNbi
cNqsTLZgqYduaFUeIgKrCcDaHWcSnBGEvUduuUuZsXMa5r7PnBtegr78Foq7SFho9q
ZD1b9B91VQ2yHi4AJxYDRZ4ujakDDeIHldLpJlxInXDXWtg3tPmF3OQ1F+9NzKL2NC
Hgmec6d52WiOQ==
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
Thunderbird/91.8.1
Content-Language: en-GB
In-Reply-To: <t43j32$tov$1@dont-email.me>
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.39
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: <https://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>
X-Mailman-Original-Message-ID: <42c27e30-fa42-0740-f170-5970c7989cef@DancesWithMice.info>
X-Mailman-Original-References: <t3v042$8s1$1@dont-email.me>
<CAPTjJmpBWz5x-Au4=k1i4_V6WP39QhiorAGitBcLtf=bTEg8yg@mail.gmail.com>
<mailman.197.1650657557.20749.python-list@python.org>
<t3v3i3$32j$1@dont-email.me> <YmMqqecSN67EM3Dg@scrozzle>
<CAPTjJmr=5wVtbYcGLtnrXanTWd+p+tyWu+dCMK8+uQR8M--DUA@mail.gmail.com>
<1761313929.296888.1650682685708@mail.yahoo.com>
<mailman.208.1650682689.20749.python-list@python.org>
<t40t3c$vb0$1@dont-email.me> <214129016.357437.1650735786870@mail.yahoo.com>
<mailman.211.1650735794.20749.python-list@python.org>
<t43j32$tov$1@dont-email.me>
 by: dn - Sun, 24 Apr 2022 19:52 UTC

On 25/04/2022 01.24, Michael F. Stemper wrote:
> On 23/04/2022 12.43, Avi Gross wrote:
>> Given what you added, Michael, your function is part of a
>> larger collection of functions and being compatible with the others
>> is a valid consideration. Whatever you decide, would ideally be done
>> consistently with all or most of them.
>> And, of course, it others in the collection also can handle multiple
>> ways to specify a permutation, it may be simpler to have each call
>> something like as.permutation() that handlesmultiple forms and
>> converts to the one easiest for you to use.
>> I am not sure that is needed as I suspect the simplest storage is
>> something like a list:  [0,3,2,4,5,6,7,1,9,8] but could also be shown
>> with each cycle as a sub-list or something like anumpy vector or a
>> customized class.
>
> Since you ask, I'm using dictionaries as the internal representation.
> If you think about it, a python dictionary *is* a function from one
> finite set to another, mathematically. And a (finite) permutation is
> a bijection from a (finite) set to itself.
>
> For convenience, the module provides two methods of defining a permutation
> other than just entering a dictionary:
>
>  >>> import PermGroups as pg
>  >>> a = {'1':'2', '2':'1', '3':'3'}
>  >>> b = pg.ParsePerm( '(12)(3)' )
>  >>> c = pg.ParseDomImg( '123', '213' )
>  >>> a==b
>  True
>  >>> b==c
>  True
>  >>>
>
> All of the other functions work on these dictionaries.
>
> I had thought about defining a permutation object, but the conceptual
> match between "dict" and "permutation" was too good to discard.
>
>> Clearly if you control the package and how it is used, errors from bad
>> data may not be a concern.
>
> An invalidly-constructed permutation will cause an exception, so
> the function won't return.
>
>  >>> d = {'1':'2', '2':'2', '3':'3'}
>  >>> pg.ValidateDict(d)
>  False
>  >>>
>
> If I was to do it over, I would have named this function something
> like IsValidPermutation(), hiding the internal representation as
> well as making the function's Boolean nature explicit.

Yes, we live and learn!
(but 'technical debt'...)

Naming something based upon its implementation, eg ValidateDict(),
rather than its purpose, is a definite no-no - and while I'm
nit-picking, is that a function? (and thus validate_dict())

The idea of representing perms as dicts is good-thinking!

Please review UserDict
(https://docs.python.org/3/library/collections.html#collections.UserDict).
Sub-classing UserDict gives the advantages of a dict, without some of
the methods you don't want/need, and the ability to gather custom
permutation-methods into the class.

For a discussion about sub-classing dict or using UserDict, may I
recommend Trey Hunner's analysis, aka "there's no such thing as a free
lunch"
(https://treyhunner.com/2019/04/why-you-shouldnt-inherit-from-list-and-dict-in-python/)

Since then, we've been given (and I haven't had a reason to try it, yet)
"PEP 589 – TypedDict: Type Hints for Dictionaries with a Fixed Set of
Keys" which may offer an alternate approach. This comes with the
advantage of 'compile-time' static analysis/checking
(https://peps.python.org/pep-0589/). When I get around to experimenting
with this, I'll be referring to "TypedDict vs dataclasses in Python"
(https://dev.to/meeshkan/typeddict-vs-dataclasses-in-python-epic-typing-battle-onb)

--
Regards,
=dn

1
server_pubkey.txt

rocksolid light 0.9.7
clearnet tor