permutations: coverage to 100% and other changes

Misc changes other than docstring edits and test addition:

no testing in the _af_foo routines to allow them
to be as fast as possible (as private methods)

__invert__ uses duplicating _af_invert now

Permutations support the iter method so list(P)
will give P.array_form

error corrected in parity which used the _cyclic_form
which is now not inclusive of singletons

the code of runs was simplified and moved to iterables

the docstring of josephus was written to be less historical and more descriptive

random_permutation is renamed random since, being a classmethod, it will be addressed as Permutation.random (clearly indicating it is related to Permutation).

sympy/combinatorics/perm_groups.py

@@ -624,7 +624,7 @@ def base(self):
         `B = (b_1, b_2, ..., b_k)` such that no element of `G` apart from the
         identity fixes all the points in `B`. The concepts of a base and
         strong generating set and their applications are discussed in depth
-        in [1],pp.87-89 and [2],pp.55-57.
+        in [1], pp.87-89 and [2], pp.55-57.
 
         Examples
         ========
@@ -704,8 +704,8 @@ def baseswap(self, base, strong_gens, pos, randomized=False,\
         =====
 
         The deterministic version of the algorithm is discussed in
-        [1],pp.102-103; the randomized version is discussed in [1],p.103, and
-        [2],p.98. It is of Las Vegas type.
+        [1], pp.102-103; the randomized version is discussed in [1], p.103, and
+        [2], p.98. It is of Las Vegas type.
         Notice that [1] contains a mistake in the pseudocode and
         discussion of BASESWAP: on line 3 of the pseudocode,
         `|\beta_{i+1}^{\left\langle T\right\rangle}|` should be replaced by
@@ -784,7 +784,7 @@ def basic_orbits(self):
         If `(b_1, b_2, ..., b_k)` is a base for a group `G`, and
         `G^{(i)} = G_{b_1, b_2, ..., b_{i-1}}` is the `i`-th basic stabilizer
         (so that `G^{(1)} = G`), the `i`-th basic orbit relative to this base
-        is the orbit of `b_i` under `G^{(i)}`. See [1],pp.87-89 for more
+        is the orbit of `b_i` under `G^{(i)}`. See [1], pp.87-89 for more
         information.
 
         Examples
@@ -813,7 +813,7 @@ def basic_stabilizers(self):
 
         The `i`-th basic stabilizer `G^{(i)}` relative to a base
         `(b_1, b_2, ..., b_k)` is `G_{b_1, b_2, ..., b_{i-1}}`. For more
-        information, see [1],pp.87-89.
+        information, see [1], pp.87-89.
 
         Examples
         ========
@@ -853,7 +853,7 @@ def basic_transversals(self):
         The basic transversals are transversals of the basic orbits. They
         are provided as a list of dictionaries, each dictionary having
         keys - the elements of one of the basic orbits, and values - the
-        corresponding transversal elements. See [1],pp.87-89 for more
+        corresponding transversal elements. See [1], pp.87-89 for more
         information.
 
         Examples
@@ -1029,7 +1029,7 @@ def commutator(self, G, H):
         For a permutation group `K` and subgroups `G`, `H`, the
         commutator of `G` and `H` is defined as the group generated
         by all the commutators `[g, h] = hgh^{-1}g^{-1}` for `g` in `G` and
-        `h` in `H`. It is naturally a subgroup of `K` ([1],p.27).
+        `h` in `H`. It is naturally a subgroup of `K` ([1], p.27).
 
         Examples
         ========
@@ -1052,7 +1052,7 @@ def commutator(self, G, H):
 
         The commutator of two subgroups `H, G` is equal to the normal closure
         of the commutators of all the generators, i.e. `hgh^{-1}g^{-1}` for `h`
-        a generator of `H` and `g` a generator of `G` ([1],p.28)
+        a generator of `H` and `g` a generator of `G` ([1], p.28)
 
         """
         ggens = G.generators
@@ -1301,7 +1301,7 @@ def derived_subgroup(self):
         The derived subgroup, or commutator subgroup is the subgroup generated
         by all commutators `[g, h] = hgh^{-1}g^{-1}` for `g, h\in G` ; it is
         equal to the normal closure of the set of commutators of the generators
-        ([1],p.28, [11]).
+        ([1], p.28, [11]).
 
         Examples
         ========
@@ -1626,7 +1626,7 @@ def is_nilpotent(self):
         A group `G` is nilpotent if it has a central series of finite length.
         Alternatively, `G` is nilpotent if its lower central series terminates
         with the trivial group. Every nilpotent group is also solvable
-        ([1],p.29, [12]).
+        ([1], p.29, [12]).
 
         Examples
         ========
@@ -1883,7 +1883,7 @@ def lower_central_series(self):
         The lower central series for a group `G` is the series
         `G = G_0 > G_1 > G_2 > \ldots` where
         `G_k = [G, G_{k-1}]`, i.e. every term after the first is equal to the
-        commutator of `G` and the previous term in `G1` ([1],p.29).
+        commutator of `G` and the previous term in `G1` ([1], p.29).
 
         Returns
         =======
@@ -2044,11 +2044,11 @@ def normal_closure(self, other, k=10):
 
         If `S` is a subset of a group `G`, the normal closure of `A` in `G`
         is defined as the intersection of all normal subgroups of `G` that
-        contain `A` ([1],p.14). Alternatively, it is the group generated by
+        contain `A` ([1], p.14). Alternatively, it is the group generated by
         the conjugates `x^{-1}yx` for `x` a generator of `G` and `y` a
         generator of the subgroup `\left\langle S\right\rangle` generated by
         `S` (for some chosen generating set for `\left\langle S\right\rangle`)
-        ([1],p.73).
+        ([1], p.73).
 
         Parameters
         ==========
@@ -2078,7 +2078,7 @@ def normal_closure(self, other, k=10):
         Notes
         =====
 
-        The algorithm is described in [1],pp.73-74; it makes use of the
+        The algorithm is described in [1], pp.73-74; it makes use of the
         generation of random elements for permutation groups by the product
         replacement algorithm.
 
@@ -2626,7 +2626,7 @@ def schreier_sims_incremental(self, base=None, gens=None):
         as any sequence of points is a base for the trivial group. If the
         identity is present in the generators ``gens``, it is removed as
         it is a redundant generator.
-        The implementation is described in [1],pp.90-93.
+        The implementation is described in [1], pp.90-93.
 
         See Also
         ========
@@ -2769,7 +2769,7 @@ def schreier_sims_random(self, base=None, gens=None, consec_succ=10,\
         Notes
         =====
 
-        The algorithm is described in detail in [1],pp.97-98. It extends
+        The algorithm is described in detail in [1], pp.97-98. It extends
         the orbits ``orbs`` and the permutation groups ``stabs`` to
         basic orbits and basic stabilizers for the base and strong generating
         set produced in the end.
@@ -2988,7 +2988,7 @@ def strong_gens(self):
         stabilizer `G^{(i+1)} := G_{b_1, b_2, ..., b_i}` with `S` generates
         the pointwise stabilizer `G^{(i+1)}`. The concepts of a base and
         strong generating set and their applications are discussed in depth
-        in [1],pp.87-89 and [2],pp.55-57.
+        in [1], pp.87-89 and [2], pp.55-57.
 
         Examples
         ========
@@ -3068,7 +3068,7 @@ def subgroup_search(self, prop, base=None, strong_gens=None, tests=None,\
 
         This function is extremely lenghty and complicated and will require
         some careful attention. The implementation is described in
-        [1],pp.114-117, and the comments for the code here follow the lines
+        [1], pp.114-117, and the comments for the code here follow the lines
         of the pseudocode in the book for clarity.
         The complexity is exponential in general, since the search process by
         itself visits all members of the supergroup. However, there are a lot