Ticket #7515: trac_7515_method_alias_decorator-fh.patch

File trac_7515_method_alias_decorator-fh.patch, 14.7 KB (added by hivert, 11 years ago)
  • sage/combinat/partition.py

    # HG changeset patch
    # User Florent Hivert <Florent.Hivert@univ-rouen.fr>
    # Date 1259575839 -3600
    # Node ID 5ef9fecac0af5f96075fc13e37218f0d50ffc9fe
    # Parent  a31e13b8091e5b8e8b70320c38bd6bbe6b6eb0a0
    - New functions deprecated_(method|function)_alias to help writing of backward
    compatibility aliases when a function or a method is renamed.
    - Added optional ``version`` options to deprecation.
    
    diff --git a/sage/combinat/partition.py b/sage/combinat/partition.py
    a b from integer_vector import IntegerVector 
    209209from cartesian_product import CartesianProduct
    210210from integer_list import IntegerListsLex
    211211from sage.functions.other import ceil
    212 from sage.misc.misc import deprecation
     212from sage.misc.misc import deprecation, deprecated_function_alias
    213213
    214214def Partition(mu=None, **keyword):
    215215    """
    class Partition_class(CombinatorialObjec 
    692692                res.append( (i,j) )
    693693        return res
    694694
    695     def boxes(self):
    696         r"""
    697         Deprecated, please use ''cells'' instead.
    698 
    699         TESTS::
    700        
    701             sage: Partition([3,2]).boxes()
    702             doctest:...: DeprecationWarning: boxes is deprecated. Please use cells instead
    703             [(0, 0), (0, 1), (0, 2), (1, 0), (1, 1)]
    704         """
    705         deprecation('boxes is deprecated. Please use cells instead')
    706         return self.cells()
    707    
    708    
     695
     696    boxes = deprecated_function_alias(cells,
     697                'Sage Version 4.3')
     698
    709699    def generalized_pochhammer_symbol(self, a, alpha):
    710700        r"""
    711701        Returns the generalized Pochhammer symbol
    class Partition_class(CombinatorialObjec 
    813803        else:
    814804            #Error: invalid coordinates
    815805            pass
    816     def arm(self, i, j):
    817         r"""
    818         Deprecated. Please use ''arm_length'' instead.
    819        
    820         TESTS::
    821        
    822             sage: Partition([2,2,1]).arm(0, 0)
    823             doctest:...: DeprecationWarning: arm is deprecated. Please use arm_length instead.
    824             1
    825         """
    826         deprecation('arm is deprecated. Please use arm_length instead.')
    827         return self.arm_length(i,j)
     806
     807    arm = deprecated_function_alias(arm_length,
     808        'Sage Version 4.3')
    828809
    829810    def arm_lengths(self, flat=False):
    830811        """
    class Partition_class(CombinatorialObjec 
    879860        else:
    880861            #Error: invalid coordinates
    881862            pass
    882        
    883     def leg(self, i, j):
    884         r"""
    885         Deprecated. Please use ''leg_length'' instead.
    886        
    887         TESTS::
    888        
    889             sage: Partition([2,2,1]).leg(0, 0)
    890             doctest:...: DeprecationWarning: leg is deprecated. Please use leg_length instead.
    891             2
    892         """
    893         deprecation('leg is deprecated. Please use leg_length instead.')
    894         return self.leg_length(i,j)
    895        
     863
     864    leg = deprecated_function_alias(leg_length,
     865        'Sage Version 4.3')
     866
    896867    def leg_lengths(self, flat=False):
    897868        """
    898869        Returns a tableau of shape p with each cell filled in with its leg
    class Partition_class(CombinatorialObjec 
    1017988            4
    1018989        """
    1019990        return self.leg_length(i,j)+self.arm_length(i,j)+1
    1020     def hook(self, i, j):
    1021         r"""
    1022         Deprecated. Please use ''hook_length'' instead.
    1023        
    1024         TESTS::
    1025        
    1026             sage: Partition([2,2,1]).hook(0, 0)
    1027             doctest:...: DeprecationWarning: hook is deprecated. Please use hook_length instead.
    1028             4
    1029         """
    1030         deprecation('hook is deprecated. Please use hook_length instead.')
    1031         return self.hook_length(i,j)
    1032    
    1033    
     991
     992    hook = deprecated_function_alias(hook_length,
     993        'Sage Version 4.3')
     994
     995
    1034996    def hooks(self):
    1035997        """
    1036998        Returns a sorted list of the hook lengths in self.
    class Partition_class(CombinatorialObjec 
    14431405               
    14441406        return res
    14451407
    1446     def r_core(self, length):
    1447         """
    1448         This function is deprecated.
    1449 
    1450         EXAMPLES::
    1451 
    1452             sage: Partition([6,3,2,2]).r_core(3)
    1453             doctest:1: DeprecationWarning: r_core is deprecated. Please use core instead.
    1454             [2, 1, 1]
    1455 
    1456         Please use :meth:`core` instead::
    1457 
    1458             sage: Partition([6,3,2,2]).core(3)
    1459             [2, 1, 1]
    1460 
    1461         """
    1462         from sage.misc.misc import deprecation
    1463         deprecation('r_core is deprecated. Please use core instead.')
    1464         return self.core(length)
    1465 
    14661408    def core(self, length):
    14671409        """
    14681410        Returns the core of the partition -- in the literature the core is
    class Partition_class(CombinatorialObjec 
    15101452        part = [part[i-1]-len(part)+i for i in range(1, len(part)+1)]
    15111453        #Select the r-core
    15121454        return filter(lambda x: x != 0, part)
    1513 
    1514     def r_quotient(self, length):
    1515         """
    1516         This function is deprecated.
    1517 
    1518         EXAMPLES::
    1519 
    1520             sage: Partition([6,3,2,2]).r_quotient(3)
    1521             doctest:1: DeprecationWarning: r_quotient is deprecated. Please use quotient instead.
    1522             [[], [], [2, 1]]
    1523 
    1524         Please use :meth:`quotient` instead::
    1525 
    1526             sage: Partition([6,3,2,2]).quotient(3)
    1527             [[], [], [2, 1]]
    1528         """
    1529         from sage.misc.misc import deprecation
    1530         deprecation('r_quotient is deprecated. Please use quotient instead.')
    1531         return self.quotient(length)
     1455    r_core = deprecated_function_alias(core,
     1456        'Sage Version 4.3')
    15321457
    15331458    def quotient(self, length):
    15341459        """
    class Partition_class(CombinatorialObjec 
    15451470
    15461471            sage: Partition([7,7,5,3,3,3,1]).quotient(3)
    15471472            [[2], [1], [2, 2, 2]]
    1548        
    1549         TESTS::
    1550        
     1473
     1474        TESTS::
     1475
    15511476            sage: Partition([8,7,7,4,1,1,1,1,1]).quotient(3)
    15521477            [[2, 1], [2, 2], [2]]
    15531478            sage: Partition([10,8,7,7]).quotient(4)
    class Partition_class(CombinatorialObjec 
    15901515
    15911516        return result
    15921517
     1518    r_quotient = deprecated_function_alias(quotient,
     1519        'Sage Version 4.3')
     1520
     1521
    15931522    def add_cell(self, i, j = None):
    15941523        r"""
    15951524        Returns a partition corresponding to self with a cell added in row
    15961525        i. i and j are 0-based row and column indices. This does not change
    15971526        p.
    1598        
     1527
    15991528        Note that if you have coordinates in a list, you can call this
    16001529        function with python's \* notation (see the examples below).
    1601        
    1602         EXAMPLES::
    1603        
     1530
     1531        EXAMPLES::
     1532
    16041533            sage: Partition([3, 2, 1, 1]).add_cell(0)
    16051534            [4, 2, 1, 1]
    16061535            sage: cell = [4, 0]; Partition([3, 2, 1, 1]).add_cell(*cell)
    16071536            [3, 2, 1, 1, 1]
    16081537        """
    1609        
     1538
    16101539        if j is None:
    16111540            if i >= len(self):
    16121541                j = 0
    class Partition_class(CombinatorialObjec 
    16221551            return Partition(pl)
    16231552
    16241553        raise ValueError, "[%s, %s] is not an addable cell"%(i,j)
    1625    
    1626     def add_box(self, i, j = None):
    1627         r"""
    1628         Deprecated, please use ''add_cell'' instead.
    1629 
    1630         TESTS::
    1631        
    1632             sage: Partition([3, 2, 1, 1]).add_box(0)
    1633             doctest:...: DeprecationWarning: add_box is deprecated. Please use add_cell instead
    1634             [4, 2, 1, 1]
    1635         """
    1636         deprecation('add_box is deprecated. Please use add_cell instead')
    1637         return self.add_cell(i,j)
    1638 
    1639    
     1554
     1555    add_box = deprecated_function_alias(add_cell,
     1556        'Sage Version 4.3')
     1557
    16401558    def remove_cell(self, i, j = None):
    16411559        """
    16421560        Returns the partition obtained by removing a cell at the end of row
    16431561        i.
    1644        
    1645         EXAMPLES::
    1646        
     1562
     1563        EXAMPLES::
     1564
    16471565            sage: Partition([2,2]).remove_cell(1)
    16481566            [2, 1]
    16491567            sage: Partition([2,2,1]).remove_cell(2)
    16501568            [2, 2]
    16511569            sage: #Partition([2,2]).remove_cell(0)
    1652        
    1653         ::
    1654        
     1570
     1571        ::
     1572
    16551573            sage: Partition([2,2]).remove_cell(1,1)
    16561574            [2, 1]
    16571575            sage: #Partition([2,2]).remove_cell(1,0)
    class Partition_class(CombinatorialObjec 
    16621580
    16631581        if j is None:
    16641582            j = self[i] - 1
    1665            
     1583
    16661584        if [i,j] not in self.corners():
    16671585            raise ValueError, "[%d,%d] is not a corner of the partition" % (i,j)
    16681586
    class Partition_class(CombinatorialObjec 
    16711589        else:
    16721590            return Partition(self[:i] + [ self[i:i+1][0] - 1 ] + self[i+1:])
    16731591
    1674     def remove_box(self, i, j = None):
    1675         r"""
    1676         Deprecated, please use ''remove_cell'' instead.
    1677 
    1678         TESTS::
    1679        
    1680             sage: Partition([2,2]).remove_box(1,1)
    1681             doctest:...: DeprecationWarning: remove_box is deprecated. Please use remove_cell instead.
    1682             [2, 1]
    1683         """
    1684         deprecation('remove_box is deprecated. Please use remove_cell instead.')
    1685         return self.remove_cell(i,j)
     1592    remove_box = deprecated_function_alias(remove_cell,
     1593        'Sage Version 4.3')
    16861594
    16871595
    16881596    def k_skew(self, k):
  • sage/misc/misc.py

    diff --git a/sage/misc/misc.py b/sage/misc/misc.py
    a b def embedded(): 
    19331933#################################################################
    19341934from warnings import warn
    19351935
    1936 def deprecation(message):
     1936def deprecation(message, version=None):
    19371937    r"""
    19381938    Issue a deprecation warning.
    1939    
    1940     EXAMPLE::
    1941    
     1939
     1940    INPUT:
     1941
     1942     - ``message`` - an explanation why things are deprecated and by what it
     1943                  should be replaced.
     1944
     1945     - ``version`` - (optional) on which version and when the deprecation
     1946                  occured. Please put there the version of sageq at the time of deprecation.
     1947
     1948    EXAMPLES::
     1949
    19421950        sage: def foo():
    19431951        ...    sage.misc.misc.deprecation("The function foo is replaced by bar.")
    1944         ...
    1945         sage: def my_function():
    1946         ...    foo()
    1947         ...
    1948         sage: my_function() # random: I don't know how to test the output.
    1949         doctest:1: DeprecationWarning: The function foo is replaced by bar.
     1952        sage: foo()
     1953        doctest:...: DeprecationWarning: The function foo is replaced by bar.
     1954
     1955        sage: def bar():
     1956        ...    sage.misc.misc.deprecation("The function bar is removed.",
     1957        ...         'Sage Version 4.2')
     1958        sage: bar()
     1959        doctest:...: DeprecationWarning: (Since Sage Version 4.2) The function bar is removed.
    19501960    """
    19511961    # Stack level 3 to get the line number of the code which called
    19521962    # the deprecated function which called this function.
     1963    if version is not None:
     1964        message = "(Since " + version + ") " + message
    19531965    warn(message, DeprecationWarning, stacklevel=3)
    19541966
    19551967
     1968
     1969from sage.misc.lazy_attribute import lazy_attribute
     1970class DeprecatedFunctionAlias(object):
     1971    """
     1972    A wrapper around methods or functions wich automatically print the correct
     1973    deprecation message. See :func:`deprecated_function_alias`.
     1974
     1975    AUTHORS:
     1976
     1977     - Florent Hivert (2009-11-23), with the help of Mike Hansen.
     1978    """
     1979    def __init__(self, func, version):
     1980        """
     1981        TESTS::
     1982
     1983            sage: from sage.misc.misc import deprecated_function_alias
     1984            sage: g = deprecated_function_alias(number_of_partitions,
     1985            ...     'Sage Version 42.132')
     1986            sage: g.__doc__ is number_of_partitions.__doc__
     1987            True
     1988        """
     1989        self.__doc__ = func.__doc__
     1990        self.__dict__.update(func.__dict__)
     1991        self.func = func
     1992        self.version  = version
     1993        self.instance = None # for use with methods
     1994
     1995    @lazy_attribute
     1996    def __name__(self):
     1997        """
     1998        TESTS::
     1999
     2000            sage: from sage.misc.misc import deprecated_function_alias
     2001            sage: g = deprecated_function_alias(number_of_partitions,
     2002            ...     'Sage Version 42.132')
     2003            sage: g.__name__
     2004            'g'
     2005        """
     2006        name = None
     2007        import gc
     2008        for referrer in gc.get_referrers(self):
     2009            if isinstance(referrer, dict):
     2010                for k, v in referrer.iteritems():
     2011                    if v is self:
     2012                        name = k
     2013        return name
     2014
     2015    def __call__(self, *args, **kwds):
     2016        """
     2017        TESTS::
     2018
     2019            sage: from sage.misc.misc import deprecated_function_alias
     2020            sage: def bla(): return 42
     2021            sage: blo = deprecated_function_alias(bla,
     2022            ...     'Sage Version 42.132')
     2023            sage: blo()
     2024            doctest:1: DeprecationWarning: (Since Sage Version 42.132) blo is deprecated. Please use bla instead.
     2025            42
     2026        """
     2027        deprecation("%s is deprecated. Please use %s instead."%(self.__name__,
     2028                                                               self.func.__name__),
     2029                    self.version)
     2030        if self.instance is None:
     2031            return self.func(*args, **kwds)
     2032        else:
     2033            return self.func(self.instance, *args, **kwds)
     2034
     2035    def __get__(self, inst, cls = None):
     2036        """
     2037        TESTS::
     2038
     2039            sage: from sage.misc.misc import deprecated_function_alias
     2040            sage: class cls(object):
     2041            ...      def new_meth(self): return 42
     2042            ...      old_meth = deprecated_function_alias(new_meth,
     2043            ...            'Sage Version 42.132')
     2044            sage: obj = cls()
     2045            sage: obj.old_meth.instance is obj
     2046            True
     2047        """
     2048        self.instance = inst
     2049        return self
     2050
     2051
     2052def deprecated_function_alias(func, version):
     2053    """
     2054    Create an aliased version of a function or a method which raise a
     2055    deprecation warning message.
     2056
     2057    If f is a function or a method, write
     2058    ``g = deprecated_function_alias(f, "Sage version")``
     2059    to make a deprecated aliased version of f.
     2060
     2061    INPUT:
     2062
     2063     - ``func`` - the function or method to be aliased
     2064
     2065     - ``version`` - the version of sage when the function is deprecated
     2066
     2067    EXAMPLES::
     2068
     2069        sage: from sage.misc.misc import deprecated_function_alias
     2070        sage: g = deprecated_function_alias(number_of_partitions,
     2071        ...     'Sage Version 42.132')
     2072        sage: g(5)
     2073        doctest:...: DeprecationWarning: (Since Sage Version 42.132) g is deprecated. Please use number_of_partitions instead.
     2074        7
     2075
     2076    This also works for methods::
     2077
     2078        sage: class cls(object):
     2079        ...      def new_meth(self): return 42
     2080        ...      old_meth = deprecated_function_alias(new_meth,
     2081        ...            'Sage Version 42.132')
     2082        sage: cls().old_meth()
     2083        doctest:...: DeprecationWarning: (Since Sage Version 42.132) old_meth is deprecated. Please use new_meth instead.
     2084        42
     2085
     2086    AUTHORS:
     2087
     2088     - Florent Hivert (2009-11-23), with the help of Mike Hansen.
     2089    """
     2090    return DeprecatedFunctionAlias(func, version)
     2091
     2092
    19562093#############################################
    19572094# Operators
    19582095#############################################