gh-36051: `sage.{topology,homology}`: Update # needs, modularization fixes
    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->

<!-- Why is this change required? What problem does it solve? -->
- Part of: #29705
- Cherry-picked from: #35095
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes #12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [ ] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #36051
Reported by: Matthias Köppe
Reviewer(s): David Coudert, Matthias Köppe

Author: Release Manager

src/sage/homology/algebraic_topological_model.py

@@ -1,4 +1,4 @@
-# sage.doctest: optional - sage.graphs
+# sage.doctest: needs sage.graphs
 r"""
 Algebraic topological model for a cell complex
 
@@ -101,8 +101,8 @@ def algebraic_topological_model(K, base_ring=None):
 
         sage: from sage.homology.algebraic_topological_model import algebraic_topological_model
         sage: RP2 = simplicial_complexes.RealProjectivePlane()
-        sage: phi, M = algebraic_topological_model(RP2, GF(2))                          # optional - sage.rings.finite_rings
-        sage: M.homology()                                                              # optional - sage.rings.finite_rings
+        sage: phi, M = algebraic_topological_model(RP2, GF(2))
+        sage: M.homology()
         {0: Vector space of dimension 1 over Finite Field of size 2,
          1: Vector space of dimension 1 over Finite Field of size 2,
          2: Vector space of dimension 1 over Finite Field of size 2}
@@ -372,8 +372,8 @@ def algebraic_topological_model_delta_complex(K, base_ring=None):
 
         sage: from sage.homology.algebraic_topological_model import algebraic_topological_model_delta_complex as AT_model
         sage: RP2 = simplicial_complexes.RealProjectivePlane()
-        sage: phi, M = AT_model(RP2, GF(2))                                             # optional - sage.rings.finite_rings
-        sage: M.homology()                                                              # optional - sage.rings.finite_rings
+        sage: phi, M = AT_model(RP2, GF(2))
+        sage: M.homology()
         {0: Vector space of dimension 1 over Finite Field of size 2,
          1: Vector space of dimension 1 over Finite Field of size 2,
          2: Vector space of dimension 1 over Finite Field of size 2}

src/sage/homology/chain_complex.py

@@ -85,7 +85,7 @@ def _latex_module(R, m):
         '\\Bold{Z}^{3}'
         sage: _latex_module(ZZ, 0)
         '0'
-        sage: _latex_module(GF(3), 1)                                                   # optional - sage.rings.finite_rings
+        sage: _latex_module(GF(3), 1)
         '\\Bold{F}_{3}^{1}'
     """
     if m == 0:
@@ -188,11 +188,11 @@ def ChainComplex(data=None, base_ring=None, grading_group=None,
         Chain complex with at most 2 nonzero terms over Integer Ring
 
         sage: m = matrix(ZZ, 2, 2, [0, 1, 0, 0])
-        sage: D = ChainComplex([m, m], base_ring=GF(2)); D                              # optional - sage.rings.finite_rings
+        sage: D = ChainComplex([m, m], base_ring=GF(2)); D
         Chain complex with at most 3 nonzero terms over Finite Field of size 2
-        sage: D == loads(dumps(D))                                                      # optional - sage.rings.finite_rings
+        sage: D == loads(dumps(D))
         True
-        sage: D.differential(0)==m, m.is_immutable(), D.differential(0).is_immutable()  # optional - sage.rings.finite_rings
+        sage: D.differential(0)==m, m.is_immutable(), D.differential(0).is_immutable()
         (True, False, True)
 
     Note that when a chain complex is defined in Sage, new
@@ -214,12 +214,12 @@ def ChainComplex(data=None, base_ring=None, grading_group=None,
 
         sage: ChainComplex([matrix(QQ, 3, 1), matrix(ZZ, 4, 3)])
         Chain complex with at most 3 nonzero terms over Rational Field
-        sage: ChainComplex([matrix(GF(125, 'a'), 3, 1), matrix(ZZ, 4, 3)])              # optional - sage.rings.finite_rings
+        sage: ChainComplex([matrix(GF(125, 'a'), 3, 1), matrix(ZZ, 4, 3)])              # needs sage.rings.finite_rings
         Chain complex with at most 3 nonzero terms over Finite Field in a of size 5^3
 
     If the matrices are defined over incompatible rings, an error results::
 
-        sage: ChainComplex([matrix(GF(125, 'a'), 3, 1), matrix(QQ, 4, 3)])              # optional - sage.rings.finite_rings
+        sage: ChainComplex([matrix(GF(125, 'a'), 3, 1), matrix(QQ, 4, 3)])              # needs sage.rings.finite_rings
         Traceback (most recent call last):
         ...
         TypeError: no common canonical parent for objects with parents:
@@ -228,7 +228,7 @@ def ChainComplex(data=None, base_ring=None, grading_group=None,
     If the base ring is given explicitly but is not compatible with
     the matrices, an error results::
 
-        sage: ChainComplex([matrix(GF(125, 'a'), 3, 1)], base_ring=QQ)                  # optional - sage.rings.finite_rings
+        sage: ChainComplex([matrix(GF(125, 'a'), 3, 1)], base_ring=QQ)                  # needs sage.rings.finite_rings
         Traceback (most recent call last):
         ...
         TypeError: unable to convert 0 to a rational
@@ -336,9 +336,9 @@ def __init__(self, parent, vectors, check=True):
 
         EXAMPLES::
 
-            sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])},           # optional - sage.rings.finite_rings
+            sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])},
             ....:                  base_ring=GF(7))
-            sage: C.category()                                                          # optional - sage.rings.finite_rings
+            sage: C.category()
             Category of chain complexes over Finite Field of size 7
 
         TESTS::
@@ -771,7 +771,7 @@ def rank(self, degree, ring=None):
             [2]
             sage: C.rank(0)
             1
-            sage: C.rank(0, ring=GF(2))                                                 # optional - sage.rings.finite_rings
+            sage: C.rank(0, ring=GF(2))
             0
         """
         degree = self.grading_group()(degree)
@@ -1079,12 +1079,12 @@ def __eq__(self, other):
 
         EXAMPLES::
 
-            sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])},           # optional - sage.rings.finite_rings
+            sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])},
             ....:                  base_ring=GF(2))
-            sage: D = ChainComplex({0: matrix(GF(2), 2, 3, [1, 0, 0, 0, 0, 0]),         # optional - sage.rings.finite_rings
+            sage: D = ChainComplex({0: matrix(GF(2), 2, 3, [1, 0, 0, 0, 0, 0]),
             ....:                   1: matrix(ZZ, 0, 2),
             ....:                   3: matrix(ZZ, 0, 0)})  # base_ring determined from the matrices
-            sage: C == D                                                                # optional - sage.rings.finite_rings
+            sage: C == D
             True
         """
         if not isinstance(other, ChainComplex_class) or self.base_ring() != other.base_ring():
@@ -1108,16 +1108,16 @@ def __ne__(self, other):
 
         EXAMPLES::
 
-            sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])},           # optional - sage.rings.finite_rings
+            sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])},
             ....:                  base_ring=GF(2))
-            sage: D = ChainComplex({0: matrix(GF(2), 2, 3, [1, 0, 0, 0, 0, 0]),         # optional - sage.rings.finite_rings
+            sage: D = ChainComplex({0: matrix(GF(2), 2, 3, [1, 0, 0, 0, 0, 0]),
             ....:                   1: matrix(ZZ, 0, 2),
             ....:                   3: matrix(ZZ, 0, 0)})  # base_ring determined from the matrices
-            sage: C != D                                                                # optional - sage.rings.finite_rings
+            sage: C != D
             False
             sage: E = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])},
             ....:                  base_ring=ZZ)
-            sage: C != E                                                                # optional - sage.rings.finite_rings
+            sage: C != E
             True
         """
         return not self == other
@@ -1143,15 +1143,15 @@ def _homology_chomp(self, deg, base_ring, verbose, generators):
 
         EXAMPLES::
 
-            sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])}, base_ring=GF(2))  # optional - sage.rings.finite_rings
-            sage: C._homology_chomp(None, GF(2), False, False)   # optional - CHomP             # optional - sage.rings.finite_rings
+            sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])}, base_ring=GF(2))
+            sage: C._homology_chomp(None, GF(2), False, False)  # optional - chomp, needs sage.rings.finite_rings
             doctest:...: DeprecationWarning: the CHomP interface is deprecated; hence so is this function
             See https://github.com/sagemath/sage/issues/33777 for details.
             {0: Vector space of dimension 2 over Finite Field of size 2, 1: Vector space of dimension 1 over Finite Field of size 2}
 
             sage: D = ChainComplex({0: matrix(ZZ,1,0,[]), 1: matrix(ZZ,1,1,[0]),
             ....:   2: matrix(ZZ,0,1,[])})
-            sage: D._homology_chomp(None, GF(2), False, False)   # optional - CHomP             # optional - sage.rings.finite_rings
+            sage: D._homology_chomp(None, GF(2), False, False)  # optional - chomp, needs sage.rings.finite_rings
             {1: Vector space of dimension 1 over Finite Field of size 2,
             2: Vector space of dimension 1 over Finite Field of size 2}
         """
@@ -1253,7 +1253,7 @@ def homology(self, deg=None, base_ring=None, generators=False,
             sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])})
             sage: C.homology()
             {0: Z x Z, 1: Z x C3}
-            sage: C.homology(deg=1, base_ring=GF(3))                                    # optional - sage.rings.finite_rings
+            sage: C.homology(deg=1, base_ring=GF(3))
             Vector space of dimension 2 over Finite Field of size 3
             sage: D = ChainComplex({0: identity_matrix(ZZ, 4), 4: identity_matrix(ZZ, 30)})
             sage: D.homology()
@@ -1280,9 +1280,9 @@ def homology(self, deg=None, base_ring=None, generators=False,
 
         From a torus using a field::
 
-            sage: T = simplicial_complexes.Torus()                                      # optional - sage.graphs
-            sage: C_t = T.chain_complex()                                               # optional - sage.graphs
-            sage: C_t.homology(base_ring=QQ, generators=True)                           # optional - sage.graphs
+            sage: T = simplicial_complexes.Torus()                                      # needs sage.graphs
+            sage: C_t = T.chain_complex()                                               # needs sage.graphs
+            sage: C_t.homology(base_ring=QQ, generators=True)                           # needs sage.graphs
             {0: [(Vector space of dimension 1 over Rational Field,
                Chain(0:(0, 0, 0, 0, 0, 0, 1)))],
              1: [(Vector space of dimension 1 over Rational Field,
@@ -1461,8 +1461,8 @@ def betti(self, deg=None, base_ring=None):
             sage: C.betti()
             {0: 2, 1: 1}
 
-            sage: D = ChainComplex({0: matrix(GF(5), [[3, 1],[1, 2]])})                 # optional - sage.rings.finite_rings
-            sage: D.betti()                                                             # optional - sage.rings.finite_rings
+            sage: D = ChainComplex({0: matrix(GF(5), [[3, 1],[1, 2]])})
+            sage: D.betti()
             {0: 1, 1: 1}
         """
         if base_ring is None:
@@ -1513,14 +1513,14 @@ def torsion_list(self, max_prime, min_prime=2):
             sage: C = ChainComplex({0: matrix(ZZ, 2, 3, [3, 0, 0, 0, 0, 0])})
             sage: C.homology()
             {0: Z x Z, 1: Z x C3}
-            sage: C.torsion_list(11)                                                    # optional - sage.rings.finite_rings
+            sage: C.torsion_list(11)                                                    # needs sage.rings.finite_rings
             [(3, [1])]
             sage: C = ChainComplex([matrix(ZZ, 1, 1, [2]), matrix(ZZ, 1, 1), matrix(1, 1, [3])])
             sage: C.homology(1)
             C2
             sage: C.homology(3)
             C3
-            sage: C.torsion_list(5)                                                     # optional - sage.rings.finite_rings
+            sage: C.torsion_list(5)                                                     # needs sage.rings.finite_rings
             [(2, [1]), (3, [3])]
         """
         if self.base_ring() != ZZ:
@@ -1563,11 +1563,12 @@ def _Hom_(self, other, category=None):
 
         EXAMPLES::
 
-            sage: S = simplicial_complexes.Sphere(2)                                    # optional - sage.graphs
-            sage: T = simplicial_complexes.Torus()                                      # optional - sage.graphs
-            sage: C = S.chain_complex(augmented=True, cochain=True)                     # optional - sage.graphs
-            sage: D = T.chain_complex(augmented=True, cochain=True)                     # optional - sage.graphs
-            sage: Hom(C, D)  # indirect doctest                                         # optional - sage.graphs
+            sage: # needs sage.graphs
+            sage: S = simplicial_complexes.Sphere(2)
+            sage: T = simplicial_complexes.Torus()
+            sage: C = S.chain_complex(augmented=True, cochain=True)
+            sage: D = T.chain_complex(augmented=True, cochain=True)
+            sage: Hom(C, D)  # indirect doctest
             Set of Morphisms from Chain complex with at most 4 nonzero terms over
             Integer Ring to Chain complex with at most 4 nonzero terms over Integer
             Ring in Category of chain complexes over Integer Ring
@@ -1629,33 +1630,35 @@ def shift(self, n=1):
 
         EXAMPLES::
 
-            sage: S1 = simplicial_complexes.Sphere(1).chain_complex()                   # optional - sage.graphs
-            sage: S1.shift(1).differential(2) == -S1.differential(1)                    # optional - sage.graphs
+            sage: # needs sage.graphs
+            sage: S1 = simplicial_complexes.Sphere(1).chain_complex()
+            sage: S1.shift(1).differential(2) == -S1.differential(1)
             True
-            sage: S1.shift(2).differential(3) == S1.differential(1)                     # optional - sage.graphs
+            sage: S1.shift(2).differential(3) == S1.differential(1)
             True
-            sage: S1.shift(3).homology(4)                                               # optional - sage.graphs
+            sage: S1.shift(3).homology(4)
             Z
 
         For cochain complexes, shifting goes in the other
         direction. Topologically, this makes sense if we grade the
         cochain complex for a space negatively::
 
-            sage: T = simplicial_complexes.Torus()                                      # optional - sage.graphs
-            sage: co_T = T.chain_complex()._flip_()                                     # optional - sage.graphs
-            sage: co_T.homology()                                                       # optional - sage.graphs
+            sage: # needs sage.graphs
+            sage: T = simplicial_complexes.Torus()
+            sage: co_T = T.chain_complex()._flip_()
+            sage: co_T.homology()
             {-2: Z, -1: Z x Z, 0: Z}
-            sage: co_T.degree_of_differential()                                         # optional - sage.graphs
+            sage: co_T.degree_of_differential()
             1
-            sage: co_T.shift(2).homology()                                              # optional - sage.graphs
+            sage: co_T.shift(2).homology()
             {-4: Z, -3: Z x Z, -2: Z}
 
         You can achieve the same result by tensoring (on the left, to
         get the signs right) with a rank one free module in degree
         ``-n * deg``, if ``deg`` is the degree of the differential::
 
             sage: C = ChainComplex({-2: matrix(ZZ, 0, 1)})
-            sage: C.tensor(co_T).homology()                                             # optional - sage.graphs
+            sage: C.tensor(co_T).homology()                                             # needs sage.graphs
             {-4: Z, -3: Z x Z, -2: Z}
         """
         deg = self.degree_of_differential()

src/sage/homology/chain_complex_homspace.py

@@ -1,4 +1,4 @@
-# sage.doctest: optional - sage.graphs          (because all doctests use SimplicialComplex)
+# sage.doctest: needs sage.graphs          (because all doctests use SimplicialComplex)
 r"""
 Homspaces between chain complexes