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 - 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– integer (default: \(4\)); 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 
- 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– integer; the github issue number where this code was introduced
- stack_level– integer (default: \(4\)); 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 
- 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– integer; the github issue number where the experimental functionality was introduced
- message– string; an explanation what is going on
- stack_level– integer (default: \(4\)); 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– integer (default: \(3\)); 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.