| 2337 | ############################################# |
| 2338 | # Stopgaps |
| 2339 | ############################################# |
| 2340 | |
| 2341 | class StopgapWarning(Warning): |
| 2342 | """ |
| 2343 | This class is used to warn users of a known issue that may produce |
| 2344 | mathematically incorrect results. |
| 2345 | """ |
| 2346 | pass |
| 2347 | |
| 2348 | _stopgap_cache = {} |
| 2349 | |
| 2350 | def stopgap(message, ticket_no): |
| 2351 | r""" |
| 2352 | Issue a stopgap warning. |
| 2353 | |
| 2354 | INPUT: |
| 2355 | |
| 2356 | - ``message`` - an explanation of how an incorrect answer might be produced. |
| 2357 | |
| 2358 | - ``ticket_no`` - an integer, giving the number of the Trac ticket tracking the underlying issue. |
| 2359 | |
| 2360 | EXAMPLES:: |
| 2361 | |
| 2362 | sage: from sage.misc.misc import stopgap |
| 2363 | sage: sage.plot.plot.DOCTEST_MODE = False |
| 2364 | sage: stopgap("Computation of heights on elliptic curves over number fields can return very imprecise results.", 12509) |
| 2365 | doctest:...: StopgapWarning: Computation of heights on elliptic curves over number fields can return very imprecise results. |
| 2366 | This issue is being tracked at http://trac.sagemath.org/sage_trac/ticket/12509. |
| 2367 | sage: stopgap("This is not printed", 12509) |
| 2368 | sage: sage.plot.plot.DOCTEST_MODE = True |
| 2369 | """ |
| 2370 | from sage.plot.plot import DOCTEST_MODE |
| 2371 | if not (DOCTEST_MODE or _stopgap_cache.has_key(ticket_no)): |
| 2372 | # We reset show_warning so that the message is not printed twice. |
| 2373 | import warnings |
| 2374 | old_format = warnings.formatwarning |
| 2375 | def my_format(message, category, filename, lineno, line=None): |
| 2376 | return "%s:%s:\n%s\n%s\n%s\n" % (filename, lineno, "*"*80, message, "*"*80) |
| 2377 | warnings.formatwarning = my_format |
| 2378 | resetwarnings() |
| 2379 | message = message + "\nThis issue is being tracked at http://trac.sagemath.org/sage_trac/ticket/%s."%ticket_no |
| 2380 | warn(StopgapWarning(message), stacklevel=2) |
| 2381 | warnings.formatwarning = old_format |
| 2382 | _stopgap_cache[ticket_no] = True |