Experimental decorator

[David Lucas]

Johan found this: http://doc.sagemath.org/html/en/reference/misc/sage/misc/superseded.html#sage.misc.superseded.experimental

This is definitely something we should add to new code classes as it allows us to perform some changes without having to put deprecation warnings all over the place. It seems to be a way to add this in the files without being forced to change all the doctests (see what is done in sage/coding./rings/asymptotic/asymptotic_ring.py), but I wasn't able to replicate this -yet.

[Johan Rosenkilde]

It seems that the secret is to have a TEST block in the docstring of the module (top of file) which triggers each of the top-level function/class FutureWarnings.

Furthermore, for functions on top-level inside a module, one needs to set the the stacklevel to 3 in the individual @experimental decorators. Otherwise the warning will be thrown every time one of those functions is called.

However, setting stacklevel to 3 seems to mean that the warning is thrown only for the first function-call among all functions in that module! I consider that something of a bug in Sage...

[David Lucas]

It seems that the secret is to have a TEST block in the docstring of the module (top of file) which triggers each of the top-level function/class FutureWarnings.

Weird, I did try that and it did not work. I probably missed something, I'll try it again.