Style for docstring

[Michael F. Stemper]

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