Improved deprecation and renaming of function and methods

[hivert]

Along the cleanup of combinat, a lot of methods and function get renamed. It is painfull to write backward compatibility aliases.
The patch given here should make it easier. I take also the chance to add a version optional argument to deprecation to store and print in which version of sage the method/function was deprecated.

Here is an excerpt from the doc:

        sage: from sage.misc.misc import deprecated_function_alias
        sage: g = deprecated_function_alias(number_of_partitions,
        ...     'Sage Version 42.132, Release Date: 5123-04-01')
        sage: g(5)
        doctest:1: DeprecationWarning: (Since Sage Version 42.132, Release Date: 5123-04-01) g is deprecated. Please use number_of_partitions instead.
        7

This also works for methods:

        sage: from sage.misc.misc import deprecated_method_alias
        sage: class cls(object):
        ...      def new_meth(self): return 42
        ...      old_meth = deprecated_method_alias(new_meth,
        ...            'Sage Version 42.132, Release Date: 5123-04-01')
        sage: cls().old_meth()
        doctest:...: DeprecationWarning: (Since Sage Version 42.132, Release Date: 5123-04-01) old_meth is deprecated. Please use new_meth instead.
        42

CC: @sagetrac-sage-combinat

Component: misc

Keywords: deprecation:

Author: Florent Hivert

Reviewer: Nathann Cohen

Merged: sage-4.3.alpha1

Issue created by migration from https://trac.sagemath.org/ticket/7515

[hivert]

comment:2

Adressed William comments on sage-devel.

[hivert]

Attachment: trac_7515_method_alias_decorator-fh.patch.gz

[hivert]

comment:3

Updated patch to remark on sage-devel (i.e. just put the version of deprecation, without the date). Reday for review.

[nathanncohen]

comment:4

No problem with this one... Extremely useful :-)

Do you think one should create a ticket saying "replace all the deprecation warning using deprecated_function_alias whenever possible" ?

Firsdt, it would shorten Sage's code, plus everybody would see this is how we should set functions as deprecated instead of using the old method... I "copy" things very often in Sage's code, and if I am not working around an example of this, you can be sure I'd do it the other way :-)

Positive review, thanks for your work !

Nathann

[hivert]

comment:5

Replying to @nathanncohen:

No problem with this one... Extremely useful :-)

Do you think one should create a ticket saying "replace all the deprecation warning using deprecated_function_alias whenever possible" ?

This would be surely a good idea, but I'm not sure I wan't to volunteer to do this one right now. There are a lot of deprecated things in sage. Here is a rough evaluation:

tomahawk-*/devel/sage-main $ grep deprecat **/*.py **/*.pyx | wc
   1228   13940  168762

So I'm opening the ticket but I currently don't accept it.

Cheers,

Florent

[nathanncohen]

comment:6

Perhaps it is possible to script it in emacs.... :-)

[mwhansen]

Reviewer: Nathann Cohen

[mwhansen]

comment:7

Looks good to me.

[mwhansen]

Merged: sage-4.3.alpha1