Exceptions and Warnings#

General SymPy exceptions and warnings.

exception sympy.utilities.exceptions.SymPyDeprecationWarning(message, *, deprecated_since_version, active_deprecations_target)[源代码]#

A warning for deprecated features of SymPy.

See the Deprecation Policy document for details on when and how things should be deprecated in SymPy.

Note that simply constructing this class will not cause a warning to be issued. To do that, you must call the :func`sympy_deprecation_warning` function. For this reason, it is not recommended to ever construct this class directly.

解释

The SymPyDeprecationWarning class is a subclass of DeprecationWarning that is used for all deprecations in SymPy. A special subclass is used so that we can automatically augment the warning message with additional metadata about the version the deprecation was introduced in and a link to the documentation. This also allows users to explicitly filter deprecation warnings from SymPy using warnings filters (see Silencing SymPy Deprecation Warnings).

Additionally, SymPyDeprecationWarning is enabled to be shown by default, unlike normal DeprecationWarnings, which are only shown by default in interactive sessions. This ensures that deprecation warnings in SymPy will actually be seen by users.

See the documentation of sympy_deprecation_warning() for a description of the parameters to this function.

To mark a function as deprecated, you can use the @deprecated decorator.

参见

sympy.utilities.exceptions.sympy_deprecation_warning, sympy.utilities.exceptions.ignore_warnings, sympy.utilities.decorator.deprecated, sympy.testing.pytest.warns_deprecated_sympy

sympy.utilities.exceptions.ignore_warnings(warningcls)[源代码]#

上下文管理器在测试期间禁止警告。

备注

Do not use this with SymPyDeprecationWarning in the tests. warns_deprecated_sympy() should be used instead.

此函数用于在测试期间抑制警告。应该使用warns函数来断言发出了警告。在无法保证发出警告（例如导入模块时）或警告来自第三方代码时，ignore_warnings功能非常有用。

This function is also useful to prevent the same or similar warnings from being issue twice due to recursive calls.

当警告（可靠地）来自SymPy时，警告功能应优先于忽略_警告。

>>> from sympy.utilities.exceptions import ignore_warnings
>>> import warnings

这里有个警告：

>>> with warnings.catch_warnings():  # reset warnings in doctest
...     warnings.simplefilter('error')
...     warnings.warn('deprecated', UserWarning)
Traceback (most recent call last):
  ...
UserWarning: deprecated

我们用ignore_警告来抑制它：

>>> with warnings.catch_warnings():  # reset warnings in doctest
...     warnings.simplefilter('error')
...     with ignore_warnings(UserWarning):
...         warnings.warn('deprecated', UserWarning)

（未发出警告）

参见

sympy.utilities.exceptions.SymPyDeprecationWarning, sympy.utilities.exceptions.sympy_deprecation_warning, sympy.utilities.decorator.deprecated, sympy.testing.pytest.warns_deprecated_sympy

sympy.utilities.exceptions.sympy_deprecation_warning(message, *, deprecated_since_version, active_deprecations_target, stacklevel=3)[源代码]#

Warn that a feature is deprecated in SymPy.

See the Deprecation Policy document for details on when and how things should be deprecated in SymPy.

To mark an entire function or class as deprecated, you can use the @deprecated decorator.

参数:

message : str

The deprecation message. This may span multiple lines and contain code examples. Messages should be wrapped to 80 characters. The message is automatically dedented and leading and trailing whitespace stripped. Messages may include dynamic content based on the user input, but avoid using str(expression) if an expression can be arbitrary, as it might be huge and make the warning message unreadable.

deprecated_since_version : str

The version of SymPy the feature has been deprecated since. For new deprecations, this should be the version in sympy/release.py without the .dev. If the next SymPy version ends up being different from this, the release manager will need to update any SymPyDeprecationWarnings using the incorrect version. This argument is required and must be passed as a keyword argument. (example: deprecated_since_version="1.10").

active_deprecations_target : str

The Sphinx target corresponding to the section for the deprecation in the List of active deprecations document (see doc/src/explanation/active-deprecations.md). This is used to automatically generate a URL to the page in the warning message. This argument is required and must be passed as a keyword argument. (example: active_deprecations_target="deprecated-feature-abc")

stacklevel : int, default: 3

The stacklevel parameter that is passed to warnings.warn. If you create a wrapper that calls this function, this should be increased so that the warning message shows the user line of code that produced the warning. Note that in some cases there will be multiple possible different user code paths that could result in the warning. In that case, just choose the smallest common stacklevel.

实例

>>> from sympy.utilities.exceptions import sympy_deprecation_warning
>>> def is_this_zero(x, y=0):
...     """
...     Determine if x = 0.
...
...     Parameters
...     ==========
...
...     x : Expr
...       The expression to check.
...
...     y : Expr, optional
...       If provided, check if x = y.
...
...       .. deprecated:: 1.1
...
...          The ``y`` argument to ``is_this_zero`` is deprecated. Use
...          ``is_this_zero(x - y)`` instead.
...
...     """
...     from sympy import simplify
...
...     if y != 0:
...         sympy_deprecation_warning("""
...     The y argument to is_zero() is deprecated. Use is_zero(x - y) instead.""",
...             deprecated_since_version="1.1",
...             active_deprecations_target='is-this-zero-y-deprecation')
...     return simplify(x - y) == 0
>>> is_this_zero(0)
True
>>> is_this_zero(1, 1) 
<stdin>:1: SymPyDeprecationWarning:

The y argument to is_zero() is deprecated. Use is_zero(x - y) instead.

See https://docs.sympy.org/latest/explanation/active-deprecations.html#is-this-zero-y-deprecation
for details.

This has been deprecated since SymPy version 1.1. It
will be removed in a future version of SymPy.

  is_this_zero(1, 1)
True

参见

sympy.utilities.exceptions.SymPyDeprecationWarning, sympy.utilities.exceptions.ignore_warnings, sympy.utilities.decorator.deprecated, sympy.testing.pytest.warns_deprecated_sympy