Style for docstring

[Avi Gross]

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 at gmail.com>
To: python-list at 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