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 trac ticket number trac ticket #13109, which is where this mandatory argument to deprecation() was introduced.

Functions and classes

class sage.misc.superseded.DeprecatedFunctionAlias(trac_number, func, module, instance=None, unbound=None)

Bases: object

A wrapper around methods or functions which automatically print the correct 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(trac_number, func)

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

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

INPUT:

  • trac_number – integer. The trac ticket 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)
sage: g(5)
doctest:...: DeprecationWarning: g is deprecated. Please use sage.combinat.partition.number_of_partitions instead.
See http://trac.sagemath.org/13109 for details.
7

This also works for methods:

sage: class cls(object):
....:    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 http://trac.sagemath.org/13109 for details.
42

trac ticket #11585:

sage: def a(): pass
sage: b = deprecated_function_alias(13109, a)
sage: b()
doctest:...: DeprecationWarning: b is deprecated. Please use a instead.
See http://trac.sagemath.org/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(trac_number, message, stacklevel=4)

Issue a deprecation warning.

INPUT:

  • trac_number – integer. The trac ticket 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 http://trac.sagemath.org/13109 for details.
class sage.misc.superseded.experimental(trac_number, stacklevel=4)

Bases: object

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

INPUT:

  • trac_number – an integer. The trac ticket 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(trac_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://trac.sagemath.org/79997 for details.
(7,) {'what': 'Hello'}
sage: class bird(SageObject):
....:     @sage.misc.superseded.experimental(trac_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://trac.sagemath.org/99999 for details.
piep (99,) {}

once, even in doc-tests (see trac ticket #20601).

sage: from sage.misc.superseded import __experimental_self_test
sage: _ = __experimental_self_test("A")
doctest:...: FutureWarning: This class/method/function is
marked as experimental. It, its functionality or its
interface might change without a formal deprecation.
See https://trac.sagemath.org/88888 for details.
I'm A
sage.misc.superseded.experimental_warning(trac_number, message, stacklevel=4)

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

INPUT:

  • trac_number – an integer. The trac ticket 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://trac.sagemath.org/66666 for details.

See also

mark_as_experimental, warning(), deprecation().

sage.misc.superseded.warning(trac_number, message, warning_class=<type 'exceptions.Warning'>, stacklevel=3)

Issue a warning.

INPUT:

  • trac_number – integer. The trac ticket 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://trac.sagemath.org/99999 for details.