Handling Superseded Functionality#

The main mechanism in Sage to deal with superseded functionality is to add a deprecation warning. This will be shown once, the first time that the deprecated function is called.

Note that all doctests in the following use the github issue number Issue #13109, which is where this mandatory argument to deprecation() was introduced.

Functions and classes#

class sage.misc.superseded.DeprecatedFunctionAlias(issue_number, func, module, instance=None, unbound=None)[source]#

Bases: object

A wrapper around methods or functions which automatically prints a deprecation message. See deprecated_function_alias().

AUTHORS:

  • Florent Hivert (2009-11-23), with the help of Mike Hansen.

  • Luca De Feo (2011-07-11), printing the full module path when different from old path

sage.misc.superseded.deprecated_function_alias(issue_number, func)[source]#

Create an aliased version of a function or a method which raises a deprecation warning message.

If f is a function or a method, write g = deprecated_function_alias(issue_number, f) to make a deprecated aliased version of f.

INPUT:

  • issue_number – integer. The github issue number where the deprecation is introduced.

  • func – the function or method to be aliased

EXAMPLES:

sage: from sage.misc.superseded import deprecated_function_alias
sage: g = deprecated_function_alias(13109, number_of_partitions)                # needs sage.combinat sage.libs.flint
sage: g(5)                                                                      # needs sage.combinat sage.libs.flint
doctest:...: DeprecationWarning: g is deprecated.
Please use sage.combinat.partition.number_of_partitions instead.
See https://github.com/sagemath/sage/issues/13109 for details.
7

>>> from sage.all import *
>>> from sage.misc.superseded import deprecated_function_alias
>>> g = deprecated_function_alias(Integer(13109), number_of_partitions)                # needs sage.combinat sage.libs.flint
>>> g(Integer(5))                                                                      # needs sage.combinat sage.libs.flint
doctest:...: DeprecationWarning: g is deprecated.
Please use sage.combinat.partition.number_of_partitions instead.
See https://github.com/sagemath/sage/issues/13109 for details.
7

This also works for methods:

sage: class cls():
....:    def new_meth(self): return 42
....:    old_meth = deprecated_function_alias(13109, new_meth)
sage: cls().old_meth()
doctest:...: DeprecationWarning: old_meth is deprecated. Please use new_meth instead.
See https://github.com/sagemath/sage/issues/13109 for details.
42

>>> from sage.all import *
>>> class cls():
...    def new_meth(self): return Integer(42)
...    old_meth = deprecated_function_alias(Integer(13109), new_meth)
>>> cls().old_meth()
doctest:...: DeprecationWarning: old_meth is deprecated. Please use new_meth instead.
See https://github.com/sagemath/sage/issues/13109 for details.
42

Issue #11585:

sage: def a(): pass
sage: b = deprecated_function_alias(13109, a)
sage: b()
doctest:...: DeprecationWarning: b is deprecated. Please use a instead.
See https://github.com/sagemath/sage/issues/13109 for details.

>>> from sage.all import *
>>> def a(): pass
>>> b = deprecated_function_alias(Integer(13109), a)
>>> b()
doctest:...: DeprecationWarning: b is deprecated. Please use a instead.
See https://github.com/sagemath/sage/issues/13109 for details.

AUTHORS:

  • Florent Hivert (2009-11-23), with the help of Mike Hansen.

  • Luca De Feo (2011-07-11), printing the full module path when different from old path

sage.misc.superseded.deprecation(issue_number, message, stacklevel=4)[source]#

Issue a deprecation warning.

INPUT:

  • issue_number – integer. The github issue number where the deprecation is introduced.

  • message – string. An explanation why things are deprecated and by what it should be replaced.

  • stack_level – (default: 4) an integer. This is passed on to warnings.warn().

EXAMPLES:

sage: def foo():
....:  sage.misc.superseded.deprecation(13109, 'the function foo is replaced by bar')
sage: foo()
doctest:...: DeprecationWarning: the function foo is replaced by bar
See https://github.com/sagemath/sage/issues/13109 for details.

>>> from sage.all import *
>>> def foo():
...  sage.misc.superseded.deprecation(Integer(13109), 'the function foo is replaced by bar')
>>> foo()
doctest:...: DeprecationWarning: the function foo is replaced by bar
See https://github.com/sagemath/sage/issues/13109 for details.

See also

experimental(), warning().

sage.misc.superseded.deprecation_cython(issue_number, message, stacklevel=3)[source]#

Issue a deprecation warning – for use in cython functions

class sage.misc.superseded.experimental(issue_number, stacklevel=4)[source]#

Bases: object

A decorator which warns about the experimental/unstable status of the decorated class/method/function.

INPUT:

  • issue_number – an integer. The github issue number where this code was introduced.

  • stack_level – (default: 4) an integer. This is passed on to warnings.warn().

EXAMPLES:

sage: @sage.misc.superseded.experimental(issue_number=79997)
....: def foo(*args, **kwargs):
....:     print("{} {}".format(args, kwargs))
sage: foo(7, what='Hello')
doctest:...: FutureWarning: This class/method/function is
marked as experimental. It, its functionality or its
interface might change without a formal deprecation.
See https://github.com/sagemath/sage/issues/79997 for details.
(7,) {'what': 'Hello'}

>>> from sage.all import *
>>> @sage.misc.superseded.experimental(issue_number=Integer(79997))
... def foo(*args, **kwargs):
...     print("{} {}".format(args, kwargs))
>>> foo(Integer(7), what='Hello')
doctest:...: FutureWarning: This class/method/function is
marked as experimental. It, its functionality or its
interface might change without a formal deprecation.
See https://github.com/sagemath/sage/issues/79997 for details.
(7,) {'what': 'Hello'}

sage: class bird(SageObject):
....:     @sage.misc.superseded.experimental(issue_number=99999)
....:     def __init__(self, *args, **kwargs):
....:         print("piep {} {}".format(args, kwargs))
sage: _ = bird(99)
doctest:...: FutureWarning: This class/method/function is
marked as experimental. It, its functionality or its
interface might change without a formal deprecation.
See https://github.com/sagemath/sage/issues/99999 for details.
piep (99,) {}

>>> from sage.all import *
>>> class bird(SageObject):
...     @sage.misc.superseded.experimental(issue_number=Integer(99999))
...     def __init__(self, *args, **kwargs):
...         print("piep {} {}".format(args, kwargs))
>>> _ = bird(Integer(99))
doctest:...: FutureWarning: This class/method/function is
marked as experimental. It, its functionality or its
interface might change without a formal deprecation.
See https://github.com/sagemath/sage/issues/99999 for details.
piep (99,) {}

See also

experimental(), warning(), deprecation().

sage.misc.superseded.experimental_warning(issue_number, message, stacklevel=4)[source]#

Issue a warning that the functionality or class is experimental and might change in future.

INPUT:

  • issue_number – an integer. The github issue number where the experimental functionality was introduced.

  • message – a string. An explanation what is going on.

  • stack_level – (default: 4) an integer. This is passed on to warnings.warn().

EXAMPLES:

sage: def foo():
....:    sage.misc.superseded.experimental_warning(
....:        66666, 'This function is experimental and '
....:               'might change in future.')
sage: foo()
doctest:...: FutureWarning: This function is experimental and
might change in future.
See https://github.com/sagemath/sage/issues/66666 for details.

>>> from sage.all import *
>>> def foo():
...    sage.misc.superseded.experimental_warning(
...        Integer(66666), 'This function is experimental and '
...               'might change in future.')
>>> foo()
doctest:...: FutureWarning: This function is experimental and
might change in future.
See https://github.com/sagemath/sage/issues/66666 for details.

See also

mark_as_experimental, warning(), deprecation().

sage.misc.superseded.warning(issue_number, message, warning_class=<class 'Warning'>, stacklevel=3)[source]#

Issue a warning.

INPUT:

  • issue_number – integer. The github issue number where the deprecation is introduced.

  • message – string. An explanation what is going on.

  • warning_class – (default: Warning) a class inherited from a Python Warning.

  • stack_level – (default: 3) an integer. This is passed on to warnings.warn().

EXAMPLES:

sage: def foo():
....:     sage.misc.superseded.warning(
....:         99999,
....:         'The syntax will change in future.',
....:         FutureWarning)
sage: foo()
doctest:...: FutureWarning: The syntax will change in future.
See https://github.com/sagemath/sage/issues/99999 for details.

>>> from sage.all import *
>>> def foo():
...     sage.misc.superseded.warning(
...         Integer(99999),
...         'The syntax will change in future.',
...         FutureWarning)
>>> foo()
doctest:...: FutureWarning: The syntax will change in future.
See https://github.com/sagemath/sage/issues/99999 for details.

See also

deprecation(), experimental(), exceptions.Warning.