Introduced _cache_key for sage objects

No meaningful hash function can be defined for elements which overwrite the
operator == like the p-adics do since the contract on __hash__ would be broken:
elements which compare equal would have different hash values. This would break
caches and lead to subtle bugs. Still such elements should be cacheable for
performance. As a workaround, such non-hashable elements can define a
_cache_key which uniquely identifies them, and so fixes the "broken" ==
operator.

Author: saraedum

src/sage/rings/padics/padic_ZZ_pX_CR_element.pyx

@@ -163,15 +163,18 @@ NOTES::
 
 AUTHORS:
 
-- David Roe  (2008-01-01) initial version
+- David Roe (2008-01-01): initial version
 
-- Robert Harron (2011-09) fixes/enhancements
+- Robert Harron (2011-09): fixes/enhancements
+
+- Julian Rueth (2014-05-09): enable caching through ``_cache_key``
 
 """
 
 #*****************************************************************************
 #       Copyright (C) 2008 David Roe <[email protected]>
 #                          William Stein <[email protected]>
+#                     2014 Julian Rueth <[email protected]>
 #
 #  Distributed under the terms of the GNU General Public License (GPL)
 #  as published by the Free Software Foundation; either version 2 of
@@ -469,6 +472,57 @@ cdef class pAdicZZpXCRElement(pAdicZZpXElement):
             else:
                 self._set_from_list_both(x, aprec, rprec)
 
+    def _cache_key(self):
+        r"""
+        Return a hashable key which uniquely identifies this element among all
+        elements in the parent.
+
+        This enables caching for `p`-adic numbers which are not hashable.
+
+        .. SEEALSO::
+
+            :meth:`sage.structure.sage_object.SageObject._cache_key`
+
+        EXAMPLE:
+
+        In the following example, ``a`` and ``b`` compare equal. They can not
+        have a meaningful hash value since then their hash value would have to
+        be the same::
+
+            sage: K.<a> = Qq(9)
+            sage: b = a + O(3)
+            sage: a == b
+            True
+            sage: hash(a)
+            Traceback (most recent call last):
+            ...
+            TypeError: unhashable type: 'sage.rings.padics.padic_ZZ_pX_CR_element.pAdicZZpXCRElement'
+
+        However, they should be cacheable, therefore they define a
+        ``_cache_key`` which is hashable and uniquely identifies them::
+
+            sage: a._cache_key()
+            (((0, 1),), 0, 20)
+            sage: b._cache_key()
+            (((0, 1),), 0, 1)
+
+        TESTS:
+
+        Check that zero values are handled correctly::
+
+            sage: K.zero()._cache_key()
+            0
+            sage: K(0,1)._cache_key()
+            (0, 1)
+
+        """
+        if self._is_exact_zero():
+            return 0
+        elif self._is_inexact_zero():
+            return 0, self.valuation()
+        else:
+            return tuple(tuple(c) if isinstance(c,list) else c for c in self.unit_part().list()), self.valuation(), self.precision_relative()
+
     cdef int _set_inexact_zero(self, long absprec) except -1:
         """
         Sets ``self`` to be zero with valuation absprec.

src/sage/structure/sage_object.pyx

@@ -221,6 +221,75 @@ cdef class SageObject:
     def __hash__(self):
         return hash(self.__repr__())
 
+    def _cache_key(self):
+        r"""
+        Return a hashable key which uniquely identifies this objects for
+        caching.
+
+        For most objects this will just be the object itself. However, some
+        immutable objects (such as `p`-adic numbers) can not implement a
+        reasonable hash function because their ``==`` operator has been
+        modified to return ``True`` for objects which might behave differently
+        in some computations::
+
+            sage: K.<a> = Qq(9)
+            sage: b = a + O(3)
+            sage: c = a + 3
+            sage: b
+            a + O(3)
+            sage: c
+            a + 3 + O(3^20)
+            sage: b == c
+            True
+            sage: b == a
+            True
+            sage: c == a
+            False
+
+        If such objects defined a non-trivial hash function, this would break
+        caching in many places. However, such objects should still be
+        cacheable. This can be achieved by defining an appropriate
+        ``_cache_key``::
+
+            sage: hash(b)
+            Traceback (most recent call last):
+            ...
+            TypeError: unhashable type: 'sage.rings.padics.padic_ZZ_pX_CR_element.pAdicZZpXCRElement'
+            sage: @cached_method
+            ....: def f(x): return x==a
+            sage: f(b)
+            True
+            sage: f(c) # if b and c were hashable, this would return True
+            False
+
+            sage: b._cache_key()
+            (((0, 1),), 0, 1)
+            sage: c._cache_key()
+            (((0, 1), (1,)), 0, 20)
+
+        Note that such ``_cache_key`` often does not uniquely identify an
+        object in a strict sense::
+
+            sage: S.<a> = Qq(4)
+            sage: d = a + O(2)
+            sage: b._cache_key() == d._cache_key()
+            True
+
+        However, this kind of behaviour is common for many elements with
+        different parents. Special care has to be taken when mixing such
+        elements in caches::
+
+            sage: A = matrix([[1]],base_ring=GF(2))
+            sage: A.set_immutable()
+            sage: B = matrix([[1]],base_ring=GF(3))
+            sage: B.set_immutable()
+            sage: A == B
+            True
+            sage: hash(A) == hash(B)
+            True
+
+        """
+        return self
 
     #############################################################################
     # DATABASE Related code