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 github 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)#

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)#

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

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

github 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.

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)#

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.

See also

experimental(), warning().

sage.misc.superseded.deprecation_cython(issue_number, message, stacklevel=3)#: Issue a deprecation warning – for use in cython functions

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

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'}

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,) {}

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

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.

See also

mark_as_experimental, warning(), deprecation().

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

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.

See also

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