Apply suggestions

Author: user202729

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,12 @@ 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
+
+    - ``replacement_rst_doc`` -- a restructuredText snippet to be inserted
+      into the user documentation to describe the replacement
+
     EXAMPLES::
 
         sage: from sage.misc.superseded import deprecated_function_alias
@@ -554,4 +569,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

@@ -309,14 +309,7 @@ def frobenius_matrix(self, N=None, algorithm='hypellfrob'):
 
     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::
 
@@ -375,11 +368,7 @@ def _frobenius_polynomial_cardinalities(self, a=None):
 
     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::
 
@@ -443,8 +432,7 @@ def _frobenius_polynomial_matrix(self, M=None, algorithm='hypellfrob'):
 
     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::
 
@@ -502,9 +490,18 @@ def _frobenius_polynomial_pari(self):
         f, h = self.hyperelliptic_polynomials()
         return ZZ['x'](pari([f, h]).hyperellcharpoly())
 
-    frobenius_polynomial_cardinalities = deprecated_function_alias(40528, _frobenius_polynomial_cardinalities)
-    frobenius_polynomial_matrix = deprecated_function_alias(40528, _frobenius_polynomial_matrix)
-    frobenius_polynomial_pari = deprecated_function_alias(40528, _frobenius_polynomial_pari)
+    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_matrix = deprecated_function_alias(
+            40528, _frobenius_polynomial_matrix,
+            replacement='frobenius_polynomial(algorithm="matrix")',
+            replacement_rst_doc=':meth:`frobenius_polynomial` ``(algorithm="matrix")`')
+    frobenius_polynomial_pari = deprecated_function_alias(
+            40528, _frobenius_polynomial_pari,
+            replacement='frobenius_polynomial(algorithm="pari")',
+            replacement_rst_doc=':meth:`frobenius_polynomial` ``(algorithm="pari")`')
 
     @cached_method
     def frobenius_polynomial(self, algorithm=None, **kwargs):
@@ -513,15 +510,27 @@ def frobenius_polynomial(self, algorithm=None, **kwargs):
 
         INPUT:
 
-        - ``algorithm`` -- (default: ``None``) the algorithm to use, one of
-          ``'cardinalities'``, ``'matrix'``, or ``'pari'``.
+        - ``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.
 
-          Refer to :meth:`frobenius_polynomial_cardinalities`,
-          :meth:`frobenius_polynomial_matrix`, and
-          :meth:`frobenius_polynomial_pari` respectively.
+            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
-          methods above. Undocumented feature, may be removed in the future.
+          internal method. Undocumented feature, may be removed in the future.
 
         EXAMPLES::
 

src/sage/schemes/hyperelliptic_curves/jacobian_generic.py

@@ -422,6 +422,8 @@ def cardinality(self):
         Return the cardinality of the Jacobian.
         Use the formula in `<https://math.stackexchange.com/a/2190894>`_.
 
+        Currently only implemented over finite fields.
+
         EXAMPLES::
 
             sage: R.<x> = GF(3663031)[]