gh-40464: some details in binary quadratic forms / class groups
    
- using "indirect doctest"
- add some typing annotations
- remove unused imports
- break very long lines

### 📝 Checklist

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
    
URL: #40464
Reported by: Frédéric Chapoton
Reviewer(s): David Coudert

Author: Release Manager

src/sage/quadratic_forms/bqf_class_group.py

@@ -56,7 +56,8 @@
     sage: cl2 * cl2.order() == Cl.zero()
     True
     sage: Cl.abelian_group()
-    Additive abelian group isomorphic to Z/21 embedded in Form Class Group of Discriminant -431
+    Additive abelian group isomorphic to Z/21 embedded in
+    Form Class Group of Discriminant -431
     sage: Cl.gens()  # random
     [Class of 5*x^2 + 3*x*y + 22*y^2]
     sage: Cl.gens()[0].order()
@@ -86,11 +87,8 @@
 
 from sage.misc.prandom import randrange
 from sage.rings.integer_ring import ZZ
-from sage.rings.finite_rings.integer_mod_ring import Zmod
 from sage.rings.finite_rings.integer_mod import Mod
-from sage.rings.polynomial.polynomial_ring import polygen
 from sage.arith.misc import random_prime
-from sage.matrix.constructor import matrix
 from sage.groups.generic import order_from_multiple, multiple
 from sage.groups.additive_abelian.additive_abelian_wrapper import AdditiveAbelianGroupWrapper
 from sage.quadratic_forms.binary_qf import BinaryQF
@@ -124,7 +122,7 @@ class BQFClassGroup(Parent, UniqueRepresentation):
         Form Class Group of Discriminant -484
     """
 
-    def __init__(self, D, *, check=True):
+    def __init__(self, D, *, check=True) -> None:
         r"""
         Construct the class group for a given discriminant `D`.
 
@@ -159,7 +157,8 @@ def _element_constructor_(self, F, *, check=True):
             Class of 16*x^2 + 5*x*y + 16*y^2
         """
         if isinstance(F, BQFClassGroup_element):
-            if check and F.parent() is not self:  # class group is unique parent
+            if check and F.parent() is not self:
+                # class group is unique parent
                 raise ValueError('quadratic form has incorrect discriminant')
             return F
         if F == 0:
@@ -170,8 +169,10 @@ def _element_constructor_(self, F, *, check=True):
 
     def zero(self):
         r"""
-        Return the neutral element of this group, i.e., the class of the
-        principal binary quadratic form of the respective discriminant.
+        Return the neutral element of this group.
+
+        This is the class of the principal binary quadratic form of
+        the respective discriminant.
 
         EXAMPLES::
 
@@ -219,7 +220,7 @@ def random_element(self):
             b = -b
         return self(BinaryQF([a, b, c]))
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         r"""
         Return a hash value for this form class group.
 
@@ -230,7 +231,7 @@ def __hash__(self):
         """
         return hash(('BQFClassGroup', self._disc))
 
-    def _repr_(self):
+    def _repr_(self) -> str:
         r"""
         Return a string describing this form class group.
 
@@ -299,7 +300,8 @@ def abelian_group(self):
             sage: Cl.order()
             16
             sage: G = Cl.abelian_group(); G
-            Additive abelian group isomorphic to Z/4 + Z/2 + Z/2 embedded in Form Class Group of Discriminant -3108
+            Additive abelian group isomorphic to Z/4 + Z/2 + Z/2 embedded in
+            Form Class Group of Discriminant -3108
             sage: G.gens()  # random
             (Class of 11*x^2 + 4*x*y + 71*y^2,
              Class of 6*x^2 + 6*x*y + 131*y^2,
@@ -314,25 +316,25 @@ def abelian_group(self):
         gens = [BinaryQF(g) for g in gens]
         return AdditiveAbelianGroupWrapper(self, gens, ords)
 
-    def gens(self) -> list:
+    def gens(self) -> tuple:
         r"""
         Return a generating set of this form class group.
 
         EXAMPLES::
 
             sage: Cl = BQFClassGroup(-4*419)
             sage: Cl.gens()
-            [Class of 3*x^2 + 2*x*y + 140*y^2]
+            (Class of 3*x^2 + 2*x*y + 140*y^2,)
 
         ::
 
             sage: Cl = BQFClassGroup(-4*777)
             sage: Cl.gens()  # random
-            [Class of 11*x^2 + 4*x*y + 71*y^2,
+            (Class of 11*x^2 + 4*x*y + 71*y^2,
              Class of 6*x^2 + 6*x*y + 131*y^2,
-             Class of 2*x^2 + 2*x*y + 389*y^2]
+             Class of 2*x^2 + 2*x*y + 389*y^2)
         """
-        return [g.element() for g in self.abelian_group().gens()]
+        return tuple(g.element() for g in self.abelian_group().gens())
 
     def _coerce_map_from_(self, other):
         r"""
@@ -345,7 +347,7 @@ def _coerce_map_from_(self, other):
 
             sage: G = BQFClassGroup(-4*117117)
             sage: H = BQFClassGroup(-4*77)
-            sage: proj = G.hom(H); proj  # implicit doctest
+            sage: proj = G.hom(H); proj  # indirect doctest
             Coercion morphism:
               From: Form Class Group of Discriminant -468468
               To:   Form Class Group of Discriminant -308
@@ -376,19 +378,19 @@ class BQFClassGroup_element(AdditiveGroupElement):
     EXAMPLES::
 
         sage: F = BinaryQF([22, 91, 99])
-        sage: F.form_class()  # implicit doctest
+        sage: F.form_class()  # indirect doctest
         Class of 5*x^2 - 3*x*y + 22*y^2
 
     ::
 
         sage: Cl = BQFClassGroup(-4*419)
         sage: Cl.zero()
         Class of x^2 + 419*y^2
-        sage: Cl.gens()[0]  # implicit doctest
+        sage: Cl.gens()[0]  # indirect doctest
         Class of 3*x^2 + 2*x*y + 140*y^2
     """
 
-    def __init__(self, F, parent, *, check=True, reduce=True):
+    def __init__(self, F, parent, *, check=True, reduce=True) -> None:
         r"""
         Constructor for classes of binary quadratic forms.
 
@@ -515,7 +517,7 @@ def __mul__(self, other):
 
     __rmul__ = __mul__
 
-    def __eq__(self, other):
+    def __eq__(self, other) -> bool:
         r"""
         Test two form classes for equality.
 
@@ -535,7 +537,7 @@ def __eq__(self, other):
         # as well as hashing.
         return self._form == other._form
 
-    def __ne__(self, other):
+    def __ne__(self, other) -> bool:
         r"""
         Test two form classes for inequality.
 
@@ -551,7 +553,7 @@ def __ne__(self, other):
         """
         return self._form != other._form
 
-    def __lt__(self, other):
+    def __lt__(self, other) -> bool:
         r"""
         Compare two form classes according to the lexicographic ordering
         on their coefficient lists.
@@ -599,7 +601,7 @@ def is_zero(self) -> bool:
         """
         return not self
 
-    def __repr__(self) -> str:
+    def _repr_(self) -> str:
         r"""
         Return a string representation of this form class.
 
@@ -611,7 +613,7 @@ def __repr__(self) -> str:
         """
         return f'Class of {self._form}'
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         r"""
         Return a hash value for this form class.
 
@@ -698,7 +700,7 @@ class representative `[a,b,c]` satisfying `f^2 \mid a` and `f \mid b`
         sage: proj(elt) == proj2(proj1(elt))
         True
     """
-    def __init__(self, G, H):
+    def __init__(self, G, H) -> None:
         r"""
         Initialize this morphism between class groups of binary
         quadratic forms.