Ticket #12691: 12691.patch

sage/misc/misc.py

@@ -2334 +2334 @@
         globs[name] = sage_wraps(func)(partial(wrapper, func, name))
     del name
 
+#############################################
+# Stopgaps
+#############################################
+
+class StopgapWarning(Warning):
+    """
+    This class is used to warn users of a known issue that may produce
+    mathematically incorrect results.
+    """
+    pass
+
+_stopgap_cache = {}
+
+def stopgap(message, ticket_no):
+    r"""
+    Issue a stopgap warning.
+
+    INPUT:
+
+     - ``message`` - an explanation of how an incorrect answer might be produced.
+
+     - ``ticket_no`` - an integer, giving the number of the Trac ticket tracking the underlying issue.
+
+    EXAMPLES::
+
+        sage: from sage.misc.misc import stopgap
+        sage: sage.plot.plot.DOCTEST_MODE = False
+        sage: stopgap("Computation of heights on elliptic curves over number fields can return very imprecise results.", 12509)
+        doctest:...: StopgapWarning: Computation of heights on elliptic curves over number fields can return very imprecise results.
+        This issue is being tracked at http://trac.sagemath.org/sage_trac/ticket/12509.
+        sage: stopgap("This is not printed", 12509)
+        sage: sage.plot.plot.DOCTEST_MODE = True
+    """
+    from sage.plot.plot import DOCTEST_MODE
+    if not (DOCTEST_MODE or _stopgap_cache.has_key(ticket_no)):
+        # We reset show_warning so that the message is not printed twice.
+        import warnings
+        old_format = warnings.formatwarning
+        def my_format(message, category, filename, lineno, line=None):
+            return "%s:%s:\n%s\n%s\n%s\n" % (filename, lineno, "*"*80, message, "*"*80)
+        warnings.formatwarning = my_format
+        resetwarnings()
+        message = message + "\nThis issue is being tracked at http://trac.sagemath.org/sage_trac/ticket/%s."%ticket_no
+        warn(StopgapWarning(message), stacklevel=2)
+        warnings.formatwarning = old_format
+        _stopgap_cache[ticket_no] = True
 
 #############################################
 # Operators