sagemathgh-41188: Refactor degree sequence functions
    
Refactor degree sequence generation to use generators, reducing memory
usage. Fix sagemath#41187

<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes sagemath#12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes sagemath#12345". -->



### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

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

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - sagemath#12345: short description why this is a dependency -->
<!-- - sagemath#34567: ... -->
    
URL: sagemath#41188
Reported by: Chenxin Zhong
Reviewer(s): Chenxin Zhong, Martin Rubey, Max Alekseyev, user202729

Author: Release Manager

src/sage/combinat/degree_sequences.pyx

@@ -21,17 +21,17 @@ With the object ``DegreeSequences(n)``, one can:
 
     sage: for seq in DegreeSequences(4):
     ....:     print(seq)
-    [0, 0, 0, 0]
-    [1, 1, 0, 0]
-    [2, 1, 1, 0]
-    [3, 1, 1, 1]
-    [1, 1, 1, 1]
-    [2, 2, 1, 1]
-    [2, 2, 2, 0]
-    [3, 2, 2, 1]
-    [2, 2, 2, 2]
-    [3, 3, 2, 2]
-    [3, 3, 3, 3]
+    (0, 0, 0, 0)
+    (1, 1, 0, 0)
+    (2, 1, 1, 0)
+    (3, 1, 1, 1)
+    (1, 1, 1, 1)
+    (2, 2, 1, 1)
+    (2, 2, 2, 0)
+    (3, 2, 2, 1)
+    (2, 2, 2, 2)
+    (3, 3, 2, 2)
+    (3, 3, 3, 3)
 
 .. NOTE::
 
@@ -253,15 +253,6 @@ Checking the consistency of enumeration and test::
     sage: DS = DegreeSequences(6)
     sage: all(seq in DS for seq in DS)
     True
-
-.. WARNING::
-
-    For the moment, iterating over all degree sequences involves building the
-    list of them first, then iterate on this list.  This is obviously bad,
-    as it requires uselessly a **lot** of memory for large values of `n`.
-
-    This should be changed. Updating the code does not require more
-    than a couple of minutes.
 """
 
 # ****************************************************************************
@@ -275,11 +266,9 @@ Checking the consistency of enumeration and test::
 # ****************************************************************************
 
 from cysignals.memory cimport check_calloc, sig_free
-from cysignals.signals cimport sig_on, sig_off
 
 
 cdef unsigned char * seq
-cdef list sequences
 
 
 class DegreeSequences:
@@ -334,13 +323,13 @@ class DegreeSequences:
         :issue:`21824`::
 
             sage: [d for d in DegreeSequences(0)]
-            [[]]
+            [()]
             sage: [d for d in DegreeSequences(1)]
-            [[0]]
+            [(0,)]
             sage: [d for d in DegreeSequences(3)]
-            [[0, 0, 0], [1, 1, 0], [2, 1, 1], [2, 2, 2]]
+            [(0, 0, 0), (1, 1, 0), (2, 1, 1), (2, 2, 2)]
             sage: [d for d in DegreeSequences(1)]
-            [[0]]
+            [(0,)]
         """
         cdef int n = self._n
         if len(seq) != n:
@@ -414,52 +403,54 @@ class DegreeSequences:
         sig_free(seq)
 
 
-cdef init(int n):
+cdef build_current_seq():
+    """
+    Build the degree sequence corresponding to the current state of the
+    algorithm.
+    """
+    global N
+    global seq
+
+    cdef list s = []
+    cdef int i, j
+
+    for N > i >= 0:
+        for 0 <= j < seq[i]:
+            s.append(i)
+
+    return tuple(s)
+
+
+def init(int n):
     """
     Initialize the memory and starts the enumeration algorithm.
+    
+    This is a generator that yields degree sequences one at a time.
     """
     global seq
     global N
-    global sequences
 
     if n == 0:
-        return [[]]
+        yield ()
+        return
     elif n == 1:
-        return [[0]]
+        yield (0,)
+        return
 
     seq = <unsigned char *>check_calloc(n + 1, sizeof(unsigned char))
 
     # We begin with one vertex of degree 0
     seq[0] = 1
 
     N = n
-    sequences = []
-    enum(1, 0)
-    sig_free(seq)
-    return sequences
-
-cdef inline add_seq():
-    """
-    This function is called whenever a sequence is found.
-
-    Build the degree sequence corresponding to the current state of the
-    algorithm and adds it to the sequences list.
-    """
-    global sequences
-    global N
-    global seq
-
-    cdef list s = []
-    cdef int i, j
-
-    for N > i >= 0:
-        for 0 <= j < seq[i]:
-            s.append(i)
-
-    sequences.append(s)
+    
+    try:
+        yield from enum(1, 0)
+    finally:
+        sig_free(seq)
 
 
-cdef void enum(int k, int M) noexcept:
+def enum(int k, int M):
     r"""
     Main function; for an explanation of the algorithm please refer to the
     :mod:`sage.combinat.degree_sequences` documentation.
@@ -468,6 +459,8 @@ cdef void enum(int k, int M) noexcept:
 
     - ``k`` -- depth of the partial degree sequence
     - ``M`` -- value of a maximum element in the partial degree sequence
+    
+    This is a generator that yields degree sequences.
     """
     cdef int i, j
     global seq
@@ -479,11 +472,9 @@ cdef void enum(int k, int M) noexcept:
 
     # Have we found a new degree sequence ? End of recursion !
     if k == N:
-        add_seq()
+        yield build_current_seq()
         return
 
-    sig_on()
-
     #############################################
     # Creating vertices of Vertices of degree M #
     #############################################
@@ -493,7 +484,7 @@ cdef void enum(int k, int M) noexcept:
     if M == 0:
 
         seq[0] += 1
-        enum(k + 1, M)
+        yield from enum(k + 1, M)
         seq[0] -= 1
 
     # We need not automatically increase the degree at each step. In this case,
@@ -504,7 +495,7 @@ cdef void enum(int k, int M) noexcept:
         seq[M] += M + 1
         seq[M - 1] -= M
 
-        enum(k + 1, M)
+        yield from enum(k + 1, M)
 
         seq[M] -= M + 1
         seq[M - 1] += M
@@ -550,7 +541,7 @@ cdef void enum(int k, int M) noexcept:
 
                 new_vertex = taken + i + j
                 seq[new_vertex] += 1
-                enum(k+1, new_vertex)
+                yield from enum(k+1, new_vertex)
                 seq[new_vertex] -= 1
 
                 seq[current_box-1] += j
@@ -574,7 +565,7 @@ cdef void enum(int k, int M) noexcept:
         seq[0] -= i
         seq[taken+i] += 1
 
-        enum(k+1, taken+i)
+        yield from enum(k+1, taken+i)
 
         seq[taken+i] -= 1
         seq[1] -= i
@@ -583,5 +574,3 @@ cdef void enum(int k, int M) noexcept:
     # Shift everything back to normal ! ( cell N is always equal to 0)
     for 1 <= i < N:
         seq[i] = seq[i+1]
-
-    sig_off()