gh-41169: Type annotations and stubs for cachefunc
    
Added missing stubs to `src/sage/misc/cachefunc.pyi` and annotations to
`src/sage/misc/cachefunc.pyx`. This should fix some of the warnings when
running `pyright` or `mypy` about not being able to import
`cached_method` or `cached_function`.

Also changed the default value of `do_pickle` from `None` to `False`.
The behaviour of `None` was the same as the behaviour of `False`, so
this simplifies the code (and the the added type annotations) with no
change to behaviour.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation and checked the documentation
preview.
    
URL: #41169
Reported by: Vincent Macri
Reviewer(s): Chenxin Zhong, Vincent Macri

Author: Release Manager

src/sage/misc/cachefunc.pyi

@@ -7,10 +7,16 @@ def dict_key(o: Any) -> Any:
 def cache_key(o: Any) -> Any:
     ...
 
+def cached_method(f, name: str | None = None, key=None, do_pickle: bool = False) -> CachedMethod:
+    ...
+
+def cached_function(f, name: str | None = None, key=None, do_pickle: bool = False) -> CachedFunction:
+    ...
+
 class CachedFunction:
     def __init__(self, f: Callable, classmethod: bool = False,
                  name: str | None = None, key: Callable | None = None,
-                 do_pickle: bool | None = None) -> None:
+                 do_pickle: bool = False) -> None:
         ...
 
     def __call__(self, *args: Any, **kwds: Any) -> Any:
@@ -40,7 +46,7 @@ class CachedFunction:
 class CachedMethod:
     def __init__(self, f: Callable, name: str | None = None,
                  key: Callable | None = None,
-                 do_pickle: bool | None = None) -> None:
+                 do_pickle: bool = False) -> None:
         ...
 
     def __call__(self, inst: Any, *args: Any, **kwds: Any) -> Any:
@@ -58,7 +64,7 @@ class CacheDict(dict):
 class CachedInParentMethod(CachedMethod):
     def __init__(self, f: Callable, name: str | None = None,
                  key: Callable | None = None,
-                 do_pickle: bool | None = None) -> None:
+                 do_pickle: bool = False) -> None:
         ...
 
     def _get_instance_cache(self, inst: Any) -> dict:
@@ -71,7 +77,7 @@ class CachedMethodCaller(CachedFunction):
     def __init__(self, cachedmethod: CachedMethod, inst: Any,
                  cache: dict | None = None, name: str | None = None,
                  key: Callable | None = None,
-                 do_pickle: bool | None = None) -> None:
+                 do_pickle: bool = False) -> None:
         ...
 
     def _instance_call(self, *args: Any, **kwds: Any) -> Any:
@@ -92,7 +98,7 @@ class CachedMethodCaller(CachedFunction):
 class CachedMethodCallerNoArgs(CachedFunction):
     def __init__(self, inst: Any, f: Callable, cache: Any = None,
                  name: str | None = None,
-                 do_pickle: bool | None = None) -> None:
+                 do_pickle: bool = False) -> None:
         ...
 
     def _instance_call(self) -> Any:

src/sage/misc/cachefunc.pyx

@@ -449,9 +449,11 @@ cdef extern from "methodobject.h":
     cdef int METH_NOARGS, METH_O
     cdef int PyCFunction_GetFlags(object op) except -1
 
+from collections.abc import Iterator
+from inspect import isfunction
 import os
+
 from sage.misc.sageinspect import sage_getfile_relative, sage_getsourcelines, sage_getargspec
-from inspect import isfunction
 
 from sage.misc.weak_dict cimport CachedWeakValueDictionary
 from sage.misc.decorators import decorator_keywords
@@ -696,7 +698,7 @@ cdef class CachedFunction():
         sage: mul(1,1,algorithm='default') is mul(1,1,algorithm='algorithm') is mul(1,1) is mul(1,1,'default')
         True
     """
-    def __init__(self, f, *, classmethod=False, name=None, key=None, do_pickle=None):
+    def __init__(self, f, *, classmethod=False, name: str | None = None, key=None, do_pickle: bool = False) -> None:
         """
         Create a cached version of a function, which only recomputes
         values it hasn't already computed. A custom name can be
@@ -769,7 +771,7 @@ cdef class CachedFunction():
         self._common_init(f, None, name=name, key=key, do_pickle=do_pickle)
         self.cache = {} if do_pickle else NonpicklingDict()
 
-    def _common_init(self, f, argument_fixer, name=None, key=None, do_pickle=None):
+    def _common_init(self, f, argument_fixer, name: str | None = None, key=None, do_pickle: bool = False) -> None:
         """
         Perform initialization common to CachedFunction and CachedMethodCaller.
 
@@ -798,7 +800,7 @@ cdef class CachedFunction():
             self._argument_fixer = argument_fixer
 
     @property
-    def __module__(self):
+    def __module__(self) -> str:
         return self.__cached_module__
 
     cdef get_key_args_kwds(self, tuple args, dict kwds):
@@ -1451,7 +1453,7 @@ cdef class WeakCachedFunction(CachedFunction):
         sage: f.is_in_cache(t)
         True
     """
-    def __init__(self, f, *, classmethod=False, name=None, key=None, **kwds):
+    def __init__(self, f, *, classmethod=False, name: str | None = None, key=None, **kwds) -> None:
         """
         The inputs to the function must be hashable or they must define
         :meth:`sage.structure.sage_object.SageObject._cache_key`.
@@ -1580,7 +1582,7 @@ class CachedMethodPickle():
 
     - Simon King (2011-01)
     """
-    def __init__(self, inst, name, cache=None):
+    def __init__(self, inst, name, cache=None) -> None:
         """
         INPUT:
 
@@ -1767,7 +1769,7 @@ cdef class CachedMethodCaller(CachedFunction):
         sage: len(b.bar.cache)
         1
     """
-    def __init__(self, CachedMethod cachedmethod, inst, *, cache=None, name=None, key=None, do_pickle=None):
+    def __init__(self, CachedMethod cachedmethod, inst, *, cache=None, name: str | None = None, key=None, do_pickle: bool = False) -> None:
         """
         EXAMPLES::
 
@@ -2244,7 +2246,7 @@ cdef class CachedMethodCallerNoArgs(CachedFunction):
 
     - Simon King (2011-04)
     """
-    def __init__(self, inst, f, cache=None, name=None, do_pickle=None):
+    def __init__(self, inst, f, cache=None, name: str | None = None, do_pickle: bool = False):
         """
         EXAMPLES::
 
@@ -2657,7 +2659,7 @@ cdef class CachedMethod():
         sage: b.f()
         1
     """
-    def __init__(self, f, name=None, key=None, do_pickle=None):
+    def __init__(self, f, name: str | None = None, key=None, do_pickle: bool = False) -> None:
         """
         EXAMPLES::
 
@@ -2728,7 +2730,7 @@ cdef class CachedMethod():
         self.__cached_module__ = self._cachedfunc.__module__
 
     @property
-    def __module__(self):
+    def __module__(self) -> str:
         return self.__cached_module__
 
     def __call__(self, inst, *args, **kwds):
@@ -3065,9 +3067,8 @@ cdef class CachedSpecialMethod(CachedMethod):
             D[name] = Caller
         return Caller
 
-
 @decorator_keywords
-def cached_method(f, name=None, key=None, do_pickle=None):
+def cached_method(f, name: str | None = None, key=None, do_pickle: bool = False) -> CachedMethod:
     """
     A decorator for cached methods.
 
@@ -3193,7 +3194,7 @@ cdef class CachedInParentMethod(CachedMethod):
     Examples can be found at :mod:`~sage.misc.cachefunc`.
     """
 
-    def __init__(self, f, name=None, key=None, do_pickle=None):
+    def __init__(self, f, name: str | None = None, key=None, do_pickle: bool = False) -> None:
         """
         Construct a new method with cache stored in the parent of the instance.
 
@@ -3359,7 +3360,7 @@ cdef class CachedInParentMethod(CachedMethod):
             P._cached_methods = {}
         return (<dict>P._cached_methods).setdefault(self._cache_name, default)
 
-    def __get__(self, inst, cls):
+    def __get__(self, inst, cls) -> GloballyCachedMethodCaller:
         """
         Get a CachedMethodCaller bound to this specific instance of
         the class of the cached-in-parent method.
@@ -3403,7 +3404,7 @@ class FileCache():
         We assume that each :class:`FileCache` lives in its own directory.
         Use **extreme** caution if you wish to break that assumption.
     """
-    def __init__(self, dir, prefix='', memory_cache=False):
+    def __init__(self, dir, prefix='', memory_cache=False) -> None:
         """
         EXAMPLES::
 
@@ -3427,7 +3428,7 @@ class FileCache():
         else:
             self._cache = None
 
-    def file_list(self):
+    def file_list(self) -> list[str]:
         """
         Return the list of files corresponding to ``self``.
 
@@ -3456,7 +3457,7 @@ class FileCache():
                 files.append(dir + f)
         return files
 
-    def items(self):
+    def items(self) -> list[tuple[Any, Any]]:
         """
         Return a list of tuples ``(k,v)`` where ``self[k] = v``.
 
@@ -3474,7 +3475,7 @@ class FileCache():
         """
         return [(k, self[k]) for k in self]
 
-    def values(self):
+    def values(self) -> list:
         """
         Return a list of values that are stored in ``self``.
 
@@ -3493,7 +3494,7 @@ class FileCache():
         """
         return [self[k] for k in self]
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator:
         """
         Return a list of keys of ``self``.
 
@@ -3512,7 +3513,7 @@ class FileCache():
         """
         return iter(self.keys())
 
-    def keys(self):
+    def keys(self) -> list:
         """
         Return a list of keys ``k`` where ``self[k]`` is defined.
 
@@ -3535,7 +3536,7 @@ class FileCache():
                 K.append(load(f))
         return K
 
-    def clear(self):
+    def clear(self) -> None:
         """
         Clear all key, value pairs from ``self`` and unlink the associated files
         from the file cache.
@@ -3561,7 +3562,7 @@ class FileCache():
         for k in self:
             del self[k]
 
-    def _filename(self, key):
+    def _filename(self, key) -> str:
         """
         Compute the filename associated with a certain key.
 
@@ -3589,7 +3590,7 @@ class FileCache():
             keystr = kwdstr + argstr
         return self._dir + self._prefix + keystr
 
-    def __contains__(self, key):
+    def __contains__(self, key) -> bool:
         """
         Return ``True`` if ``self[key]`` is defined and ``False`` otherwise.
 
@@ -3647,7 +3648,7 @@ class FileCache():
             cache[key] = v
         return v
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key, value) -> None:
         """
         Set ``self[key] = value`` and stores both key and value on
         disk.
@@ -3676,7 +3677,7 @@ class FileCache():
         if self._cache is not None:
             self._cache[key] = value
 
-    def __delitem__(self, key):
+    def __delitem__(self, key) -> None:
         """
         Delete the ``key, value`` pair from ``self`` and unlink the associated
         files from the file cache.
@@ -3719,7 +3720,7 @@ class DiskCachedFunction(CachedFunction):
         sage: f is factor(2775)
         True
     """
-    def __init__(self, f, dir, memory_cache=False, key=None):
+    def __init__(self, f, dir, memory_cache=False, key=None) -> None:
         """
         EXAMPLES::
 
@@ -3756,7 +3757,7 @@ class disk_cached_function:
         sage: foo(200)
         1/200
     """
-    def __init__(self, dir, memory_cache=False, key=None):
+    def __init__(self, dir, memory_cache=False, key=None) -> None:
         """
         EXAMPLES::
 
@@ -3775,7 +3776,7 @@ class disk_cached_function:
         self._memory_cache = memory_cache
         self._key = key
 
-    def __call__(self, f):
+    def __call__(self, f) -> DiskCachedFunction:
         """
         EXAMPLES::
 

src/sage/misc/decorators.py

@@ -25,15 +25,12 @@
 #                  http://www.gnu.org/licenses/
 # *****************************************************************************
 
-from functools import (partial, update_wrapper, WRAPPER_ASSIGNMENTS,
-                       WRAPPER_UPDATES)
 from copy import copy
-
-from sage.misc.sageinspect import (sage_getsource, sage_getsourcelines,
-                                   sage_getargspec)
-
+from functools import WRAPPER_ASSIGNMENTS, WRAPPER_UPDATES, partial, update_wrapper
 from inspect import FullArgSpec
 
+from sage.misc.sageinspect import sage_getargspec, sage_getsource, sage_getsourcelines
+
 
 def sage_wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES):
     r"""