Style for docstring

[Avi Gross]

Yes, Michael, a dictionary is an excellent way to represent a closed set of transitions which your permutations are.
You examples use numerals but obviously a dictionary will allow transformations of anything that can be hashed which mostly is items that are not mutable.
Of course for the purposes you may be using these permutations, accessing them may be done carefully as you need to have nothing else in the dictionary and must access all the keys and make sure you know which keys have already been visited from another item.
Some other data structures may work better or faster on smaller examples.
I think you have satisfied my curiosity and your main and only question really was on suggested wording of a Docstring.
Now if only the Docstring idea was replaced by a Dictionary too! Things like:
Dictstring = {"Purpose": "Text", "Args": "Text", "Return(s)": "Text", "Optional-Note": "Text", "French version": DocStringFrench}
Too late to seriously change the language now!

-----Original Message-----
From: Michael F. Stemper <michael.stemper at gmail.com>
To: python-list at python.org
Sent: Sun, Apr 24, 2022 9:24 am
Subject: Re: Style for docstring

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.
-- 
https://mail.python.org/mailman/listinfo/python-list