Ticket #715: cachefunc_94107.py

# -*- coding: utf-8 -*-

# This file was generated by 'sage-doctest' from
# '/scratch/sking/sage-5.4.beta0/devel/sage-main/sage/misc/cachefunc.pyx'.

from sage.all_cmdline import *; 
import sage.plot.plot; sage.plot.plot.DOCTEST_MODE=True

def warning_function(f):
    import warnings

    def doctest_showwarning(message, category, filename, lineno, file=f, line=None):
        try:
            file.write(warnings.formatwarning(message, category, 'doctest', lineno, line))
        except IOError:
            pass # the file (probably stdout) is invalid
    return doctest_showwarning

def change_warning_output(file):
    import warnings
    warnings.showwarning = warning_function(file)

import re
float_pattern = re.compile('[+-]?((\d*\.?\d+)|(\d+\.?))([eE][+-]?\d+)?')

def check_with_tolerance(expected, actual, epsilon, rel_or_abs=None):
    if actual is Exception:
        return # error computing actual
    else:
        actual = str(actual)
    expected = re.sub('\n +', '\n', expected)
    actual = re.sub('\n +', '\n', actual)
    assert float_pattern.sub('#', expected.strip()) == float_pattern.sub('#', actual.strip()), \
        "Expected '" + expected + "' got '" + actual + "'"
    for expected_value, actual_value in zip(float_pattern.finditer(expected), float_pattern.finditer(actual)):
        expected_value = float(expected_value.group())
        actual_value = float(actual_value.group())
        if rel_or_abs == 'abs' or expected_value == 0:
            assert abs(expected_value - actual_value) < epsilon, "Out of tolerance %s vs %s" % (expected_value, actual_value)
        else:
            assert abs((expected_value - actual_value) / expected_value) < epsilon, "Out of tolerance %s vs %s" % (expected_value, actual_value)
def example_0():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


Cached Functions and Methods

AUTHORS:

- William Stein (inspired by conversation with Justin Walker).
- Mike Hansen (added doctests and made it work with class methods).
- Willem Jan Palenstijn (add CachedMethodCaller for binding cached
  methods to instances).
- Tom Boothby (added DiskCachedFunction).
- Simon King (improved performance, more doctests, cython version,
  added CachedMethodCallerNoArgs).

EXAMPLES:

By trac ticket #11115, cached functions and methods are now also
available in Cython code. The following examples cover various ways
of usage.

Python functions::

    >>> @cached_function###line 22:_sage_    >>> @cached_function
    ... def test_pfunc(x):
    ...     '''
    ...     Some documentation
    ...     '''
    ...     return -x
    ...
    >>> test_pfunc(Integer(5)) is test_pfunc(Integer(5))###line 29:_sage_    >>> test_pfunc(5) is test_pfunc(5)
    True

Unfortunately, cython functions do not allow arbitrary
decorators. However, one can wrap a Cython function and
turn it into a cached function, by trac ticket #11115.
We need to provide the name that the wrapped method or
function should have, since otherwise the name of the
original function would be used::

    >>> cython('''cpdef test_funct(x): return -x''')###line 39:_sage_    >>> cython('''cpdef test_funct(x): return -x''')
    >>> wrapped_funct = cached_function(test_funct, name='wrapped_funct')###line 40:_sage_    >>> wrapped_funct = cached_function(test_funct, name='wrapped_funct')
    >>> wrapped_funct###line 41:_sage_    >>> wrapped_funct
    Cached version of <built-in function test_funct>
    >>> wrapped_funct.__name__###line 43:_sage_    >>> wrapped_funct.__name__
    'wrapped_funct'
    >>> wrapped_funct(Integer(5))###line 45:_sage_    >>> wrapped_funct(5)
    -5
    >>> wrapped_funct(Integer(5)) is wrapped_funct(Integer(5))###line 47:_sage_    >>> wrapped_funct(5) is wrapped_funct(5)
    True

We can proceed similarly for cached methods of Cython classes,
provided that they allow attribute assignment or have a public
attribute ``__cached_methods`` of type ``<dict>``. Since trac ticket
#11115, this is the case for all classes inheriting from
:class:`~sage.structure.parent.Parent`::

    >>> cython_code = ['cpdef test_meth(self,x):',###line 56:_sage_    >>> cython_code = ['cpdef test_meth(self,x):',
    ... '    "some doc for a wrapped cython method"',
    ... '    return -x',
    ... 'from sage.all import cached_method',
    ... 'from sage.structure.parent cimport Parent',
    ... 'cdef class MyClass(Parent):',
    ... '    wrapped_method = cached_method(test_meth,name="wrapped_method")']
    >>> cython('\n'.join(cython_code))###line 63:_sage_    >>> cython('\n'.join(cython_code))
    >>> O = MyClass()###line 64:_sage_    >>> O = MyClass()
    >>> O.wrapped_method###line 65:_sage_    >>> O.wrapped_method
    Cached version of <built-in function test_meth>
    >>> O.wrapped_method.__name__###line 67:_sage_    >>> O.wrapped_method.__name__
    'wrapped_method'
    >>> O.wrapped_method(Integer(5))###line 69:_sage_    >>> O.wrapped_method(5)
    -5
    >>> O.wrapped_method(Integer(5)) is O.wrapped_method(Integer(5))###line 71:_sage_    >>> O.wrapped_method(5) is O.wrapped_method(5)
    True

By trac ticket #11115, even if a parent does not allow attribute
assignment, it can inherit a cached method from the parent class of a
category (previously, the cache would have been broken)::

    >>> cython_code = ["from sage.all import cached_method, cached_in_parent_method, Category, Objects",###line 78:_sage_    >>> cython_code = ["from sage.all import cached_method, cached_in_parent_method, Category, Objects",
    ... "class MyCategory(Category):",
    ... "    @cached_method",
    ... "    def super_categories(self):",
    ... "        return [Objects()]",
    ... "    class ElementMethods:",
    ... "        @cached_method",
    ... "        def element_cache_test(self):",
    ... "            return -self",
    ... "        @cached_in_parent_method",
    ... "        def element_via_parent_test(self):",
    ... "            return -self",
    ... "    class ParentMethods:",
    ... "        @cached_method",
    ... "        def one(self):",
    ... "            return self.element_class(self,1)",
    ... "        @cached_method",
    ... "        def invert(self, x):",
    ... "            return -x"]
    >>> cython('\n'.join(cython_code))###line 97:_sage_    >>> cython('\n'.join(cython_code))
    >>> C = MyCategory()###line 98:_sage_    >>> C = MyCategory()

In order to keep the memory footprint of elements small, it was
decided to not support the same freedom of using cached methods
for elements: If an instance of a class derived from
:class:`~sage.structure.element.Element` does not allow attribute
assignment, then a cached method inherited from the category of
its parent will break, as in the class ``MyBrokenElement`` below.

However, there is a class :class:`~sage.structure.element.ElementWithCachedMethod`
that has generally a slower attribute access, but fully supports
cached methods. We remark, however, that cached methods are
*much* faster if attribute access works. So, we expect that
:class:`~sage.structure.element.ElementWithCachedMethod` will
hardly by used.
::

    >>> cython_code = ["from sage.structure.element cimport Element, ElementWithCachedMethod",###line 115:_sage_    >>> cython_code = ["from sage.structure.element cimport Element, ElementWithCachedMethod",
    ... "cdef class MyBrokenElement(Element):",
    ... "    cdef public object x",
    ... "    def __init__(self,P,x):",
    ... "        self.x=x",
    ... "        Element.__init__(self,P)",
    ... "    def __neg__(self):",
    ... "        return MyBrokenElement(self.parent(),-self.x)",
    ... "    def _repr_(self):",
    ... "        return '<%s>'%self.x",
    ... "    def __hash__(self):",
    ... "        return hash(self.x)",
    ... "    def __cmp__(left, right):",
    ... "        return (<Element>left)._cmp(right)",
    ... "    def __richcmp__(left, right, op):",
    ... "        return (<Element>left)._richcmp(right,op)",
    ... "    cdef int _cmp_c_impl(left, Element right) except -2:",
    ... "        return cmp(left.x,right.x)",
    ... "    def raw_test(self):",
    ... "        return -self",
    ... "cdef class MyElement(ElementWithCachedMethod):",
    ... "    cdef public object x",
    ... "    def __init__(self,P,x):",
    ... "        self.x=x",
    ... "        ElementWithCachedMethod.__init__(self,P)",
    ... "    def __neg__(self):",
    ... "        return MyElement(self.parent(),-self.x)",
    ... "    def _repr_(self):",
    ... "        return '<%s>'%self.x",
    ... "    def __hash__(self):",
    ... "        return hash(self.x)",
    ... "    def __cmp__(left, right):",
    ... "        return (<Element>left)._cmp(right)",
    ... "    def __richcmp__(left, right, op):",
    ... "        return (<Element>left)._richcmp(right,op)",
    ... "    cdef int _cmp_c_impl(left, Element right) except -2:",
    ... "        return cmp(left.x,right.x)",
    ... "    def raw_test(self):",
    ... "        return -self",
    ... "from sage.structure.parent cimport Parent",
    ... "cdef class MyParent(Parent):",
    ... "    Element = MyElement"]
    >>> cython('\n'.join(cython_code))###line 157:_sage_    >>> cython('\n'.join(cython_code))
    >>> P = MyParent(category=C)###line 158:_sage_    >>> P = MyParent(category=C)
    >>> ebroken = MyBrokenElement(P,Integer(5))###line 159:_sage_    >>> ebroken = MyBrokenElement(P,5)
    >>> e = MyElement(P,Integer(5))###line 160:_sage_    >>> e = MyElement(P,5)

The cached methods inherited by the parent works::

    >>> P.one()###line 164:_sage_    >>> P.one()
    <1>
    >>> P.one() is P.one()###line 166:_sage_    >>> P.one() is P.one()
    True
    >>> P.invert(e)###line 168:_sage_    >>> P.invert(e)
    <-5>
    >>> P.invert(e) is P.invert(e)###line 170:_sage_    >>> P.invert(e) is P.invert(e)
    True

The cached methods inherited by ``MyElement`` works::

    >>> e.element_cache_test()###line 175:_sage_    >>> e.element_cache_test()
    <-5>
    >>> e.element_cache_test() is e.element_cache_test()###line 177:_sage_    >>> e.element_cache_test() is e.element_cache_test()
    True
    >>> e.element_via_parent_test()###line 179:_sage_    >>> e.element_via_parent_test()
    <-5>
    >>> e.element_via_parent_test() is e.element_via_parent_test()###line 181:_sage_    >>> e.element_via_parent_test() is e.element_via_parent_test()
    True

The other element class can only inherit a ``cached_in_parent_method``, since
the cache is stored in the parent. In fact, equal elements share the cache,
even if they are of different types::

    >>> e == ebroken###line 188:_sage_    >>> e == ebroken
    True
    >>> type(e) == type(ebroken)###line 190:_sage_    >>> type(e) == type(ebroken)
    False
    >>> ebroken.element_via_parent_test() is e.element_via_parent_test()###line 192:_sage_    >>> ebroken.element_via_parent_test() is e.element_via_parent_test()
    True

However, the cache of the other inherited method breaks, although the method
as such works::

    >>> ebroken.element_cache_test()###line 198:_sage_    >>> ebroken.element_cache_test()
    <-5>
    >>> ebroken.element_cache_test() is ebroken.element_cache_test()###line 200:_sage_    >>> ebroken.element_cache_test() is ebroken.element_cache_test()
    False

The cache can be emptied::

    >>> a = test_pfunc(Integer(5))###line 205:_sage_    >>> a = test_pfunc(5)
    >>> test_pfunc.clear_cache()###line 206:_sage_    >>> test_pfunc.clear_cache()
    >>> a is test_pfunc(Integer(5))###line 207:_sage_    >>> a is test_pfunc(5)
    False
    >>> a = P.one()###line 209:_sage_    >>> a = P.one()
    >>> P.one.clear_cache()###line 210:_sage_    >>> P.one.clear_cache()
    >>> a is P.one()###line 211:_sage_    >>> a is P.one()
    False

Since ``e`` and ``ebroken`` share the cache, when we empty it for one element
it is empty for the other as well::

    >>> b = ebroken.element_via_parent_test()###line 217:_sage_    >>> b = ebroken.element_via_parent_test()
    >>> e.element_via_parent_test.clear_cache()###line 218:_sage_    >>> e.element_via_parent_test.clear_cache()
    >>> b is ebroken.element_via_parent_test()###line 219:_sage_    >>> b is ebroken.element_via_parent_test()
    False

Introspection works::

    >>> from sage.misc.edit_module import file_and_line###line 224:_sage_    >>> from sage.misc.edit_module import file_and_line
    >>> from sage.misc.sageinspect import sage_getdoc, sage_getfile, sage_getsource###line 225:_sage_    >>> from sage.misc.sageinspect import sage_getdoc, sage_getfile, sage_getsource
    >>> print sage_getdoc(test_pfunc)###line 226:_sage_    >>> print sage_getdoc(test_pfunc)
       Some documentation
    >>> print sage_getdoc(O.wrapped_method)###line 228:_sage_    >>> print sage_getdoc(O.wrapped_method)
    some doc for a wrapped cython method
    <BLANKLINE>
    >>> print sage_getsource(O.wrapped_method)###line 231:_sage_    >>> print sage_getsource(O.wrapped_method)
    cpdef test_meth(self,x):
        "some doc for a wrapped cython method"
        return -x

It is a very common special case to cache a method that has no
arguments. In that special case, the time needed to access the cache
can be drastically reduced by using a special implementation. The
cached method decorator automatically determines which implementation
ought to be chosen. A typical example is
:meth:`sage.rings.polynomial.multi_polynomial_ideal.MPolynomialIdeal.gens`
(no arguments) versus
:meth:`sage.rings.polynomial.multi_polynomial_ideal.MPolynomialIdeal.groebner_basis`
(several arguments)::

    >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 246:_sage_    >>> P.<a,b,c,d> = QQ[]
    >>> I = P*[a,b]###line 247:_sage_    >>> I = P*[a,b]
    >>> I.gens()###line 248:_sage_    >>> I.gens()
    [a, b]
    >>> I.gens() is I.gens()###line 250:_sage_    >>> I.gens() is I.gens()
    True
    >>> I.groebner_basis()###line 252:_sage_    >>> I.groebner_basis()
    [a, b]
    >>> I.groebner_basis() is I.groebner_basis()###line 254:_sage_    >>> I.groebner_basis() is I.groebner_basis()
    True
    >>> type(I.gens)###line 256:_sage_    >>> type(I.gens)
    <type 'sage.misc.cachefunc.CachedMethodCallerNoArgs'>
    >>> type(I.groebner_basis)###line 258:_sage_    >>> type(I.groebner_basis)
    <type 'sage.misc.cachefunc.CachedMethodCaller'>


>>> sig_on_count()
0
"""

def example_1():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    Unpickling of cached functions.

    NOTE:

    Pickling and unpickling of cached functions is by importing
    from the module in which the function is defined.

    INPUT:

    - ``module``: A string, describing the module to import the
      function from.
    - ``name``: A string, name of the to-be-imported cached function.

    EXAMPLE::

        >>> type(cunningham_prime_factors)###line 292:_sage_    >>> type(cunningham_prime_factors)
        <type 'sage.misc.cachefunc.CachedFunction'>
        >>> loads(dumps(cunningham_prime_factors)) is cunningham_prime_factors #indirect doctest###line 294:_sage_    >>> loads(dumps(cunningham_prime_factors)) is cunningham_prime_factors #indirect doctest
        True

    
>>> sig_on_count()
0
"""

def example_2():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    Create a cached version of a function, which only recomputes
    values it hasn't already computed. Synonyme: ``cached_function``

    INPUT:

    - ``f`` -- a function
    - ``name`` (optional string) -- name that the cached version
      of ``f`` should be provided with.

    If ``f`` is a function, do either ``g = CachedFunction(f)``
    or ``g = cached_function(f)`` to make a cached version of ``f``,
    or put ``@cached_function`` right before the definition of ``f``
    (i.e., use Python decorators)::

        @cached_function
        def f(...):
            ....

    The inputs to the function must be hashable.

    EXAMPLES::

        >>> @cached_function###line 324:_sage_    >>> @cached_function
        ... def mul(x, y=Integer(2)):
        ...     return x*y
        ...
        >>> mul(Integer(3))###line 328:_sage_    >>> mul(3)
        6

    We demonstrate that the result is cached, and that, moreover,
    the cache takes into account the various ways of providing
    default arguments::

        >>> mul(Integer(3)) is mul(Integer(3),Integer(2))###line 335:_sage_    >>> mul(3) is mul(3,2)
        True
        >>> mul(Integer(3),y=Integer(2)) is mul(Integer(3),Integer(2))###line 337:_sage_    >>> mul(3,y=2) is mul(3,2)
        True

    The user can clear the cache::

        >>> a = mul(Integer(4))###line 342:_sage_    >>> a = mul(4)
        >>> mul.clear_cache()###line 343:_sage_    >>> mul.clear_cache()
        >>> a is mul(Integer(4))###line 344:_sage_    >>> a is mul(4)
        False

    It is also possible to explicitly override the cache with
    a different value::

        >>> mul.set_cache('foo',Integer(5))###line 350:_sage_    >>> mul.set_cache('foo',5)
        >>> mul(Integer(5),Integer(2))###line 351:_sage_    >>> mul(5,2)
        'foo'

    
>>> sig_on_count()
0
"""

def example_3():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Create a cached version of a function, which only recomputes
        values it hasn't already computed. A custom name can be
        provided by an optional argument "name".

        If f is a function, do either g = CachedFunction(f) to make
        a cached version of f, or put @CachedFunction right before
        the definition of f (i.e., use Python decorators, but then
        the optional argument ``name`` can not be used)::

            @CachedFunction
            def f(...):
                ....

        The inputs to the function must be hashable.

        TESTS::

            >>> g = CachedFunction(number_of_partitions)###line 374:_sage_    >>> g = CachedFunction(number_of_partitions)
            >>> g.__name__###line 375:_sage_    >>> g.__name__
            'number_of_partitions'
            >>> 'partitions' in sage.misc.sageinspect.sage_getdoc(g)###line 377:_sage_    >>> 'partitions' in sage.misc.sageinspect.sage_getdoc(g)
            True
            >>> g(Integer(5))###line 379:_sage_    >>> g(5)
            7
            >>> g.cache###line 381:_sage_    >>> g.cache
            {((5, None, 'default'), ()): 7}
            >>> def f(t=Integer(1)): print(t)###line 383:_sage_    >>> def f(t=1): print(t)
            >>> h = CachedFunction(f)###line 384:_sage_    >>> h = CachedFunction(f)
            >>> w = walltime()###line 385:_sage_    >>> w = walltime()
            >>> h(); h(Integer(1)); h(t=Integer(1))###line 386:_sage_    >>> h(); h(1); h(t=1)
            1
            >>> walltime(w) < Integer(2)###line 388:_sage_    >>> walltime(w) < 2
            True

        
>>> sig_on_count()
0
"""

def example_4():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Perform initialization common to CachedFunction and CachedMethodCaller.

        TESTS::

            >>> @cached_function###line 401:_sage_    >>> @cached_function
            ... def test_cache(x):
            ...     return -x
            >>> test_cache._fix_to_pos is not None  # indirect doctest###line 404:_sage_    >>> test_cache._fix_to_pos is not None  # indirect doctest
            True

        
>>> sig_on_count()
0
"""

def example_5():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Pickling of cached functions.

        TEST::

            >>> type(cunningham_prime_factors)###line 426:_sage_    >>> type(cunningham_prime_factors)
            <type 'sage.misc.cachefunc.CachedFunction'>
            >>> loads(dumps(cunningham_prime_factors)) is cunningham_prime_factors #indirect doctest###line 428:_sage_    >>> loads(dumps(cunningham_prime_factors)) is cunningham_prime_factors #indirect doctest
            True

        
>>> sig_on_count()
0
"""

def example_6():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Provide documentation for the cached function.

        A cached function shall inherit the documentation
        from the function that is wrapped, not from the
        documentation of the wrapper.

        TEST::

            >>> P = QQ['x, y']; (x, y,) = P._first_ngens(2)###line 450:_sage_    >>> P.<x,y> = QQ[]
            >>> I = P*[x,y]###line 451:_sage_    >>> I = P*[x,y]
            >>> from sage.misc.sageinspect import sage_getdoc###line 452:_sage_    >>> from sage.misc.sageinspect import sage_getdoc
            >>> print sage_getdoc(I.groebner_basis) # indirect doctest###line 453:_sage_    >>> print sage_getdoc(I.groebner_basis) # indirect doctest
               Return the reduced Groebner basis of this ideal.
            ...
               ALGORITHM: Uses Singular, Magma (if available), Macaulay2 (if
               available), or a toy implementation.

        
>>> sig_on_count()
0
"""

def example_7():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns the source code for the wrapped function.

        TESTS::

            >>> from sage.misc.sageinspect import sage_getsource###line 491:_sage_    >>> from sage.misc.sageinspect import sage_getsource
            >>> g = CachedFunction(number_of_partitions)###line 492:_sage_    >>> g = CachedFunction(number_of_partitions)
            >>> 'bober' in sage_getsource(g)  # indirect doctest###line 493:_sage_    >>> 'bober' in sage_getsource(g)  # indirect doctest
            True

        
>>> sig_on_count()
0
"""

def example_8():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns the list of source lines and the first line number
        of the wrapped function.

        TEST::

            >>> P = QQ['x, y']; (x, y,) = P._first_ngens(2)###line 507:_sage_    >>> P.<x,y> = QQ[]
            >>> I = P*[x,y]###line 508:_sage_    >>> I = P*[x,y]
            >>> from sage.misc.sageinspect import sage_getsourcelines###line 509:_sage_    >>> from sage.misc.sageinspect import sage_getsourcelines
            >>> l = "        elif algorithm == 'macaulay2:gb':\n"###line 510:_sage_    >>> l = "        elif algorithm == 'macaulay2:gb':\n"
            >>> l in sage_getsourcelines(I.groebner_basis)[Integer(0)] # indirect doctest###line 511:_sage_    >>> l in sage_getsourcelines(I.groebner_basis)[0] # indirect doctest
            True

        
>>> sig_on_count()
0
"""

def example_9():        r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Return the argspec of the wrapped function or method.

        This was implemented in trac ticket #11115.

        EXAMPLE::

            >>> P = QQ['x, y']; (x, y,) = P._first_ngens(2)###line 526:_sage_    >>> P.<x,y> = QQ[]
            >>> I = P*[x,y]###line 527:_sage_    >>> I = P*[x,y]
            >>> from sage.misc.sageinspect import sage_getargspec###line 528:_sage_    >>> from sage.misc.sageinspect import sage_getargspec
            >>> sage_getargspec(I.groebner_basis)   # indirect doctest###line 529:_sage_    >>> sage_getargspec(I.groebner_basis)   # indirect doctest
            ArgSpec(args=['self', 'algorithm', 'deg_bound', 'mult_bound', 'prot'],
            varargs='args', keywords='kwds', defaults=('', None, None,
            False))

        
>>> sig_on_count()
0
"""

def example_10():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Return value from cache or call the wrapped function,
        caching the output.

        TESTS::

            >>> g = CachedFunction(number_of_partitions)###line 545:_sage_    >>> g = CachedFunction(number_of_partitions)
            >>> a = g(Integer(5))###line 546:_sage_    >>> a = g(5)
            >>> g.get_cache()###line 547:_sage_    >>> g.get_cache()
            {((5, None, 'default'), ()): 7}
            >>> a = g(Integer(10)**Integer(5))   # indirect doctest###line 549:_sage_    >>> a = g(10^5)   # indirect doctest
            >>> a == number_of_partitions(Integer(10)**Integer(5))###line 550:_sage_    >>> a == number_of_partitions(10^5)
            True
            >>> a is g(Integer(10)**Integer(5))###line 552:_sage_    >>> a is g(10^5)
            True
            >>> a is number_of_partitions(Integer(10)**Integer(5))###line 554:_sage_    >>> a is number_of_partitions(10^5)
            False

        
>>> sig_on_count()
0
"""

def example_11():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns the cache dictionary.

        EXAMPLES::

            >>> g = CachedFunction(number_of_partitions)###line 580:_sage_    >>> g = CachedFunction(number_of_partitions)
            >>> a = g(Integer(5))###line 581:_sage_    >>> a = g(5)
            >>> g.get_cache()###line 582:_sage_    >>> g.get_cache()
            {((5, None, 'default'), ()): 7}

        
>>> sig_on_count()
0
"""

def example_12():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Checks if the argument list is in the cache.

        EXAMPLES::

            >>> class Foo:###line 594:_sage_    >>> class Foo:
            ...       def __init__(self, x):
            ...           self._x = x
            ...       @cached_method
            ...       def f(self, z, y=Integer(0)):
            ...           return self._x*z+y
            ...
            >>> a = Foo(Integer(2))###line 601:_sage_    >>> a = Foo(2)
            >>> a.f.is_in_cache(Integer(3))###line 602:_sage_    >>> a.f.is_in_cache(3)
            False
            >>> a.f(Integer(3))###line 604:_sage_    >>> a.f(3)
            6
            >>> a.f.is_in_cache(Integer(3),y=Integer(0))###line 606:_sage_    >>> a.f.is_in_cache(3,y=0)
            True
        
>>> sig_on_count()
0
"""

def example_13():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Set the value for those args and keyword args
        Mind the unintuitive syntax (value first).
        Any idea on how to improve that welcome!

        EXAMPLES::

            >>> g = CachedFunction(number_of_partitions)###line 619:_sage_    >>> g = CachedFunction(number_of_partitions)
            >>> a = g(Integer(5))###line 620:_sage_    >>> a = g(5)
            >>> g.get_cache()###line 621:_sage_    >>> g.get_cache()
            {((5, None, 'default'), ()): 7}
            >>> g.set_cache(Integer(17), Integer(5))###line 623:_sage_    >>> g.set_cache(17, 5)
            >>> g.get_cache()###line 624:_sage_    >>> g.get_cache()
            {((5, None, 'default'), ()): 17}
            >>> g(Integer(5))###line 626:_sage_    >>> g(5)
            17

        DEVELOPER NOTE:

        Is there a way to use the following intuitive syntax?

        ::





            19
        
>>> sig_on_count()
0
"""

def example_14():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns the key in the cache to be used when args
        and kwds are passed in as parameters.

        EXAMPLES::

            >>> @cached_function###line 648:_sage_    >>> @cached_function
            ... def foo(x):
            ...    return x**Integer(2)
            ...
            >>> foo(Integer(2))###line 652:_sage_    >>> foo(2)
            4
            >>> foo.get_key(Integer(2))###line 654:_sage_    >>> foo.get_key(2)
            ((2,), ())
            >>> foo.get_key(x=Integer(3))###line 656:_sage_    >>> foo.get_key(x=3)
            ((3,), ())
        
>>> sig_on_count()
0
"""

def example_15():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        EXAMPLES::

            >>> g = CachedFunction(number_of_partitions)###line 665:_sage_    >>> g = CachedFunction(number_of_partitions)
            >>> g     # indirect doctest###line 666:_sage_    >>> g     # indirect doctest
            Cached version of <function number_of_partitions at 0x...>
        
>>> sig_on_count()
0
"""

def example_16():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Clear the cache dictionary.

        EXAMPLES::

            >>> g = CachedFunction(number_of_partitions)###line 680:_sage_    >>> g = CachedFunction(number_of_partitions)
            >>> a = g(Integer(5))###line 681:_sage_    >>> a = g(5)
            >>> g.get_cache()###line 682:_sage_    >>> g.get_cache()
            {((5, None, 'default'), ()): 7}
            >>> g.clear_cache()###line 684:_sage_    >>> g.clear_cache()
            >>> g.get_cache()###line 685:_sage_    >>> g.get_cache()
            {}
        
>>> sig_on_count()
0
"""

def example_17():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Cache values for a number of inputs.  Do the computation
        in parallel, and only bother to compute values that we
        haven't already cached.

        EXAMPLES::

            >>> @cached_function###line 700:_sage_    >>> @cached_function
            ... def oddprime_factors(n):
            ...     l = [p for p,e in factor(n) if p != Integer(2)]
            ...     return len(l)
            >>> oddprime_factors.precompute(range(Integer(1),Integer(100)), Integer(4))###line 704:_sage_    >>> oddprime_factors.precompute(range(1,100), 4)
            >>> oddprime_factors.cache[(Integer(25),),()]###line 705:_sage_    >>> oddprime_factors.cache[(25,),()]
            1
        
>>> sig_on_count()
0
"""

def example_18():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    This class helps to unpickle cached methods.

    NOTE:

    Since trac ticket #8611, a cached method is an attribute
    of the instance (provided that it has a ``__dict__``).
    Hence, when pickling the instance, it would be attempted
    to pickle that attribute as well, but this is a problem,
    since functions can not be pickled, currently. Therefore,
    we replace the actual cached method by a place holder,
    that kills itself as soon as any attribute is requested.
    Then, the original cached attribute is reinstated. But the
    cached values are in fact saved.

    EXAMPLE::

        >>> R = PolynomialRing(QQ, Integer(3), names=('x', 'y', 'z',)); (x, y, z,) = R._first_ngens(3)###line 738:_sage_    >>> R.<x, y, z> = PolynomialRing(QQ, 3)
        >>> I = R*(x**Integer(3) + y**Integer(3) + z**Integer(3),x**Integer(4)-y**Integer(4))###line 739:_sage_    >>> I = R*(x^3 + y^3 + z^3,x^4-y^4)
        >>> I.groebner_basis()###line 740:_sage_    >>> I.groebner_basis()
        [y^5*z^3 - 1/4*x^2*z^6 + 1/2*x*y*z^6 + 1/4*y^2*z^6,
         x^2*y*z^3 - x*y^2*z^3 + 2*y^3*z^3 + z^6,
         x*y^3 + y^4 + x*z^3, x^3 + y^3 + z^3]
        >>> I.groebner_basis###line 744:_sage_    >>> I.groebner_basis
        Cached version of <function groebner_basis at 0x...>

    We now pickle and unpickle the ideal. The cached method
    ``groebner_basis`` is replaced by a placeholder::

        >>> J = loads(dumps(I))###line 750:_sage_    >>> J = loads(dumps(I))
        >>> J.groebner_basis###line 751:_sage_    >>> J.groebner_basis
        Pickle of the cached method "groebner_basis"

    But as soon as any other attribute is requested from the
    placeholder, it replaces itself by the cached method, and
    the entries of the cache are actually preserved::

        >>> J.groebner_basis.is_in_cache()###line 758:_sage_    >>> J.groebner_basis.is_in_cache()
        True
        >>> J.groebner_basis###line 760:_sage_    >>> J.groebner_basis
        Cached version of <function groebner_basis at 0x...>
        >>> J.groebner_basis() == I.groebner_basis()###line 762:_sage_    >>> J.groebner_basis() == I.groebner_basis()
        True

    TESTS:

    Since Trac Ticket #11115, there is a special implementation for
    cached methods that don't take arguments::

        >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 770:_sage_    >>> P.<a,b,c,d> = QQ[]
        >>> I = P*[a,b]###line 771:_sage_    >>> I = P*[a,b]
        >>> type(I.gens)###line 772:_sage_    >>> type(I.gens)
        <type 'sage.misc.cachefunc.CachedMethodCallerNoArgs'>
        >>> type(I.groebner_basis)###line 774:_sage_    >>> type(I.groebner_basis)
        <type 'sage.misc.cachefunc.CachedMethodCaller'>

    We demonstrate that both implementations can be pickled and
    preserve the cache. For that purpose, we assign nonsense to the
    cache. Of course, it is a very bad idea to override the cache in
    that way.  So, please don't try this at home::

        >>> I.groebner_basis.set_cache('foo',algorithm='singular')###line 782:_sage_    >>> I.groebner_basis.set_cache('foo',algorithm='singular')
        >>> I.groebner_basis(algorithm='singular')###line 783:_sage_    >>> I.groebner_basis(algorithm='singular')
        'foo'
        >>> I.gens.set_cache('bar')###line 785:_sage_    >>> I.gens.set_cache('bar')
        >>> I.gens()###line 786:_sage_    >>> I.gens()
        'bar'
        >>> J = loads(dumps(I))###line 788:_sage_    >>> J = loads(dumps(I))
        >>> J.gens()###line 789:_sage_    >>> J.gens()
        'bar'
        >>> J.groebner_basis(algorithm='singular')###line 791:_sage_    >>> J.groebner_basis(algorithm='singular')
        'foo'

    Anyway, the cache will be automatically reconstructed after
    clearing it::

        >>> J.gens.clear_cache()###line 797:_sage_    >>> J.gens.clear_cache()
        >>> J.gens()###line 798:_sage_    >>> J.gens()
        [a, b]
        >>> J.groebner_basis.clear_cache()###line 800:_sage_    >>> J.groebner_basis.clear_cache()
        >>> J.groebner_basis(algorithm='singular')###line 801:_sage_    >>> J.groebner_basis(algorithm='singular')
        [a, b]

    AUTHOR:

    - Simon King (2011-01)
    
>>> sig_on_count()
0
"""

def example_19():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        INPUT:

        - ``inst`` - some instance.
        - ``name`` (string) - usually the name of an attribute
          of ``inst`` to which ``self`` is assigned.

        TEST::

            >>> from sage.misc.cachefunc import CachedMethodPickle###line 818:_sage_    >>> from sage.misc.cachefunc import CachedMethodPickle
            >>> P = CachedMethodPickle(Integer(1), 'foo')###line 819:_sage_    >>> P = CachedMethodPickle(1, 'foo')
            >>> P###line 820:_sage_    >>> P
            Pickle of the cached method "foo"

        
>>> sig_on_count()
0
"""

def example_20():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        TEST::

            >>> R = PolynomialRing(QQ, Integer(3), names=('x', 'y', 'z',)); (x, y, z,) = R._first_ngens(3)###line 831:_sage_    >>> R.<x, y, z> = PolynomialRing(QQ, 3)
            >>> I = R*(x**Integer(3) + y**Integer(3) + z**Integer(3),x**Integer(4)-y**Integer(4))###line 832:_sage_    >>> I = R*(x^3 + y^3 + z^3,x^4-y^4)
            >>> G = I.groebner_basis()###line 833:_sage_    >>> G = I.groebner_basis()
            >>> J = loads(dumps(I))###line 834:_sage_    >>> J = loads(dumps(I))
            >>> J.groebner_basis  #indirect doctest###line 835:_sage_    >>> J.groebner_basis  #indirect doctest
            Pickle of the cached method "groebner_basis"
        
>>> sig_on_count()
0
"""

def example_21():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        This class is a pickle. However, sometimes, pickles
        need to be pickled another time.

        TEST::

            >>> PF = WeylGroup(['A',Integer(3)]).pieri_factors()###line 846:_sage_    >>> PF = WeylGroup(['A',3]).pieri_factors()
            >>> a = PF.an_element()###line 847:_sage_    >>> a = PF.an_element()
            >>> a.bruhat_lower_covers()###line 848:_sage_    >>> a.bruhat_lower_covers()
            [[0 1 0 0]
            [0 0 1 0]
            [1 0 0 0]
            [0 0 0 1], [0 1 0 0]
            [1 0 0 0]
            [0 0 0 1]
            [0 0 1 0], [1 0 0 0]
            [0 0 1 0]
            [0 0 0 1]
            [0 1 0 0]]
            >>> b = loads(dumps(a))###line 859:_sage_    >>> b = loads(dumps(a))
            >>> b.bruhat_lower_covers###line 860:_sage_    >>> b.bruhat_lower_covers
            Pickle of the cached method "bruhat_lower_covers"

        When we now pickle ``b``, the pickle of the cached method
        needs to be taken care of::

            >>> c = loads(dumps(b))  # indirect doctest###line 866:_sage_    >>> c = loads(dumps(b))  # indirect doctest
            >>> c.bruhat_lower_covers###line 867:_sage_    >>> c.bruhat_lower_covers
            Pickle of the cached method "bruhat_lower_covers"
            >>> c.bruhat_lower_covers()###line 869:_sage_    >>> c.bruhat_lower_covers()
            [[0 1 0 0]
            [0 0 1 0]
            [1 0 0 0]
            [0 0 0 1], [0 1 0 0]
            [1 0 0 0]
            [0 0 0 1]
            [0 0 1 0], [1 0 0 0]
            [0 0 1 0]
            [0 0 0 1]
            [0 1 0 0]]

        
>>> sig_on_count()
0
"""

def example_22():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        The purpose of this call method is to kill ``self`` and to
        replace it by an actual :class:`CachedMethodCaller`. The last
        thing that ``self`` does before disappearing is to call the
        :class:`CachedMethodCaller` and return the result.

        EXAMPLE::

            >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 892:_sage_    >>> P.<a,b,c,d> = QQ[]
            >>> I = P*[a,b]###line 893:_sage_    >>> I = P*[a,b]
            >>> I.gens###line 894:_sage_    >>> I.gens
            Cached version of <function gens at 0x...>
            >>> J = loads(dumps(I))###line 896:_sage_    >>> J = loads(dumps(I))
            >>> J.gens###line 897:_sage_    >>> J.gens
            Pickle of the cached method "gens"
            >>> J.gens()   # indirect doctest###line 899:_sage_    >>> J.gens()   # indirect doctest
            [a, b]
            >>> J.gens###line 901:_sage_    >>> J.gens
            Cached version of <function gens at 0x...>

        
>>> sig_on_count()
0
"""

def example_23():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        TEST::

            >>> R = PolynomialRing(QQ, Integer(3), names=('x', 'y', 'z',)); (x, y, z,) = R._first_ngens(3)###line 919:_sage_    >>> R.<x, y, z> = PolynomialRing(QQ, 3)
            >>> I = R*(x**Integer(3) + y**Integer(3) + z**Integer(3),x**Integer(4)-y**Integer(4))###line 920:_sage_    >>> I = R*(x^3 + y^3 + z^3,x^4-y^4)
            >>> G = I.groebner_basis()###line 921:_sage_    >>> G = I.groebner_basis()
            >>> J = loads(dumps(I))###line 922:_sage_    >>> J = loads(dumps(I))
            >>> J.groebner_basis###line 923:_sage_    >>> J.groebner_basis
            Pickle of the cached method "groebner_basis"

        If an attribute of name ``s`` is requested (say,
        ``is_in_cache``), the attribute ``self._name`` of
        ``self._instance`` is deleted. Then, the attribute
        of name ``s`` of the attribute ``self._name`` of
        ``self._instance`` is requested. Since ``self._name``
        is a cached method defined for the class of
        ``self._instance``, retrieving the just-deleted
        attribute ``self._name`` succeeds.

        In that way, the unpickling of the cached method is
        finally accomplished::

            >>> J.groebner_basis.is_in_cache()  #indirect doctest###line 938:_sage_    >>> J.groebner_basis.is_in_cache()  #indirect doctest
            True
            >>> J.groebner_basis###line 940:_sage_    >>> J.groebner_basis
            Cached version of <function groebner_basis at 0x...>

        
>>> sig_on_count()
0
"""

def example_24():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    Utility class that is used by :class:`CachedMethod` to bind a
    cached method to an instance.

    NOTE:

    Since Trac Ticket #11115, there is a special implementation
    :class:`CachedMethodCallerNoArgs` for methods that do not take
    arguments.

    EXAMPLE::

        >>> class A:###line 967:_sage_    >>> class A:
        ...    @cached_method
        ...    def bar(self,x):
        ...        return x**Integer(2)
        >>> a = A()###line 971:_sage_    >>> a = A()
        >>> a.bar###line 972:_sage_    >>> a.bar
        Cached version of <function bar at 0x...>
        >>> type(a.bar)###line 974:_sage_    >>> type(a.bar)
        <type 'sage.misc.cachefunc.CachedMethodCaller'>
        >>> a.bar(Integer(2)) is a.bar(x=Integer(2))###line 976:_sage_    >>> a.bar(2) is a.bar(x=2)
        True

    
>>> sig_on_count()
0
"""

def example_25():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        EXAMPLES::

            >>> class Foo:###line 984:_sage_    >>> class Foo:
            ...       def __init__(self, x):
            ...           self._x = x
            ...       @cached_method
            ...       def f(self,*args):
            ...           return self._x**Integer(2)
            ...
            >>> a = Foo(Integer(2))###line 991:_sage_    >>> a = Foo(2)
            >>> a.f.get_cache()###line 992:_sage_    >>> a.f.get_cache()
            {}
            >>> a.f()###line 994:_sage_    >>> a.f()
            4
            >>> a.f.get_cache()###line 996:_sage_    >>> a.f.get_cache()
            {((), ()): 4}
        
>>> sig_on_count()
0
"""

def example_26():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        The pickle of a :class:`CachedMethodCaller` unpickles
        to a :class:`CachedMethodPickle`, that is able to replace
        itself by a copy of the original :class:`CachedMethodCaller`.

        TEST::

            >>> R = PolynomialRing(QQ, Integer(3), names=('x', 'y', 'z',)); (x, y, z,) = R._first_ngens(3)###line 1014:_sage_    >>> R.<x, y, z> = PolynomialRing(QQ, 3)
            >>> I = R*(x**Integer(3) + y**Integer(3) + z**Integer(3),x**Integer(4)-y**Integer(4))###line 1015:_sage_    >>> I = R*(x^3 + y^3 + z^3,x^4-y^4)
            >>> G = I.groebner_basis()###line 1016:_sage_    >>> G = I.groebner_basis()
            >>> J = loads(dumps(I))  #indirect doctest###line 1017:_sage_    >>> J = loads(dumps(I))  #indirect doctest
            >>> J.groebner_basis###line 1018:_sage_    >>> J.groebner_basis
            Pickle of the cached method "groebner_basis"
            >>> J.groebner_basis.is_in_cache()###line 1020:_sage_    >>> J.groebner_basis.is_in_cache()
            True
            >>> J.groebner_basis###line 1022:_sage_    >>> J.groebner_basis
            Cached version of <function groebner_basis at 0x...>

        
>>> sig_on_count()
0
"""

def example_27():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Call the cached method without using the cache.

        EXAMPLE::

            >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 1038:_sage_    >>> P.<a,b,c,d> = QQ[]
            >>> I = P*[a,b]###line 1039:_sage_    >>> I = P*[a,b]
            >>> I.groebner_basis()###line 1040:_sage_    >>> I.groebner_basis()
            [a, b]
            >>> I.groebner_basis._instance_call() is I.groebner_basis()###line 1042:_sage_    >>> I.groebner_basis._instance_call() is I.groebner_basis()
            False
            >>> I.groebner_basis._instance_call() == I.groebner_basis()###line 1044:_sage_    >>> I.groebner_basis._instance_call() == I.groebner_basis()
            True

        
>>> sig_on_count()
0
"""

def example_28():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Call the cached method.

        TESTS::

            >>> class Foo:###line 1056:_sage_    >>> class Foo:
            ...       @cached_method
            ...       def f(self, x,y=Integer(1)):
            ...           return x+y
            ...
            >>> a = Foo()###line 1061:_sage_    >>> a = Foo()
            >>> a.f(Integer(1))  #indirect doctest###line 1062:_sage_    >>> a.f(1)  #indirect doctest
            2

        The result is cached, taking into account
        the three ways of providing (named) arguments::

            >>> a.f(Integer(5)) is a.f(Integer(5),Integer(1))###line 1068:_sage_    >>> a.f(5) is a.f(5,1)
            True
            >>> a.f(Integer(5)) is a.f(Integer(5),y=Integer(1))###line 1070:_sage_    >>> a.f(5) is a.f(5,y=1)
            True
            >>> a.f(Integer(5)) is a.f(y=Integer(1),x=Integer(5))###line 1072:_sage_    >>> a.f(5) is a.f(y=1,x=5)
            True

        We test that #5843 is fixed::

            >>> class Foo:###line 1077:_sage_    >>> class Foo:
            ...       def __init__(self, x):
            ...           self._x = x
            ...       @cached_method
            ...       def f(self, y):
            ...           return self._x
            ...
            >>> a = Foo(Integer(2))###line 1084:_sage_    >>> a = Foo(2)
            >>> b = Foo(Integer(3))###line 1085:_sage_    >>> b = Foo(3)
            >>> a.f(b.f)###line 1086:_sage_    >>> a.f(b.f)
            2
        
>>> sig_on_count()
0
"""

def example_29():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Convert arguments to the key for this instance's cache.

        EXAMPLES::

            >>> class Foo:###line 1135:_sage_    >>> class Foo:
            ...       def __init__(self, x):
            ...           self._x = x
            ...       @cached_method
            ...       def f(self, y, z=Integer(0)):
            ...           return self._x * y + z
            ...
            >>> a = Foo(Integer(2))###line 1142:_sage_    >>> a = Foo(2)
            >>> z = a.f(Integer(37))###line 1143:_sage_    >>> z = a.f(37)
            >>> k = a.f.get_key(Integer(37)); k###line 1144:_sage_    >>> k = a.f.get_key(37); k
            ((37, 0), ())
            >>> a.f.get_cache()[k] is z###line 1146:_sage_    >>> a.f.get_cache()[k] is z
            True

        Note that the method does not test whether there are
        too many arguments, or wrong argument names::

            >>> a.f.get_key(Integer(1),Integer(2),Integer(3),x=Integer(4),y=Integer(5),z=Integer(6))###line 1152:_sage_    >>> a.f.get_key(1,2,3,x=4,y=5,z=6)
            ((1, 2, 3), (('x', 4), ('y', 5), ('z', 6)))

        It does, however, take into account the different
        ways of providing named arguments, possibly with a
        default value::

            >>> a.f.get_key(Integer(5))###line 1159:_sage_    >>> a.f.get_key(5)
            ((5, 0), ())
            >>> a.f.get_key(y=Integer(5))###line 1161:_sage_    >>> a.f.get_key(y=5)
            ((5, 0), ())
            >>> a.f.get_key(Integer(5),Integer(0))###line 1163:_sage_    >>> a.f.get_key(5,0)
            ((5, 0), ())
            >>> a.f.get_key(Integer(5),z=Integer(0))###line 1165:_sage_    >>> a.f.get_key(5,z=0)
            ((5, 0), ())
            >>> a.f.get_key(y=Integer(5),z=Integer(0))###line 1167:_sage_    >>> a.f.get_key(y=5,z=0)
            ((5, 0), ())

        
>>> sig_on_count()
0
"""

def example_30():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Get a :class:`CachedMethodCaller` bound to a specific
        instance of the class of the cached method.

        NOTE:

        :class:`CachedMethodCaller` has a separate ``__get__``
        since the categories framework creates and caches the
        return value of ``CachedMethod.__get__`` with
        ``inst==None``.

        This getter attempts to assign a bound method as an
        attribute to the given instance. If this is not
        possible (for example, for some extension classes),
        it is attempted to find an attribute ``__cached_methods``,
        and store/retrieve the bound method there. In that
        way, cached methods can be implemented for extension
        classes deriving from :class:`~sage.structure.parent.Parent`
        and :class:`~sage.structure.element.Element`.

        TESTS:

        Due to the separate ``__get__`` method, it is possible
        to define a cached method in one class and use it as
        an attribute of another class.

            >>> class Foo:###line 1202:_sage_    >>> class Foo:
            ...       @cached_method
            ...       def f(self, y):
            ...           return y - Integer(1)
            >>> class Bar:###line 1206:_sage_    >>> class Bar:
            ...       f = Foo.f
            >>> b1 = Bar()###line 1208:_sage_    >>> b1 = Bar()
            >>> b2 = Bar()###line 1209:_sage_    >>> b2 = Bar()

        The :class:`CachedMethod` is replaced by an instance
        of :class:`CachedMethodCaller` that (by trac ticket
        #8611) is set as an attribute. Hence, we have::

            >>> b1.f is b1.f###line 1215:_sage_    >>> b1.f is b1.f
            True

        Any instance of ``Bar`` gets its own instance of
        :class:`CachedMethodCaller``::

            >>> b1.f is b2.f###line 1221:_sage_    >>> b1.f is b2.f
            False

        The method caller knows the instance that it belongs
        to::

            >>> Foo.f._instance is None###line 1227:_sage_    >>> Foo.f._instance is None
            True
            >>> b1.f._instance is b1###line 1229:_sage_    >>> b1.f._instance is b1
            True
            >>> b2.f._instance is b2###line 1231:_sage_    >>> b2.f._instance is b2
            True

        An extension class can inherit a cached method from the
        parent or element class of a category (trac ticket #11115).
        See :class:`CachedMethodCaller` for examples.

        
>>> sig_on_count()
0
"""

def example_31():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    Utility class that is used by :class:`CachedMethod` to bind a
    cached method to an instance, in the case of a method that does
    not accept any arguments except ``self``.

    NOTE:

    The return value ``None`` would not be cached. So, if you have
    a method that does not accept arguments and may return ``None``
    after a lengthy computation, then ``@cached_method`` should not
    be used.

    EXAMPLE::

        >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 1274:_sage_    >>> P.<a,b,c,d> = QQ[]
        >>> I = P*[a,b]###line 1275:_sage_    >>> I = P*[a,b]
        >>> I.gens###line 1276:_sage_    >>> I.gens
        Cached version of <function gens at 0x...>
        >>> type(I.gens)###line 1278:_sage_    >>> type(I.gens)
        <type 'sage.misc.cachefunc.CachedMethodCallerNoArgs'>
        >>> I.gens is I.gens###line 1280:_sage_    >>> I.gens is I.gens
        True
        >>> I.gens() is I.gens()###line 1282:_sage_    >>> I.gens() is I.gens()
        True

    AUTHOR:

    - Simon King (2011-04)
    
>>> sig_on_count()
0
"""

def example_32():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        EXAMPLES::

            >>> class Foo:###line 1293:_sage_    >>> class Foo:
            ...       def __init__(self, x):
            ...           self._x = x
            ...       @cached_method
            ...       def f(self):
            ...           return self._x**Integer(2)
            ...
            >>> a = Foo(Integer(2))###line 1300:_sage_    >>> a = Foo(2)
            >>> print a.f.get_cache()###line 1301:_sage_    >>> print a.f.get_cache()
            None
            >>> a.f()###line 1303:_sage_    >>> a.f()
            4
            >>> a.f.get_cache()###line 1305:_sage_    >>> a.f.get_cache()
            4

        
>>> sig_on_count()
0
"""

def example_33():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Since functions can not be pickled, the cached method caller
        is pickled by a :class:`CachedMethodPickle`, that replaces
        itself by an actual :class:`CachedMethodCallerNoArgs` as soon
        as it is asked to do anything.

        TEST::

            >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 1346:_sage_    >>> P.<a,b,c,d> = QQ[]
            >>> I = P*[a,b]###line 1347:_sage_    >>> I = P*[a,b]
            >>> I.gens()###line 1348:_sage_    >>> I.gens()
            [a, b]
            >>> I.gens###line 1350:_sage_    >>> I.gens
            Cached version of <function gens at 0x...>
            >>> J = loads(dumps(I))###line 1352:_sage_    >>> J = loads(dumps(I))
            >>> J.gens###line 1353:_sage_    >>> J.gens
            Pickle of the cached method "gens"
            >>> J.gens.cache###line 1355:_sage_    >>> J.gens.cache
            [a, b]
            >>> J.gens###line 1357:_sage_    >>> J.gens
            Cached version of <function gens at 0x...>

        
>>> sig_on_count()
0
"""

def example_34():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Call the cached method without using the cache.

        EXAMPLE::

            >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 1369:_sage_    >>> P.<a,b,c,d> = QQ[]
            >>> I = P*[a,b]###line 1370:_sage_    >>> I = P*[a,b]
            >>> I.gens()###line 1371:_sage_    >>> I.gens()
            [a, b]
            >>> I.gens._instance_call() is I.gens()###line 1373:_sage_    >>> I.gens._instance_call() is I.gens()
            False
            >>> I.gens._instance_call() == I.gens()###line 1375:_sage_    >>> I.gens._instance_call() == I.gens()
            True

        
>>> sig_on_count()
0
"""

def example_35():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Call the cached method.

        EXAMPLE::

            >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 1387:_sage_    >>> P.<a,b,c,d> = QQ[]
            >>> I = P*[a,b]###line 1388:_sage_    >>> I = P*[a,b]
            >>> I.gens()    # indirect doctest###line 1389:_sage_    >>> I.gens()    # indirect doctest
            [a, b]
            >>> I.gens() is I.gens()###line 1391:_sage_    >>> I.gens() is I.gens()
            True

        
>>> sig_on_count()
0
"""

def example_36():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Override the cache with a specific value.

        NOTE:

        ``None`` is not suitable for a cached value. It would be
        interpreted as an empty cache, forcing a new computation.

        EXAMPLES::

            >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 1411:_sage_    >>> P.<a,b,c,d> = QQ[]
            >>> I = P*[a,b]###line 1412:_sage_    >>> I = P*[a,b]
            >>> I.gens()###line 1413:_sage_    >>> I.gens()
            [a, b]
            >>> I.gens.set_cache('bar')###line 1415:_sage_    >>> I.gens.set_cache('bar')
            >>> I.gens()###line 1416:_sage_    >>> I.gens()
            'bar'

        The cache can be emptied and thus the original value will
        be reconstructed::

            >>> I.gens.clear_cache()###line 1422:_sage_    >>> I.gens.clear_cache()
            >>> I.gens()###line 1423:_sage_    >>> I.gens()
            [a, b]

        The attempt to assign ``None`` to the cache fails::

            >>> I.gens.set_cache(None)###line 1428:_sage_    >>> I.gens.set_cache(None)
            >>> I.gens()###line 1429:_sage_    >>> I.gens()
            [a, b]

        
>>> sig_on_count()
0
"""

def example_37():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Clear the cache dictionary.

        EXAMPLES::

            >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 1441:_sage_    >>> P.<a,b,c,d> = QQ[]
            >>> I = P*[a,b]###line 1442:_sage_    >>> I = P*[a,b]
            >>> I.gens()###line 1443:_sage_    >>> I.gens()
            [a, b]
            >>> I.gens.set_cache('bar')###line 1445:_sage_    >>> I.gens.set_cache('bar')
            >>> I.gens()###line 1446:_sage_    >>> I.gens()
            'bar'

        The cache can be emptied and thus the original value will
        be reconstructed::

            >>> I.gens.clear_cache()###line 1452:_sage_    >>> I.gens.clear_cache()
            >>> I.gens()###line 1453:_sage_    >>> I.gens()
            [a, b]

        
>>> sig_on_count()
0
"""

def example_38():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Answers whether the return value is already in the cache.

        NOTE:

        Recall that a cached method without arguments can not cache
        the return value ``None``.

        EXAMPLE::

            >>> P = QQ['x, y']; (x, y,) = P._first_ngens(2)###line 1470:_sage_    >>> P.<x,y> = QQ[]
            >>> I = P*[x,y]###line 1471:_sage_    >>> I = P*[x,y]
            >>> I.gens.is_in_cache()###line 1472:_sage_    >>> I.gens.is_in_cache()
            False
            >>> I.gens()###line 1474:_sage_    >>> I.gens()
            [x, y]
            >>> I.gens.is_in_cache()###line 1476:_sage_    >>> I.gens.is_in_cache()
            True

        
>>> sig_on_count()
0
"""

def example_39():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Get a :class:`CachedMethodCallerNoArgs` bound to a specific
        instance of the class of the cached method.

        NOTE:

        :class:`CachedMethodCallerNoArgs` has a separate ``__get__``
        since the categories framework creates and caches the
        return value of ``CachedMethod.__get__`` with
        ``inst==None``.

        This getter attempts to assign a bound method as an
        attribute to the given instance. If this is not
        possible (for example, for some extension classes),
        it is attempted to find an attribute ``__cached_methods``,
        and store/retrieve the bound method there. In that
        way, cached methods can be implemented for extension
        classes deriving from :class:`~sage.structure.parent.Parent`
        and :class:`~sage.structure.element.Element`.

        TESTS:

        Due to the separate ``__get__`` method, it is possible
        to define a cached method in one class and use it as
        an attribute of another class.

            >>> class Foo:###line 1509:_sage_    >>> class Foo:
            ...       def __init__(self, n):
            ...           self.__n = n
            ...       @cached_method
            ...       def f(self):
            ...           return self.__n**Integer(2)
            ...
            >>> class Bar:###line 1516:_sage_    >>> class Bar:
            ...       f = Foo.f
            ...
            >>> b1 = Bar()###line 1519:_sage_    >>> b1 = Bar()
            >>> b2 = Bar()###line 1520:_sage_    >>> b2 = Bar()

        The :class:`CachedMethod` is replaced by an instance of
        :class:`CachedMethodCallerNoArgs` that is set as an
        attribute. Hence, we have::

            >>> b1.f is b1.f###line 1526:_sage_    >>> b1.f is b1.f
            True
            >>> type(b1.f)###line 1528:_sage_    >>> type(b1.f)
            <type 'sage.misc.cachefunc.CachedMethodCallerNoArgs'>

        Any instance of ``Bar`` gets its own instance of
        :class:`CachedMethodCaller``::

            >>> b1.f is b2.f###line 1534:_sage_    >>> b1.f is b2.f
            False

        The method caller knows the instance that it belongs
        to::

            >>> Foo.f._instance is None###line 1540:_sage_    >>> Foo.f._instance is None
            True
            >>> b1.f._instance is b1###line 1542:_sage_    >>> b1.f._instance is b1
            True
            >>> b2.f._instance is b2###line 1544:_sage_    >>> b2.f._instance is b2
            True

        
>>> sig_on_count()
0
"""

def example_40():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    A decorator that creates a cached version of an instance
    method of a class.

    NOTE:

    For proper behavior, the method must be a pure function
    (no side effects). Arguments to the method must be hashable.

    EXAMPLES::

        >>> class Foo(object):###line 1580:_sage_    >>> class Foo(object):
        ...       @cached_method
        ...       def f(self, t, x=Integer(2)):
        ...           print 'computing'
        ...           return t**x
        >>> a = Foo()###line 1585:_sage_    >>> a = Foo()

    The example shows that the actual computation
    takes place only once, and that the result is
    identical for equivalent input::

        >>> res = a.f(Integer(3), Integer(2)); res###line 1591:_sage_    >>> res = a.f(3, 2); res
        computing
        9
        >>> a.f(t = Integer(3), x = Integer(2)) is res###line 1594:_sage_    >>> a.f(t = 3, x = 2) is res
        True
        >>> a.f(Integer(3)) is res###line 1596:_sage_    >>> a.f(3) is res
        True

    Note, however, that the :class:`CachedMethod` is replaced by a
    :class:`CachedMethodCaller` or :class:`CachedMethodCallerNoArgs`
    as soon as it is bound to an instance or class::

        >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 1603:_sage_    >>> P.<a,b,c,d> = QQ[]
        >>> I = P*[a,b]###line 1604:_sage_    >>> I = P*[a,b]
        >>> type(I.__class__.gens)###line 1605:_sage_    >>> type(I.__class__.gens)
        <type 'sage.misc.cachefunc.CachedMethodCallerNoArgs'>

    So, you would hardly ever see an instance of this class alive.
    
>>> sig_on_count()
0
"""

def example_41():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        EXAMPLES::

            >>> class Foo:###line 1614:_sage_    >>> class Foo:
            ...       def __init__(self, x):
            ...           self._x = x
            ...       @cached_method
            ...       def f(self,n):
            ...           return self._x**n
            ...       @cached_method
            ...       def f0(self):
            ...           return self._x**Integer(2)
            ...
            >>> a = Foo(Integer(2))###line 1624:_sage_    >>> a = Foo(2)
            >>> a.f(Integer(2))###line 1625:_sage_    >>> a.f(2)
            4
            >>> a.f0()###line 1627:_sage_    >>> a.f0()
            4

        The computations in method ``f`` are tried to store in a
        dictionary assigned to the instance ``a``::

            >>> hasattr(a, '_cache__f')###line 1633:_sage_    >>> hasattr(a, '_cache__f')
            True
            >>> a._cache__f###line 1635:_sage_    >>> a._cache__f
            {((2,), ()): 4}

        As a shortcut, useful to speed up internal computations,
        the same dictionary is also available as an attribute
        of the ``CachedMethodCaller``::

            >>> type(a.f)###line 1642:_sage_    >>> type(a.f)
            <type 'sage.misc.cachefunc.CachedMethodCaller'>
            >>> a.f.cache is a._cache__f###line 1644:_sage_    >>> a.f.cache is a._cache__f
            True

        Note that if the instance ``a`` would not accept attribute
        assignment, the computations would still be cached in
        ``a.f.cache``, and they would in fact be preserved when
        pickling.

        The cached method ``f0`` accepts no arguments, which allows
        for an improved way of caching: By an attribute of the cached
        method itsel. This cache is *only* available in that way, i.e.,
        it is not additionally stored as an attribute of ``a``::

            >>> type(a.f0)###line 1657:_sage_    >>> type(a.f0)
            <type 'sage.misc.cachefunc.CachedMethodCallerNoArgs'>
            >>> a.f0.cache###line 1659:_sage_    >>> a.f0.cache
            4
            >>> sorted(dir(a))###line 1661:_sage_    >>> sorted(dir(a))
            ['__doc__', '__init__', '__module__', '_cache__f', '_x', 'f', 'f0']

        
>>> sig_on_count()
0
"""

def example_42():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Call the cached method *without* using the cache.

        INPUT:

        - ``inst`` - an instance at which the method is to be called
        - Further positional or named arguments.

        EXAMPLES::

            >>> class Foo(object):###line 1679:_sage_    >>> class Foo(object):
            ...       def __init__(self, x):
            ...           self._x = x
            ...       @cached_method
            ...       def f(self,n=Integer(2)):
            ...           return self._x**n
            ...
            >>> a = Foo(Integer(2))###line 1686:_sage_    >>> a = Foo(2)
            >>> a.f()###line 1687:_sage_    >>> a.f()
            4

        Usually, a cached method is indeed cached::

            >>> a.f() is a.f()###line 1692:_sage_    >>> a.f() is a.f()
            True

        However, when it becomes necessary, one can call it without
        using the cache. Note that ``a.f`` is an instance of
        :class:`CachedMethodCaller`.  But its
        :meth:`CachedMethodCaller._instance_call` relies on this
        method, so, we have an indirect doctest::

            >>> a.f._instance_call() is a.f() # indirect doctest###line 1701:_sage_    >>> a.f._instance_call() is a.f() # indirect doctest
            False
            >>> a.f._instance_call() == a.f()###line 1703:_sage_    >>> a.f._instance_call() == a.f()
            True

        
>>> sig_on_count()
0
"""

def example_43():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns the cache dictionary.

        TESTS::

            >>> class Foo:###line 1715:_sage_    >>> class Foo:
            ...       def __init__(self, x):
            ...           self._x = x
            ...       @cached_method
            ...       def f(self,n=Integer(2)):
            ...           return self._x**n
            ...
            >>> a = Foo(Integer(2))###line 1722:_sage_    >>> a = Foo(2)
            >>> a.f()###line 1723:_sage_    >>> a.f()
            4

        Note that we can not provide a direct test, since ``a.f`` is
        an instance of :class:`CachedMethodCaller`.  But during its
        initialisation, this method was called in order to provide the
        cached method caller with its cache, and, if possible, assign
        it to an attribute of ``a``.  So, the following is an indirect
        doctest::

            >>> a.f.get_cache()    # indirect doctest###line 1733:_sage_    >>> a.f.get_cache()    # indirect doctest
            {((2,), ()): 4}
            >>> a._cache__f###line 1735:_sage_    >>> a._cache__f
            {((2,), ()): 4}

        
>>> sig_on_count()
0
"""

def example_44():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Get a CachedMethodCaller bound to this specific instance of
        the class of the cached method.

        TESTS::

            >>> class Foo:###line 1751:_sage_    >>> class Foo:
            ...       @cached_method
            ...       def f(self):
            ...           return Integer(1)
            ...       @cached_method
            ...       def g(self, x,n=Integer(3)):
            ...           return x**n
            ...
            >>> a = Foo()###line 1759:_sage_    >>> a = Foo()
            >>> type(a.f)###line 1760:_sage_    >>> type(a.f)
            <type 'sage.misc.cachefunc.CachedMethodCallerNoArgs'>
            >>> type(a.g)###line 1762:_sage_    >>> type(a.g)
            <type 'sage.misc.cachefunc.CachedMethodCaller'>

        By trac ticket #8611, it is attempted to set the
        CachedMethodCaller as an attribute of the instance ``a``,
        replacing the original cached attribute. Therefore, the
        ``__get__`` method will be used only once, which saves much
        time. Hence, we have::

            >>> a.f is a.f###line 1771:_sage_    >>> a.f is a.f
            True
            >>> a.g is a.g###line 1773:_sage_    >>> a.g is a.g
            True

        
>>> sig_on_count()
0
"""

def example_45():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    A decorator that creates a cached version of an instance
    method of a class.

    In contrast to :class:`CachedMethod`,
    the cache dictionary is an attribute of the parent of
    the instance to which the method belongs.

    ASSUMPTION:

    This way of caching works only if

    - the instances *have* a parent, and
    - the instances are hashable (they are part of the cache key).

    NOTE:

    For proper behavior, the method must be a pure function (no side
    effects). If this decorator is used on a method, it will have
    identical output on equal elements. This is since the element is
    part of the hash key. Arguments to the method and the instance
    it is assigned to must be hashable.

    Examples can be found at :mod:`~sage.misc.cachefunc`.

    
>>> sig_on_count()
0
"""

def example_46():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Constructs a new method with cache stored in the parent of the instance.

        See also ``cached_method`` and ``cached_function``.

        EXAMPLES::

            >>> class MyParent(Parent):###line 1857:_sage_    >>> class MyParent(Parent):
            ...       pass
            >>> class Foo:###line 1859:_sage_    >>> class Foo:
            ...       def __init__(self, x):
            ...           self._x = x
            ...       _parent = MyParent()
            ...       def parent(self):
            ...           return self._parent
            ...       @cached_in_parent_method  #indirect doctest
            ...       def f(self):
            ...           return self._x**Integer(2)
            ...
            >>> a = Foo(Integer(2))###line 1869:_sage_    >>> a = Foo(2)
            >>> a.f()###line 1870:_sage_    >>> a.f()
            4
            >>> hasattr(a.parent(), '_cache__element_f')###line 1872:_sage_    >>> hasattr(a.parent(), '_cache__element_f')
            True

        For speeding up internal computations, this dictionary
        is also accessible as an attribute of the CachedMethodCaller
        (by trac ticket #8611)::

            >>> a.parent()._cache__element_f is a.f.cache###line 1879:_sage_    >>> a.parent()._cache__element_f is a.f.cache
            True
        
>>> sig_on_count()
0
"""

def example_47():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns the cache dictionary, which is stored in the parent.

        EXAMPLES::

            >>> class MyParent(Parent):###line 1891:_sage_    >>> class MyParent(Parent):
            ...       pass
            ...
            >>> class Foo:###line 1894:_sage_    >>> class Foo:
            ...       def __init__(self, x):
            ...           self._x = x
            ...       _parent = MyParent()
            ...       def parent(self):
            ...           return self._parent
            ...       def __eq__(self, other):
            ...           return self._x**Integer(2) == other._x**Integer(2)
            ...       def __hash__(self):
            ...           return hash(self._x**Integer(2))
            ...       def __repr__(self):
            ...           return 'My %s'%self._x
            ...       @cached_in_parent_method
            ...       def f(self):
            ...           return self._x**Integer(3)
            ...
            >>> a = Foo(Integer(2))###line 1910:_sage_    >>> a = Foo(2)
            >>> a.f()###line 1911:_sage_    >>> a.f()
            8
            >>> a.f.get_cache()   #indirect doctest###line 1913:_sage_    >>> a.f.get_cache()   #indirect doctest
            {(My 2, ((), ())): 8}

        Since the key for the cache depends on equality of
        the instances, we obtain *identical* result for
        *equal* instance - even though in this particular
        example the result is wrong::

            >>> b = Foo(-Integer(2))###line 1921:_sage_    >>> b = Foo(-2)
            >>> a is not b###line 1922:_sage_    >>> a is not b
            True
            >>> a == b###line 1924:_sage_    >>> a == b
            True
            >>> b.f() is a.f()###line 1926:_sage_    >>> b.f() is a.f()
            True

        Non-equal instances do not share the result of
        the cached method, but they do share the cache::

            >>> c = Foo(Integer(3))###line 1932:_sage_    >>> c = Foo(3)
            >>> c.f()###line 1933:_sage_    >>> c.f()
            27
            >>> c.f.get_cache() is a.f.get_cache() #indirect doctest###line 1935:_sage_    >>> c.f.get_cache() is a.f.get_cache() #indirect doctest
            True

        Note that the cache is also available as an
        attribute of the cached method, which speeds
        up internal computations::

            >>> a.f.cache is b.f.get_cache() is c.f._cachedmethod._get_instance_cache(c)###line 1942:_sage_    >>> a.f.cache is b.f.get_cache() is c.f._cachedmethod._get_instance_cache(c)
            True

        
>>> sig_on_count()
0
"""

def example_48():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Get a CachedMethodCaller bound to this specific instance of
        the class of the cached-in-parent method.
        
>>> sig_on_count()
0
"""

def example_49():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    FileCache is a dictionary-like class which stores keys and
    values on disk.  The keys take the form of a tuple (A,K)

    - A is a tuple of objects t where each t is an exact
      object which is uniquely identified by a short string.

    - K is a tuple of tuples (s,v) where s is a valid
      variable name and v is an exact object which is uniquely
      identified by a short string with letters [a-zA-Z0-9-._]

    The primary use case is the DiskCachedFunction.  If
    ``memory_cache == True``, we maintain a cache of objects seen
    during this session in memory -- but we don't load them from
    disk until necessary.  The keys and values are stored in a
    pair of files:

    - ``prefix-argstring.key.sobj`` contains the ``key`` only,
    - ``prefix-argstring.sobj`` contains the tuple ``(key,val)``

    where ``self[key] == val``.

    NOTE:

    We assume that each FileCache lives in its own directory.
    Use **extreme** caution if you wish to break that assumption.
    
>>> sig_on_count()
0
"""

def example_50():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2005:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir()###line 2006:_sage_    >>> dir = tmp_dir()
            >>> FC = FileCache(dir, memory_cache = True)###line 2007:_sage_    >>> FC = FileCache(dir, memory_cache = True)
            >>> FC[((),())] = Integer(1)###line 2008:_sage_    >>> FC[((),())] = 1
            >>> FC[((Integer(1),Integer(2)),())] = Integer(2)###line 2009:_sage_    >>> FC[((1,2),())] = 2
            >>> FC[((),())]###line 2010:_sage_    >>> FC[((),())]
            1
        
>>> sig_on_count()
0
"""

def example_51():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns the list of files corresponding to self.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2032:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir()###line 2033:_sage_    >>> dir = tmp_dir()
            >>> FC = FileCache(dir, memory_cache = True, prefix='t')###line 2034:_sage_    >>> FC = FileCache(dir, memory_cache = True, prefix='t')
            >>> FC[((),())] = Integer(1)###line 2035:_sage_    >>> FC[((),())] = 1
            >>> FC[((Integer(1),Integer(2)),())] = Integer(2)###line 2036:_sage_    >>> FC[((1,2),())] = 2
            >>> FC[((Integer(1),),(('a',Integer(1)),))] = Integer(3)###line 2037:_sage_    >>> FC[((1,),(('a',1),))] = 3
            >>> for f in sorted(FC.file_list()): print f[len(dir):]###line 2038:_sage_    >>> for f in sorted(FC.file_list()): print f[len(dir):]
            /t-.key.sobj
            /t-.sobj
            /t-1_2.key.sobj
            /t-1_2.sobj
            /t-a-1.1.key.sobj
            /t-a-1.1.sobj
        
>>> sig_on_count()
0
"""

def example_52():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns a list of tuples ``(k,v)`` where ``self[k] = v``.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2061:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir()###line 2062:_sage_    >>> dir = tmp_dir()
            >>> FC = FileCache(dir, memory_cache = False)###line 2063:_sage_    >>> FC = FileCache(dir, memory_cache = False)
            >>> FC[((),())] = Integer(1)###line 2064:_sage_    >>> FC[((),())] = 1
            >>> FC[((Integer(1),Integer(2)),())] = Integer(2)###line 2065:_sage_    >>> FC[((1,2),())] = 2
            >>> FC[((Integer(1),),(('a',Integer(1)),))] = Integer(3)###line 2066:_sage_    >>> FC[((1,),(('a',1),))] = 3
            >>> I = FC.items()###line 2067:_sage_    >>> I = FC.items()
            >>> I.sort(); print I###line 2068:_sage_    >>> I.sort(); print I
            [(((), ()), 1), (((1,), (('a', 1),)), 3), (((1, 2), ()), 2)]
        
>>> sig_on_count()
0
"""

def example_53():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns a list of values that are stored in ``self``.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2079:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir()###line 2080:_sage_    >>> dir = tmp_dir()
            >>> FC = FileCache(dir, memory_cache = False)###line 2081:_sage_    >>> FC = FileCache(dir, memory_cache = False)
            >>> FC[((),())] = Integer(1)###line 2082:_sage_    >>> FC[((),())] = 1
            >>> FC[((Integer(1),Integer(2)),())] = Integer(2)###line 2083:_sage_    >>> FC[((1,2),())] = 2
            >>> FC[((Integer(1),),(('a',Integer(1)),))] = Integer(3)###line 2084:_sage_    >>> FC[((1,),(('a',1),))] = 3
            >>> FC[((),(('a',Integer(1)),))] = Integer(4)###line 2085:_sage_    >>> FC[((),(('a',1),))] = 4
            >>> v = FC.values()###line 2086:_sage_    >>> v = FC.values()
            >>> v.sort(); print v###line 2087:_sage_    >>> v.sort(); print v
            [1, 2, 3, 4]
        
>>> sig_on_count()
0
"""

def example_54():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns a list of keys of ``self``.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2098:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir()###line 2099:_sage_    >>> dir = tmp_dir()
            >>> FC = FileCache(dir, memory_cache = False)###line 2100:_sage_    >>> FC = FileCache(dir, memory_cache = False)
            >>> FC[((),())] = Integer(1)###line 2101:_sage_    >>> FC[((),())] = 1
            >>> FC[((Integer(1),Integer(2)),())] = Integer(2)###line 2102:_sage_    >>> FC[((1,2),())] = 2
            >>> FC[((Integer(1),),(('a',Integer(1)),))] = Integer(3)###line 2103:_sage_    >>> FC[((1,),(('a',1),))] = 3
            >>> for k in sorted(FC): print k###line 2104:_sage_    >>> for k in sorted(FC): print k
            ((), ())
            ((1,), (('a', 1),))
            ((1, 2), ())
        
>>> sig_on_count()
0
"""

def example_55():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns a list of keys ``k`` where ``self[k]`` is defined.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2117:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir()###line 2118:_sage_    >>> dir = tmp_dir()
            >>> FC = FileCache(dir, memory_cache = False)###line 2119:_sage_    >>> FC = FileCache(dir, memory_cache = False)
            >>> FC[((),())] = Integer(1)###line 2120:_sage_    >>> FC[((),())] = 1
            >>> FC[((Integer(1),Integer(2)),())] = Integer(2)###line 2121:_sage_    >>> FC[((1,2),())] = 2
            >>> FC[((Integer(1),),(('a',Integer(1)),))] = Integer(3)###line 2122:_sage_    >>> FC[((1,),(('a',1),))] = 3
            >>> K = FC.keys()###line 2123:_sage_    >>> K = FC.keys()
            >>> K.sort(); print K###line 2124:_sage_    >>> K.sort(); print K
            [((), ()), ((1,), (('a', 1),)), ((1, 2), ())]
        
>>> sig_on_count()
0
"""

def example_56():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Computes the filename associated with a certain key.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2140:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir() + '/'###line 2141:_sage_    >>> dir = tmp_dir() + '/'
            >>> FC = FileCache(dir, memory_cache = False, prefix='foo')###line 2142:_sage_    >>> FC = FileCache(dir, memory_cache = False, prefix='foo')
            >>> N = FC._filename(((Integer(1),Integer(2)), (('a',Integer(1)),('b',Integer(2)))))###line 2143:_sage_    >>> N = FC._filename(((1,2), (('a',1),('b',2))))
            >>> print N[len(dir):]###line 2144:_sage_    >>> print N[len(dir):]
            foo-a-1_b-2.1_2
            >>> N = FC._filename(((), (('a',Integer(1)),('b',Integer(2)))))###line 2146:_sage_    >>> N = FC._filename(((), (('a',1),('b',2))))
            >>> print N[len(dir):]###line 2147:_sage_    >>> print N[len(dir):]
            foo-a-1_b-2
            >>> N = FC._filename(((Integer(1),Integer(2)), ()))###line 2149:_sage_    >>> N = FC._filename(((1,2), ()))
            >>> print N[len(dir):]###line 2150:_sage_    >>> print N[len(dir):]
            foo-1_2
        
>>> sig_on_count()
0
"""

def example_57():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns ``True`` if ``self[key]`` is defined and False otherwise.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2168:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir() + '/'###line 2169:_sage_    >>> dir = tmp_dir() + '/'
            >>> FC = FileCache(dir, memory_cache = False, prefix='foo')###line 2170:_sage_    >>> FC = FileCache(dir, memory_cache = False, prefix='foo')
            >>> k = ((),(('a',Integer(1)),))###line 2171:_sage_    >>> k = ((),(('a',1),))
            >>> FC[k] = True###line 2172:_sage_    >>> FC[k] = True
            >>> FC.has_key(k)###line 2173:_sage_    >>> FC.has_key(k)
            True
            >>> FC.has_key(((),()))###line 2175:_sage_    >>> FC.has_key(((),()))
            False
        
>>> sig_on_count()
0
"""

def example_58():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Returns the value set by ``self[key] = val``, in this session
        or a previous one.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2187:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir() + '/'###line 2188:_sage_    >>> dir = tmp_dir() + '/'
            >>> FC1 = FileCache(dir, memory_cache = False, prefix='foo')###line 2189:_sage_    >>> FC1 = FileCache(dir, memory_cache = False, prefix='foo')
            >>> FC2 = FileCache(dir, memory_cache = False, prefix='foo')###line 2190:_sage_    >>> FC2 = FileCache(dir, memory_cache = False, prefix='foo')
            >>> k = ((),(('a',Integer(1)),))###line 2191:_sage_    >>> k = ((),(('a',1),))
            >>> t = randint(Integer(0), Integer(1000))###line 2192:_sage_    >>> t = randint(0, 1000)
            >>> FC1[k] = t###line 2193:_sage_    >>> FC1[k] = t
            >>> FC2[k] == FC1[k] == t###line 2194:_sage_    >>> FC2[k] == FC1[k] == t
            True
            >>> FC1[(Integer(1),Integer(2)),(('a',Integer(4)),('b',Integer(2)))]###line 2196:_sage_    >>> FC1[(1,2),(('a',4),('b',2))]
            Traceback (most recent call last):
            ...
            KeyError: ((1, 2), (('a', 4), ('b', 2)))

        
>>> sig_on_count()
0
"""

def example_59():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Sets ``self[key] = value`` and stores both key and value on
        disk.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2228:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir() + '/'###line 2229:_sage_    >>> dir = tmp_dir() + '/'
            >>> FC1 = FileCache(dir, memory_cache = False, prefix='foo')###line 2230:_sage_    >>> FC1 = FileCache(dir, memory_cache = False, prefix='foo')
            >>> FC2 = FileCache(dir, memory_cache = False, prefix='foo')###line 2231:_sage_    >>> FC2 = FileCache(dir, memory_cache = False, prefix='foo')
            >>> k = ((),(('a',Integer(1)),))###line 2232:_sage_    >>> k = ((),(('a',1),))
            >>> t = randint(Integer(0), Integer(1000))###line 2233:_sage_    >>> t = randint(0, 1000)
            >>> FC1[k] = t###line 2234:_sage_    >>> FC1[k] = t
            >>> FC2[k] == t###line 2235:_sage_    >>> FC2[k] == t
            True
            >>> FC1[k] = Integer(2000)###line 2237:_sage_    >>> FC1[k] = 2000
            >>> FC2[k]!= t###line 2238:_sage_    >>> FC2[k]!= t
            True
        
>>> sig_on_count()
0
"""

def example_60():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        Delete the key,value pair from self and unlink the associated
        files from the file cache.

        EXAMPLES::

            >>> from sage.misc.cachefunc import FileCache###line 2257:_sage_    >>> from sage.misc.cachefunc import FileCache
            >>> dir = tmp_dir() + '/'###line 2258:_sage_    >>> dir = tmp_dir() + '/'
            >>> FC1 = FileCache(dir, memory_cache = False, prefix='foo')###line 2259:_sage_    >>> FC1 = FileCache(dir, memory_cache = False, prefix='foo')
            >>> FC2 = FileCache(dir, memory_cache = False, prefix='foo')###line 2260:_sage_    >>> FC2 = FileCache(dir, memory_cache = False, prefix='foo')
            >>> k = ((),(('a',Integer(1)),))###line 2261:_sage_    >>> k = ((),(('a',1),))
            >>> t = randint(Integer(0), Integer(1000))###line 2262:_sage_    >>> t = randint(0, 1000)
            >>> FC1[k] = t###line 2263:_sage_    >>> FC1[k] = t
            >>> del FC2[k]###line 2264:_sage_    >>> del FC2[k]
            >>> FC1.has_key(k)###line 2265:_sage_    >>> FC1.has_key(k)
            False
       
>>> sig_on_count()
0
"""

def example_61():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    Works similar to CachedFunction, but instead, we keep the
    cache on disk (optionally, we keep it in memory too).

    EXAMPLES::

        >>> from sage.misc.cachefunc import DiskCachedFunction###line 2285:_sage_    >>> from sage.misc.cachefunc import DiskCachedFunction
        >>> dir = tmp_dir()###line 2286:_sage_    >>> dir = tmp_dir()
        >>> factor = DiskCachedFunction(factor, dir, memory_cache=True)###line 2287:_sage_    >>> factor = DiskCachedFunction(factor, dir, memory_cache=True)
        >>> f = factor(Integer(2775)); f###line 2288:_sage_    >>> f = factor(2775); f
        3 * 5^2 * 37
        >>> f is factor(Integer(2775))###line 2290:_sage_    >>> f is factor(2775)
        True
    
>>> sig_on_count()
0
"""

def example_62():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        EXAMPLES::

            >>> from sage.misc.cachefunc import DiskCachedFunction###line 2297:_sage_    >>> from sage.misc.cachefunc import DiskCachedFunction
            >>> def foo(x): sleep(x)###line 2298:_sage_    >>> def foo(x): sleep(x)
            >>> dir = tmp_dir()###line 2299:_sage_    >>> dir = tmp_dir()
            >>> bar = DiskCachedFunction(foo, dir, memory_cache = False)###line 2300:_sage_    >>> bar = DiskCachedFunction(foo, dir, memory_cache = False)
            >>> w = walltime()###line 2301:_sage_    >>> w = walltime()
            >>> for i in range(Integer(10)): bar(Integer(1))###line 2302:_sage_    >>> for i in range(10): bar(1)
            >>> walltime(w) < Integer(2)###line 2303:_sage_    >>> walltime(w) < 2
            True
        
>>> sig_on_count()
0
"""

def example_63():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    Decorator for :class:`DiskCachedFunction`.

    EXAMPLES::

        >>> dir = tmp_dir()###line 2317:_sage_    >>> dir = tmp_dir()
        >>> @disk_cached_function(dir)###line 2318:_sage_    >>> @disk_cached_function(dir)
        ... def foo(x): return next_prime(Integer(2)**x)%x
        >>> x = foo(Integer(200));x###line 2320:_sage_    >>> x = foo(200);x
        11
        >>> @disk_cached_function(dir)###line 2322:_sage_    >>> @disk_cached_function(dir)
        ... def foo(x): return Integer(1)/x
        >>> foo(Integer(200))###line 2324:_sage_    >>> foo(200)
        11
        >>> foo.clear_cache()###line 2326:_sage_    >>> foo.clear_cache()
        >>> foo(Integer(200))###line 2327:_sage_    >>> foo(200)
        1/200
    
>>> sig_on_count()
0
"""

def example_64():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        EXAMPLES::

            >>> dir = tmp_dir()###line 2334:_sage_    >>> dir = tmp_dir()
            >>> @disk_cached_function(dir, memory_cache=True)###line 2335:_sage_    >>> @disk_cached_function(dir, memory_cache=True)
            ... def foo(x): return next_prime(Integer(2)**x)
            >>> x = foo(Integer(200))###line 2337:_sage_    >>> x = foo(200)
            >>> x is foo(Integer(200))###line 2338:_sage_    >>> x is foo(200)
            True
            >>> @disk_cached_function(dir, memory_cache=False)###line 2340:_sage_    >>> @disk_cached_function(dir, memory_cache=False)
            ... def foo(x): return next_prime(Integer(2)**x)
            >>> x is foo(Integer(200))###line 2342:_sage_    >>> x is foo(200)
            False
        
>>> sig_on_count()
0
"""

def example_65():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        EXAMPLES::

            >>> dir = tmp_dir()###line 2352:_sage_    >>> dir = tmp_dir()
            >>> @disk_cached_function(dir)###line 2353:_sage_    >>> @disk_cached_function(dir)
            ... def foo(x): return ModularSymbols(x)
            >>> foo(Integer(389))###line 2355:_sage_    >>> foo(389)
            Modular Symbols space of dimension 65 for Gamma_0(389) of weight 2 with sign 0 over Rational Field
        
>>> sig_on_count()
0
"""

def example_66():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


    This class implements an appropriate ``__getstate__`` method that
    clears the cache of the methods (see @cached_method) before
    passing them on to the caller, typically the pickle and copy modules.

    The implemented ``__getstate__`` method calls the ``__getstate__``
    methods of classes later in the method resolution
    order. Therefore, classes which want this behaviour should inherit
    first from this one.

    EXAMPLE:

    In the following example, we create a Python class that inherits
    from multivariate polynomial ideals, but does not pickle cached
    values.  We provide the definition in Cython, however, since
    interactive Cython definitions provide introspection by trac
    ticket #9976, whereas Python definitions don't.
    ::

        >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 2380:_sage_    >>> P.<a,b,c,d> = QQ[]
        >>> I = P*[a,b]###line 2381:_sage_    >>> I = P*[a,b]
        >>> classdef = ['from sage.misc.cachefunc import ClearCacheOnPickle',###line 2382:_sage_    >>> classdef = ['from sage.misc.cachefunc import ClearCacheOnPickle',
        ...    'from sage.all import QQ',
        ...    'P = QQ["a","b","c","d"]; I = P*[P.gen(0),P.gen(1)]',
        ...    'class MyClass(ClearCacheOnPickle,I.__class__):',
        ...    '    def __init__(self,ring,gens):',
        ...    '        I.__class__.__init__(self,ring,gens)',
        ...    '    def __getnewargs__(self):',
        ...    '        return (self._Ideal_generic__ring,self._Ideal_generic__gens)']
        >>> cython('\n'.join(classdef))###line 2390:_sage_    >>> cython('\n'.join(classdef))

    We destroy the cache of two methods of ``I`` on purpose
    (demonstrating that the two different implementations of cached
    methods are correctly dealt with).  Pickling ``I`` preserves the
    cache::

        >>> I.gens.set_cache('bar')###line 2397:_sage_    >>> I.gens.set_cache('bar')
        >>> I.groebner_basis.set_cache('foo',algorithm='singular')###line 2398:_sage_    >>> I.groebner_basis.set_cache('foo',algorithm='singular')
        >>> J = loads(dumps(I))###line 2399:_sage_    >>> J = loads(dumps(I))
        >>> J.gens()###line 2400:_sage_    >>> J.gens()
        'bar'
        >>> J.groebner_basis(algorithm='singular')###line 2402:_sage_    >>> J.groebner_basis(algorithm='singular')
        'foo'

    However, if we have an ideal that additionally descends from
    :class:`ClearCacheOnPickle`, the carefully corrupted cache is not
    pickled::

        >>> A = MyClass(P,[a,b])###line 2409:_sage_    >>> A = MyClass(P,[a,b])
        >>> A###line 2410:_sage_    >>> A
        Ideal (a, b) of Multivariate Polynomial Ring in a, b, c, d over Rational Field
        >>> A.gens.set_cache('foo')###line 2412:_sage_    >>> A.gens.set_cache('foo')
        >>> A.groebner_basis.set_cache('bar',algorithm='singular')###line 2413:_sage_    >>> A.groebner_basis.set_cache('bar',algorithm='singular')
        >>> A.gens()###line 2414:_sage_    >>> A.gens()
        'foo'
        >>> A.groebner_basis(algorithm='singular')###line 2416:_sage_    >>> A.groebner_basis(algorithm='singular')
        'bar'
        >>> B = loads(dumps(A))###line 2418:_sage_    >>> B = loads(dumps(A))
        >>> B.gens()###line 2419:_sage_    >>> B.gens()
        [a, b]
        >>> B.groebner_basis(algorithm='singular')###line 2421:_sage_    >>> B.groebner_basis(algorithm='singular')
        [a, b]
        >>> A.gens()###line 2423:_sage_    >>> A.gens()
        'foo'

    
>>> sig_on_count()
0
"""

def example_67():       r""">>> set_random_seed(0L)

>>> change_warning_output(sys.stdout)


        The idea is to remove that might provide a cache to some cached method
        from the return value of the ``__getstate__`` method.

        EXAMPLE:

        In the following example, we create a Python class that
        inherits from multivariate polynomial ideals, but clears the
        cache as well.

            >>> P = QQ['a, b, c, d']; (a, b, c, d,) = P._first_ngens(4)###line 2438:_sage_    >>> P.<a,b,c,d> = QQ[]
            >>> I = P*[a,b]###line 2439:_sage_    >>> I = P*[a,b]

        We destroy the cache of two methods if ``I`` on purpose
        (demonstrating that the two different implementations of cached
        methods are correctly dealt with).  Pickling ``I`` preserves the
        cache::

            >>> I.gens.set_cache('bar')###line 2446:_sage_    >>> I.gens.set_cache('bar')
            >>> I.groebner_basis.set_cache('foo',algorithm='singular')###line 2447:_sage_    >>> I.groebner_basis.set_cache('foo',algorithm='singular')
            >>> J = loads(dumps(I))###line 2448:_sage_    >>> J = loads(dumps(I))
            >>> J.gens()###line 2449:_sage_    >>> J.gens()
            'bar'
            >>> J.groebner_basis(algorithm='singular')###line 2451:_sage_    >>> J.groebner_basis(algorithm='singular')
            'foo'

        However, if we do the same with a class that additionally
        descends from :class:`ClearCacheOnPickle`, the cache is not
        pickled. We provide the definition in Cython, however, since
        interactive Cython definitions provide introspection by trac
        ticket #9976, whereas Python definitions don't.
        ::

            >>> classdef = ['from sage.misc.cachefunc import ClearCacheOnPickle',###line 2461:_sage_    >>> classdef = ['from sage.misc.cachefunc import ClearCacheOnPickle',
            ...    'from sage.all import QQ',
            ...    'from sage.rings.polynomial.multi_polynomial_ideal import MPolynomialIdeal',
            ...    'class MyClass(ClearCacheOnPickle,MPolynomialIdeal):',
            ...    '    def __init__(self,ring,gens):',
            ...    '        MPolynomialIdeal.__init__(self,ring,gens)',
            ...    '    def __getnewargs__(self):',
            ...    '        return (self._Ideal_generic__ring,self._Ideal_generic__gens)']
            >>> cython('\n'.join(classdef))###line 2469:_sage_    >>> cython('\n'.join(classdef))
            >>> A = MyClass(P,[a,b])###line 2470:_sage_    >>> A = MyClass(P,[a,b])
            >>> A###line 2471:_sage_    >>> A
            Ideal (a, b) of Multivariate Polynomial Ring in a, b, c, d over Rational Field
            >>> A.gens.set_cache('foo')###line 2473:_sage_    >>> A.gens.set_cache('foo')
            >>> A.groebner_basis.set_cache('bar',algorithm='singular')###line 2474:_sage_    >>> A.groebner_basis.set_cache('bar',algorithm='singular')
            >>> A.gens()###line 2475:_sage_    >>> A.gens()
            'foo'
            >>> A.groebner_basis(algorithm='singular')###line 2477:_sage_    >>> A.groebner_basis(algorithm='singular')
            'bar'
            >>> B = loads(dumps(A))###line 2479:_sage_    >>> B = loads(dumps(A))
            >>> B.gens()###line 2480:_sage_    >>> B.gens()
            [a, b]
            >>> B.groebner_basis(algorithm='singular')###line 2482:_sage_    >>> B.groebner_basis(algorithm='singular')
            [a, b]
            >>> A.gens()###line 2484:_sage_    >>> A.gens()
            'foo'

        And here is why the example works::

            >>> ST = I.__getstate__(); ST[Integer(0)],sorted(ST[Integer(1)].items())###line 2489:_sage_    >>> ST = I.__getstate__(); ST[0],sorted(ST[1].items())
            (Monoid of ideals of Multivariate Polynomial Ring in a, b, c, d over Rational Field, [('_Ideal_generic__gens', (a, b)), ('_Ideal_generic__ring', Multivariate Polynomial Ring in a, b, c, d over Rational Field), ('_cache__groebner_basis', {(('singular', None, None, False), ()): 'foo'}), ('gens', Cached version of <function gens at 0x...>), ('groebner_basis', Cached version of <function groebner_basis at 0x...>)])
            >>> ST = A.__getstate__(); ST[Integer(0)],sorted(ST[Integer(1)].items())###line 2491:_sage_    >>> ST = A.__getstate__(); ST[0],sorted(ST[1].items())
            (Monoid of ideals of Multivariate Polynomial Ring in a, b, c, d over Rational Field, [('_Ideal_generic__gens', (a, b)), ('_Ideal_generic__ring', Multivariate Polynomial Ring in a, b, c, d over Rational Field)])

        
>>> sig_on_count()
0
"""


if __name__ ==  '__main__':
    verbose = False
    do_timeit = False
    output_filename = '/scratch/sking/sage-5.4.beta0/devel/sage-main/sage/misc/cachefunc.pyx.timeit.sobj'

    import sys
    sys.path = sys.path + ['/scratch/sking/sage-5.4.beta0/local/bin']
    import sagedoctest

    # execfile('/scratch/sking/sage-5.4.beta0/devel/sage-main/sage/misc/cachefunc.pyx')
    m = sys.modules[__name__]
    m.__file__ = '/scratch/sking/sage-5.4.beta0/devel/sage-main/sage/misc/cachefunc.pyx'

    try:

        # configure special sage doc test runner
        runner = sagedoctest.SageDocTestRunner(checker=None, verbose=verbose, optionflags=0)
        runner._collect_timeit_stats = do_timeit
        runner._reset_random_seed = True

        runner = sagedoctest.testmod_returning_runner(m,
                       # filename='/scratch/sking/sage-5.4.beta0/devel/sage-main/sage/misc/cachefunc.pyx',
                       verbose=verbose,
                       globs=globals(),
                       runner=runner)
        runner.save_timeit_stats_to_file_named(output_filename)
    except:
        quit_sage(verbose=False)
        import traceback
        traceback.print_exc(file=sys.stdout)
        sys.exit(255)
    quit_sage(verbose=False)
    if runner.failures > 254:
        sys.exit(254)
    sys.exit(runner.failures)