gh-40528: Minor refactor for hyperelliptic curve
    
As in the title. See the code for detail.

### 📝 Checklist

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

- [x] 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.
- [x] I have updated the documentation and checked the documentation
preview.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->
    
URL: #40528
Reported by: user202729
Reviewer(s): Michael Orlitzky, user202729

Author: Release Manager

src/sage/misc/superseded.py

@@ -350,15 +350,18 @@ class DeprecatedFunctionAlias:
     - Florent Hivert (2009-11-23), with the help of Mike Hansen.
     - Luca De Feo (2011-07-11), printing the full module path when different from old path
     """
-    def __init__(self, issue_number, func, module, instance=None, unbound=None):
+    def __init__(self, issue_number, func, module, instance=None, unbound=None, *, replacement=None, replacement_rst_doc=None):
         r"""
         TESTS::
 
+            sage: # needs sage.combinat
             sage: from sage.misc.superseded import deprecated_function_alias
-            sage: g = deprecated_function_alias(13109, number_of_partitions)            # needs sage.combinat
-            sage: from sage.misc.superseded import deprecated_function_alias
-            sage: g.__doc__                                                             # needs sage.combinat
+            sage: g = deprecated_function_alias(13109, number_of_partitions)
+            sage: g.__doc__
             'Deprecated: Use :func:`number_of_partitions` instead.\nSee :issue:`13109` for details.\n\n'
+            sage: g = deprecated_function_alias(13109, number_of_partitions, replacement_rst_doc='BLOB')
+            sage: g.__doc__
+            'Deprecated: Use BLOB instead.\nSee :issue:`13109` for details.\n\n'
         """
         _check_issue_number(issue_number)
         try:
@@ -369,14 +372,15 @@ def __init__(self, issue_number, func, module, instance=None, unbound=None):
         self.issue_number = issue_number
         self.instance = instance  # for use with methods
         self.unbound = unbound
+        self._replacement = replacement
         self.__module__ = module
-        if isinstance(func, type(deprecation)):
-            sphinxrole = "func"
-        else:
-            sphinxrole = "meth"
-        doc = 'Deprecated: '
-        doc += 'Use :' + sphinxrole + ':`' + self.func.__name__ + '` instead.\n'
-        doc += 'See :issue:`' + str(self.issue_number) + '` for details.\n\n'
+        if replacement_rst_doc is None:
+            if isinstance(func, type(deprecation)):
+                replacement_rst_doc = f":func:`{self.func.__name__}`"
+            else:
+                replacement_rst_doc = f":meth:`{self.func.__name__}`"
+        doc = f'Deprecated: Use {replacement_rst_doc} instead.\n'
+        doc += f'See :issue:`{self.issue_number}` for details.\n\n'
         self.__doc__ = doc
 
     @lazy_attribute
@@ -389,7 +393,6 @@ def __name__(self):
             sage: g.__name__                                                            # needs sage.combinat
             'g'
 
-            sage: from sage.misc.superseded import deprecated_function_alias
             sage: class cls():
             ....:    def new_meth(self): return 42
             ....:    old_meth = deprecated_function_alias(13109, new_meth)
@@ -444,15 +447,21 @@ def __call__(self, *args, **kwds):
             doctest:...: DeprecationWarning: blo is deprecated. Please use bla instead.
             See https://github.com/sagemath/sage/issues/13109 for details.
             42
+            sage: blo = deprecated_function_alias(13109, bla, replacement='BLOB')
+            sage: blo()
+            doctest:...: DeprecationWarning: blo is deprecated. Please use BLOB instead.
+            See https://github.com/sagemath/sage/issues/13109 for details.
+            42
         """
-        if self.instance is None and self.__module__ != self.func.__module__:
-            other = self.func.__module__ + "." + self.func.__name__
-        else:
-            other = self.func.__name__
+        replacement = self._replacement
+        if replacement is None:
+            if self.instance is None and self.__module__ != self.func.__module__:
+                replacement = self.func.__module__ + "." + self.func.__name__
+            else:
+                replacement = self.func.__name__
 
         deprecation(self.issue_number,
-                    "{} is deprecated. Please use {} instead.".format(
-                        self.__name__, other))
+                    f"{self.__name__} is deprecated. Please use {replacement} instead.")
         if self.instance is None:
             return self.func(*args, **kwds)
         else:
@@ -497,7 +506,7 @@ def __get__(self, inst, cls=None):
                                            unbound=self)
 
 
-def deprecated_function_alias(issue_number, func):
+def deprecated_function_alias(issue_number, func, *, replacement=None, replacement_rst_doc=None):
     """
     Create an aliased version of a function or a method which raises a
     deprecation warning message.
@@ -513,6 +522,15 @@ def deprecated_function_alias(issue_number, func):
 
     - ``func`` -- the function or method to be aliased
 
+    - ``replacement`` -- a plain text string to be inserted
+      into the warning message to describe the replacement.
+      If unspecified, use the name of ``func``.
+
+    - ``replacement_rst_doc`` -- a reStructuredText snippet to be inserted
+      into the user documentation to describe the replacement.
+      If unspecified, this is constructed from the name of ``func``,
+      with either the ``:meth:`` or the ``:func:`` role, as appropriate.
+
     EXAMPLES::
 
         sage: from sage.misc.superseded import deprecated_function_alias
@@ -554,4 +572,5 @@ def deprecated_function_alias(issue_number, func):
             module_name = inspect.getmodulename(frame1.f_code.co_filename)
     if module_name is None:
         module_name = '__main__'
-    return DeprecatedFunctionAlias(issue_number, func, module_name)
+    return DeprecatedFunctionAlias(issue_number, func, module_name,
+                                   replacement=replacement, replacement_rst_doc=replacement_rst_doc)

src/sage/schemes/hyperelliptic_curves/hyperelliptic_finite_field.py

@@ -57,6 +57,7 @@
 from sage.rings.power_series_ring import PowerSeriesRing
 from . import hyperelliptic_generic
 from sage.misc.cachefunc import cached_method
+from sage.misc.superseded import deprecated_function_alias
 from sage.matrix.constructor import identity_matrix, matrix
 from sage.misc.functional import rank
 from sage.misc.lazy_import import lazy_import
@@ -297,7 +298,7 @@ def frobenius_matrix(self, N=None, algorithm='hypellfrob'):
             ValueError: In the current implementation, p must be greater than (2g+1)(2N-1) = 81
         """
         if algorithm != 'hypellfrob':
-            raise ValueError("Unknown algorithm")
+            raise ValueError("unknown algorithm")
 
         # By default, use precision enough to be able to compute the
         # frobenius minimal polynomial
@@ -306,48 +307,41 @@ def frobenius_matrix(self, N=None, algorithm='hypellfrob'):
 
         return self.frobenius_matrix_hypellfrob(N=N)
 
-    def frobenius_polynomial_cardinalities(self, a=None):
+    def _frobenius_polynomial_cardinalities(self, a=None):
         r"""
-        Compute the charpoly of frobenius, as an element of `\ZZ[x]`,
-        by computing the number of points on the curve over `g` extensions
-        of the base field where `g` is the genus of the curve.
-
-        .. WARNING::
-
-            This is highly inefficient when the base field or the genus of the
-            curve are large.
+        Helper method for :meth:`frobenius_polynomial`.
 
         EXAMPLES::
 
             sage: R.<t> = PolynomialRing(GF(37))
             sage: H = HyperellipticCurve(t^5 + t + 2)
-            sage: H.frobenius_polynomial_cardinalities()
+            sage: H.frobenius_polynomial(algorithm='cardinalities')
             x^4 + x^3 - 52*x^2 + 37*x + 1369
 
         A quadratic twist::
 
             sage: H = HyperellipticCurve(2*t^5 + 2*t + 4)
-            sage: H.frobenius_polynomial_cardinalities()
+            sage: H.frobenius_polynomial(algorithm='cardinalities')
             x^4 - x^3 - 52*x^2 - 37*x + 1369
 
         Curve over a non-prime field::
 
             sage: K.<z> = GF(7**2)
             sage: R.<t> = PolynomialRing(K)
             sage: H = HyperellipticCurve(t^5 + z*t + z^2)
-            sage: H.frobenius_polynomial_cardinalities()
+            sage: H.frobenius_polynomial(algorithm='cardinalities')
             x^4 + 8*x^3 + 70*x^2 + 392*x + 2401
 
         This method may actually be useful when ``hypellfrob`` does not work::
 
             sage: K = GF(7)
             sage: R.<t> = PolynomialRing(K)
             sage: H = HyperellipticCurve(t^9 + t^3 + 1)
-            sage: H.frobenius_polynomial_matrix(algorithm='hypellfrob')
+            sage: H.frobenius_polynomial(algorithm='matrix')
             Traceback (most recent call last):
             ...
             ValueError: In the current implementation, p must be greater than (2g+1)(2N-1) = 81
-            sage: H.frobenius_polynomial_cardinalities()
+            sage: H.frobenius_polynomial(algorithm='cardinalities')
             x^8 - 5*x^7 + 7*x^6 + 36*x^5 - 180*x^4 + 252*x^3 + 343*x^2 - 1715*x + 2401
         """
         g = self.genus()
@@ -372,37 +366,33 @@ def frobenius_polynomial_cardinalities(self, a=None):
 
         return ZZ['x'](coeffs).reverse()
 
-    def frobenius_polynomial_matrix(self, M=None, algorithm='hypellfrob'):
+    def _frobenius_polynomial_matrix(self, M=None, algorithm='hypellfrob'):
         r"""
-        Compute the charpoly of frobenius, as an element of `\ZZ[x]`,
-        by computing the charpoly of the frobenius matrix.
-
-        This is currently only supported when the base field is prime
-        and large enough using the ``hypellfrob`` library.
+        Helper method for :meth:`frobenius_polynomial`.
 
         EXAMPLES::
 
             sage: R.<t> = PolynomialRing(GF(37))
             sage: H = HyperellipticCurve(t^5 + t + 2)
-            sage: H.frobenius_polynomial_matrix()
+            sage: H.frobenius_polynomial(algorithm='matrix')
             x^4 + x^3 - 52*x^2 + 37*x + 1369
 
         A quadratic twist::
 
             sage: H = HyperellipticCurve(2*t^5 + 2*t + 4)
-            sage: H.frobenius_polynomial_matrix()
+            sage: H.frobenius_polynomial(algorithm='matrix')
             x^4 - x^3 - 52*x^2 - 37*x + 1369
 
         Curves defined over larger prime fields::
 
             sage: K = GF(49999)
             sage: R.<t> = PolynomialRing(K)
             sage: H = HyperellipticCurve(t^9 + t^5 + 1)
-            sage: H.frobenius_polynomial_matrix()
+            sage: H.frobenius_polynomial(algorithm='matrix')
             x^8 + 281*x^7 + 55939*x^6 + 14144175*x^5 + 3156455369*x^4 + 707194605825*x^3
             + 139841906155939*x^2 + 35122892542149719*x + 6249500014999800001
             sage: H = HyperellipticCurve(t^15 + t^5 + 1)
-            sage: H.frobenius_polynomial_matrix()  # long time, 8s on a Corei7
+            sage: H.frobenius_polynomial(algorithm='matrix')  # long time, 8s on a Corei7
             x^14 - 76*x^13 + 220846*x^12 - 12984372*x^11 + 24374326657*x^10 - 1203243210304*x^9
             + 1770558798515792*x^8 - 74401511415210496*x^7 + 88526169366991084208*x^6
             - 3007987702642212810304*x^5 + 3046608028331197124223343*x^4
@@ -440,52 +430,51 @@ def frobenius_polynomial_matrix(self, M=None, algorithm='hypellfrob'):
 
         return ZZ['x'](f)
 
-    def frobenius_polynomial_pari(self):
+    def _frobenius_polynomial_pari(self):
         r"""
-        Compute the charpoly of frobenius, as an element of `\ZZ[x]`,
-        by calling the PARI function ``hyperellcharpoly``.
+        Helper method for :meth:`frobenius_polynomial`.
 
         EXAMPLES::
 
             sage: R.<t> = PolynomialRing(GF(37))
             sage: H = HyperellipticCurve(t^5 + t + 2)
-            sage: H.frobenius_polynomial_pari()
+            sage: H.frobenius_polynomial(algorithm='pari')
             x^4 + x^3 - 52*x^2 + 37*x + 1369
 
         A quadratic twist::
 
             sage: H = HyperellipticCurve(2*t^5 + 2*t + 4)
-            sage: H.frobenius_polynomial_pari()
+            sage: H.frobenius_polynomial(algorithm='pari')
             x^4 - x^3 - 52*x^2 - 37*x + 1369
 
         Slightly larger example::
 
             sage: K = GF(2003)
             sage: R.<t> = PolynomialRing(K)
             sage: H = HyperellipticCurve(t^7 + 487*t^5 + 9*t + 1)
-            sage: H.frobenius_polynomial_pari()
+            sage: H.frobenius_polynomial(algorithm='pari')
             x^6 - 14*x^5 + 1512*x^4 - 66290*x^3 + 3028536*x^2 - 56168126*x + 8036054027
 
         Curves defined over a non-prime field are supported as well::
 
             sage: K.<a> = GF(7^2)
             sage: R.<t> = PolynomialRing(K)
             sage: H = HyperellipticCurve(t^5 + a*t + 1)
-            sage: H.frobenius_polynomial_pari()
+            sage: H.frobenius_polynomial(algorithm='pari')
             x^4 + 4*x^3 + 84*x^2 + 196*x + 2401
 
             sage: K.<z> = GF(23**3)
             sage: R.<t> = PolynomialRing(K)
             sage: H = HyperellipticCurve(t^3 + z*t + 4)
-            sage: H.frobenius_polynomial_pari()
+            sage: H.frobenius_polynomial(algorithm='pari')
             x^2 - 15*x + 12167
 
         Over prime fields of odd characteristic, `h` may be nonzero::
 
             sage: K = GF(101)
             sage: R.<t> = PolynomialRing(K)
             sage: H = HyperellipticCurve(t^5 + 27*t + 3, t)
-            sage: H.frobenius_polynomial_pari()
+            sage: H.frobenius_polynomial(algorithm='pari')
             x^4 + 2*x^3 - 58*x^2 + 202*x + 10201
 
         TESTS:
@@ -495,17 +484,54 @@ def frobenius_polynomial_pari(self):
             sage: P.<x> = PolynomialRing(GF(3))
             sage: u = x^10 + x^9 + x^8 + x
             sage: C = HyperellipticCurve(u)
-            sage: C.frobenius_polynomial_pari()
+            sage: C.frobenius_polynomial(algorithm='pari')
             x^8 + 2*x^7 + 6*x^6 + 9*x^5 + 18*x^4 + 27*x^3 + 54*x^2 + 54*x + 81
         """
         f, h = self.hyperelliptic_polynomials()
         return ZZ['x'](pari([f, h]).hyperellcharpoly())
 
+    frobenius_polynomial_cardinalities = deprecated_function_alias(
+            40528, _frobenius_polynomial_cardinalities,
+            replacement='frobenius_polynomial(algorithm="cardinalities")',
+            replacement_rst_doc=':meth:`frobenius_polynomial(algorithm="cardinalities") <frobenius_polynomial>`')
+    frobenius_polynomial_matrix = deprecated_function_alias(
+            40528, _frobenius_polynomial_matrix,
+            replacement='frobenius_polynomial(algorithm="matrix")',
+            replacement_rst_doc=':meth:`frobenius_polynomial(algorithm="matrix") <frobenius_polynomial>`')
+    frobenius_polynomial_pari = deprecated_function_alias(
+            40528, _frobenius_polynomial_pari,
+            replacement='frobenius_polynomial(algorithm="pari")',
+            replacement_rst_doc=':meth:`frobenius_polynomial(algorithm="pari") <frobenius_polynomial>`')
+
     @cached_method
-    def frobenius_polynomial(self):
+    def frobenius_polynomial(self, algorithm=None, **kwargs):
         r"""
         Compute the charpoly of frobenius, as an element of `\ZZ[x]`.
 
+        INPUT:
+
+        - ``algorithm`` -- the algorithm to use, one of
+
+          - ``None`` (default) -- automatically select an algorithm.
+
+          - ``'pari'`` -- use the PARI function ``hyperellcharpoly``.
+
+          - ``'cardinalities'`` -- compute the number of points on the curve over `g`
+            extensions of the base field where `g` is the genus of the curve.
+
+            .. WARNING::
+
+                This is highly inefficient when the base field or the genus of the
+                curve are large.
+
+          - ``'matrix'`` -- compute the charpoly of the frobenius matrix.
+
+            This is currently only supported when the base field is prime
+            and large enough using the ``hypellfrob`` library.
+
+        - ``**kwargs`` -- additional keyword arguments passed to the
+          internal method. Undocumented feature, may be removed in the future.
+
         EXAMPLES::
 
             sage: R.<t> = PolynomialRing(GF(37))
@@ -578,6 +604,15 @@ def frobenius_polynomial(self):
             sage: C.frobenius_polynomial()
             x^8 + 2*x^7 + 6*x^6 + 9*x^5 + 18*x^4 + 27*x^3 + 54*x^2 + 54*x + 81
         """
+        if algorithm == "cardinalities":
+            return self._frobenius_polynomial_cardinalities(**kwargs)
+        elif algorithm == "matrix":
+            return self._frobenius_polynomial_matrix(**kwargs)
+        elif algorithm == "pari":
+            return self._frobenius_polynomial_pari(**kwargs)
+        elif algorithm is not None:
+            raise ValueError(f"unknown algorithm {algorithm}")
+
         K = self.base_ring()
         e = K.degree()
         q = K.cardinality()
@@ -588,11 +623,11 @@ def frobenius_polynomial(self):
         if (e == 1 and
             q >= (2*g+1)*(2*self._frobenius_coefficient_bound_charpoly()-1) and
             h == 0 and f.degree() % 2):
-            return self.frobenius_polynomial_matrix()
+            return self.frobenius_polynomial(algorithm='matrix')
         elif q % 2 == 1:
-            return self.frobenius_polynomial_pari()
+            return self.frobenius_polynomial(algorithm='pari')
         else:
-            return self.frobenius_polynomial_cardinalities()
+            return self.frobenius_polynomial(algorithm='cardinalities')
 
     def _points_fast_sqrt(self):
         """
@@ -1031,7 +1066,7 @@ def count_points_exhaustive(self, n=1, naive=False):
                 a.append(self.cardinality_exhaustive(extension_degree=i))
 
         # let's not be too naive and compute the frobenius polynomial
-        f = self.frobenius_polynomial_cardinalities(a=a)
+        f = self._frobenius_polynomial_cardinalities(a=a)
         return self.count_points_frobenius_polynomial(n=n, f=f)
 
     def count_points_hypellfrob(self, n=1, N=None, algorithm=None):
@@ -1116,7 +1151,7 @@ def count_points_hypellfrob(self, n=1, N=None, algorithm=None):
             M = self.frobenius_matrix(N=N, algorithm='hypellfrob')
             return self.count_points_matrix_traces(n=n,M=M,N=N)
         elif algorithm == 'charpoly':
-            f = self.frobenius_polynomial_matrix(algorithm='hypellfrob')
+            f = self._frobenius_polynomial_matrix(algorithm='hypellfrob')
             return self.count_points_frobenius_polynomial(n=n,f=f)
         else:
             raise ValueError("Unknown algorithm")