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 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
(trac_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(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
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 towarnings.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.
See also
-
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 towarnings.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,) {}
See also
-
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 towarnings.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=<class '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 PythonWarning
.stack_level
– (default:3
) an integer. This is passed on towarnings.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.
See also
deprecation()
,experimental()
,exceptions.Warning
.