Style for docstring

[Michael F. Stemper]

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.