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_callable_import
(trac_number, module_name, globs, locs, fromlist, message=None)¶ Imports a list of callables into the namespace from which it is called. These callables however give a deprecation warning whenever they are called. This is primarily used from deprecating things from Sage’s
all.py
files.INPUT:
trac_number
– integer. The trac ticket number where the deprecation is introduced.param module_name
– string orNone
. The name of the module from which to import the callables orNone
.globs
– dictionary. Theglobals()
from where this is being called.locs
– dictionary. Thelocals()
from where this is being called.fromlist
– list of strings. The list the names of the callables to deprecatemessage
– string. Message to display when the deprecated functions are called.
Note
If
module_name
isNone
, then no importing will be done, and it will be assumed that the functions have already been imported and are present inglobs
Warning
This should really only be used for functions.
EXAMPLES:
sage: from sage.misc.superseded import deprecated_callable_import sage: is_prime(3) True sage: message = "Using %(name)s from here is deprecated." sage: deprecated_callable_import(13109, None, globals(), locals(), ['is_prime'], message) sage: is_prime(3) doctest:...: DeprecationWarning: Using is_prime from here is deprecated. See http://trac.sagemath.org/13109 for details. True sage: del is_prime sage: deprecated_callable_import(13109, 'sage.arith.all', globals(), locals(), ['is_prime']) sage: is_prime(3) doctest:...: DeprecationWarning: Using is_prime from here is deprecated. If you need to use it, please import it directly from sage.arith.all. See http://trac.sagemath.org/13109 for details. True
-
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
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 http://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 http://trac.sagemath.org/99999 for details. piep (99,) {}
TESTS:
The following test works together with the doc-test for
__experimental_self_test()
to demonstrate that warnings are issued only 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 http://trac.sagemath.org/88888 for details. I'm A
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 http://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 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 http://trac.sagemath.org/99999 for details.
See also