Style for docstring

[dn]

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