187 lines
7.0 KiB
Python
187 lines
7.0 KiB
Python
"""
|
|
General SymPy exceptions and warnings.
|
|
"""
|
|
|
|
import warnings
|
|
|
|
from sympy.utilities.misc import filldedent
|
|
|
|
|
|
class SymPyDeprecationWarning(DeprecationWarning):
|
|
r"""A warning for deprecated features of SymPy.
|
|
|
|
This class is expected to be used with the warnings.warn function (note
|
|
that one has to explicitly turn on deprecation warnings):
|
|
|
|
>>> import warnings
|
|
>>> from sympy.utilities.exceptions import SymPyDeprecationWarning
|
|
>>> warnings.simplefilter(
|
|
... "always", SymPyDeprecationWarning)
|
|
>>> warnings.warn(
|
|
... SymPyDeprecationWarning(feature="Old deprecated thing",
|
|
... issue=1065, deprecated_since_version="1.0")) #doctest:+SKIP
|
|
__main__:3: SymPyDeprecationWarning:
|
|
|
|
Old deprecated thing has been deprecated since SymPy 1.0. See
|
|
https://github.com/sympy/sympy/issues/1065 for more info.
|
|
|
|
>>> SymPyDeprecationWarning(feature="Old deprecated thing",
|
|
... issue=1065, deprecated_since_version="1.1").warn() #doctest:+SKIP
|
|
__main__:1: SymPyDeprecationWarning:
|
|
|
|
Old deprecated thing has been deprecated since SymPy 1.1.
|
|
See https://github.com/sympy/sympy/issues/1065 for more info.
|
|
|
|
Three arguments to this class are required: ``feature``, ``issue`` and
|
|
``deprecated_since_version``.
|
|
|
|
The ``issue`` flag should be an integer referencing for a "Deprecation
|
|
Removal" issue in the SymPy issue tracker. See
|
|
https://github.com/sympy/sympy/wiki/Deprecating-policy.
|
|
|
|
>>> SymPyDeprecationWarning(
|
|
... feature="Old feature",
|
|
... useinstead="new feature",
|
|
... issue=5241,
|
|
... deprecated_since_version="1.1")
|
|
Old feature has been deprecated since SymPy 1.1. Use new feature
|
|
instead. See https://github.com/sympy/sympy/issues/5241 for more info.
|
|
|
|
Every formal deprecation should have an associated issue in the GitHub
|
|
issue tracker. All such issues should have the DeprecationRemoval
|
|
tag.
|
|
|
|
Additionally, each formal deprecation should mark the first release for
|
|
which it was deprecated. Use the ``deprecated_since_version`` flag for
|
|
this.
|
|
|
|
>>> SymPyDeprecationWarning(
|
|
... feature="Old feature",
|
|
... useinstead="new feature",
|
|
... deprecated_since_version="0.7.2",
|
|
... issue=1065)
|
|
Old feature has been deprecated since SymPy 0.7.2. Use new feature
|
|
instead. See https://github.com/sympy/sympy/issues/1065 for more info.
|
|
|
|
To provide additional information, create an instance of this
|
|
class in this way:
|
|
|
|
>>> SymPyDeprecationWarning(
|
|
... feature="Such and such",
|
|
... last_supported_version="1.2.3",
|
|
... useinstead="this other feature",
|
|
... issue=1065,
|
|
... deprecated_since_version="1.1")
|
|
Such and such has been deprecated since SymPy 1.1. It will be last
|
|
supported in SymPy version 1.2.3. Use this other feature instead. See
|
|
https://github.com/sympy/sympy/issues/1065 for more info.
|
|
|
|
Note that the text in ``feature`` begins a sentence, so if it begins with
|
|
a plain English word, the first letter of that word should be capitalized.
|
|
|
|
Either (or both) of the arguments ``last_supported_version`` and
|
|
``useinstead`` can be omitted. In this case the corresponding sentence
|
|
will not be shown:
|
|
|
|
>>> SymPyDeprecationWarning(feature="Such and such",
|
|
... useinstead="this other feature", issue=1065,
|
|
... deprecated_since_version="1.1")
|
|
Such and such has been deprecated since SymPy 1.1. Use this other
|
|
feature instead. See https://github.com/sympy/sympy/issues/1065 for
|
|
more info.
|
|
|
|
You can still provide the argument value. If it is a string, it
|
|
will be appended to the end of the message:
|
|
|
|
>>> SymPyDeprecationWarning(
|
|
... feature="Such and such",
|
|
... useinstead="this other feature",
|
|
... value="Contact the developers for further information.",
|
|
... issue=1065,
|
|
... deprecated_since_version="1.1")
|
|
Such and such has been deprecated since SymPy 1.1. Use this other
|
|
feature instead. See https://github.com/sympy/sympy/issues/1065 for
|
|
more info. Contact the developers for further information.
|
|
|
|
If, however, the argument value does not hold a string, a string
|
|
representation of the object will be appended to the message:
|
|
|
|
>>> SymPyDeprecationWarning(
|
|
... feature="Such and such",
|
|
... useinstead="this other feature",
|
|
... value=[1,2,3],
|
|
... issue=1065,
|
|
... deprecated_since_version="1.1")
|
|
Such and such has been deprecated since SymPy 1.1. Use this other
|
|
feature instead. See https://github.com/sympy/sympy/issues/1065 for
|
|
more info. ([1, 2, 3])
|
|
|
|
Note that it may be necessary to go back through all the deprecations
|
|
before a release to make sure that the version number is correct. So just
|
|
use what you believe will be the next release number (this usually means
|
|
bumping the minor number by one).
|
|
|
|
To mark a function as deprecated, you can use the decorator
|
|
@deprecated.
|
|
|
|
See Also
|
|
========
|
|
sympy.core.decorators.deprecated
|
|
|
|
"""
|
|
|
|
def __init__(self, value=None, feature=None, last_supported_version=None,
|
|
useinstead=None, issue=None, deprecated_since_version=None):
|
|
|
|
self.args = (value, feature, last_supported_version, useinstead,
|
|
issue, deprecated_since_version)
|
|
|
|
self.fullMessage = ""
|
|
|
|
if not feature:
|
|
raise ValueError("feature is required argument of SymPyDeprecationWarning")
|
|
|
|
if not deprecated_since_version:
|
|
raise ValueError("deprecated_since_version is a required argument of SymPyDeprecationWarning")
|
|
|
|
self.fullMessage = "%s has been deprecated since SymPy %s. " % \
|
|
(feature, deprecated_since_version)
|
|
|
|
if last_supported_version:
|
|
self.fullMessage += ("It will be last supported in SymPy "
|
|
"version %s. ") % last_supported_version
|
|
if useinstead:
|
|
self.fullMessage += "Use %s instead. " % useinstead
|
|
|
|
if not issue:
|
|
raise ValueError("""\
|
|
The issue argument of SymPyDeprecationWarning is required.
|
|
This should be a separate issue with the "Deprecation Removal" label. See
|
|
https://github.com/sympy/sympy/wiki/Deprecating-policy.\
|
|
""")
|
|
|
|
self.fullMessage += ("See "
|
|
"https://github.com/sympy/sympy/issues/%d for more "
|
|
"info. ") % issue
|
|
|
|
if value:
|
|
if not isinstance(value, str):
|
|
value = "(%s)" % repr(value)
|
|
value = " " + value
|
|
else:
|
|
value = ""
|
|
|
|
self.fullMessage += value
|
|
|
|
def __str__(self):
|
|
return '\n%s\n' % filldedent(self.fullMessage)
|
|
|
|
def warn(self, stacklevel=2):
|
|
# the next line is what the user would see after the error is printed
|
|
# if stacklevel was set to 1. If you are writing a wrapper around this,
|
|
# increase the stacklevel accordingly.
|
|
warnings.warn(self, stacklevel=stacklevel)
|
|
|
|
# Python by default hides DeprecationWarnings, which we do not want.
|
|
warnings.simplefilter("once", SymPyDeprecationWarning)
|