Decorator

Useful utility decorators.

@sympy.utilities.decorator.deprecated(message, *, deprecated_since_version, active_deprecations_target, stacklevel=3)

Mark a function as deprecated.

This decorator should be used if an entire function or class is deprecated. If only a certain functionality is deprecated, you should use warns_deprecated_sympy() directly. This decorator is just a convenience. There is no functional difference between using this decorator and calling warns_deprecated_sympy() at the top of the function.

The decorator takes the same arguments as warns_deprecated_sympy(). See its documentation for details on what the keywords to this decorator do.

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

Examples

>>> from sympy.utilities.decorator import deprecated
>>> from sympy import simplify
>>> @deprecated("""    ... The simplify_this(expr) function is deprecated. Use simplify(expr)
... instead.""", deprecated_since_version="1.1",
... active_deprecations_target='simplify-this-deprecation')
... def simplify_this(expr):
...     """
...     Simplify ``expr``.
...
...     .. deprecated:: 1.1
...
...        The ``simplify_this`` function is deprecated. Use :func:`simplify`
...        instead. See its documentation for more information. See
...        :ref:`simplify-this-deprecation` for details.
...
...     """
...     return simplify(expr)
>>> from sympy.abc import x
>>> simplify_this(x*(x + 1) - x**2) 
<stdin>:1: SymPyDeprecationWarning:

The simplify_this(expr) function is deprecated. Use simplify(expr)
instead.

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

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

  simplify_this(x)
x

See also

sympy.utilities.exceptions.SymPyDeprecationWarning, sympy.utilities.exceptions.sympy_deprecation_warning, sympy.utilities.exceptions.ignore_warnings, sympy.testing.pytest.warns_deprecated_sympy

sympy.utilities.decorator.conserve_mpmath_dps(func)

After the function finishes, resets the value of mpmath.mp.dps to the value it had before the function was run.

sympy.utilities.decorator.doctest_depends_on(exe=None, modules=None, disable_viewers=None, python_version=None)

Adds metadata about the dependencies which need to be met for doctesting the docstrings of the decorated objects.

exe should be a list of executables

modules should be a list of modules

disable_viewers should be a list of viewers for preview() to disable

python_version should be the minimum Python version required, as a tuple (like (3, 0))

sympy.utilities.decorator.memoize_property(propfunc)

Property decorator that caches the value of potentially expensive \(propfunc\) after the first evaluation. The cached value is stored in the corresponding property name with an attached underscore.

class sympy.utilities.decorator.no_attrs_in_subclass(cls, f)

Don’t ‘inherit’ certain attributes from a base class

>>> from sympy.utilities.decorator import no_attrs_in_subclass

>>> class A(object):
...     x = 'test'

>>> A.x = no_attrs_in_subclass(A, A.x)

>>> class B(A):
...     pass

>>> hasattr(A, 'x')
True
>>> hasattr(B, 'x')
False

sympy.utilities.decorator.public(obj)

Append obj’s name to global __all__ variable (call site).

By using this decorator on functions or classes you achieve the same goal as by filling __all__ variables manually, you just do not have to repeat yourself (object’s name). You also know if object is public at definition site, not at some random location (where __all__ was set).

Note that in multiple decorator setup (in almost all cases) @public decorator must be applied before any other decorators, because it relies on the pointer to object’s global namespace. If you apply other decorators first, @public may end up modifying the wrong namespace.

Examples

>>> from sympy.utilities.decorator import public

>>> __all__ # noqa: F821
Traceback (most recent call last):
...
NameError: name '__all__' is not defined

>>> @public
... def some_function():
...     pass

>>> __all__ # noqa: F821
['some_function']

sympy.utilities.decorator.threaded(func)

Apply func to sub–elements of an object, including Add.

This decorator is intended to make it uniformly possible to apply a function to all elements of composite objects, e.g. matrices, lists, tuples and other iterable containers, or just expressions.

This version of threaded() decorator allows threading over elements of Add class. If this behavior is not desirable use xthreaded() decorator.

Functions using this decorator must have the following signature:

@threaded
def function(expr, *args, **kwargs):

sympy.utilities.decorator.threaded_factory(func, use_add)

A factory for threaded decorators.

sympy.utilities.decorator.xthreaded(func)

Apply func to sub–elements of an object, excluding Add.

This decorator is intended to make it uniformly possible to apply a function to all elements of composite objects, e.g. matrices, lists, tuples and other iterable containers, or just expressions.

This version of threaded() decorator disallows threading over elements of Add class. If this behavior is not desirable use threaded() decorator.

Functions using this decorator must have the following signature:

@xthreaded
def function(expr, *args, **kwargs):