memo and singleton decorator annotations (streamlit#4045)

Adds type annotations to `@st.experimental_memo` and `@st.experimental_singleton`.

This means that running mypy on a Streamlit app should catch incorrect usage of a cached function, e.g.

```python
import streamlit as st

@st.experimental_memo
def foo(value: int) -> None:
  st.write(value * 2)

foo("bar")  # this is now a mypy error, whereas before it was not
```

This changes the signatures for memo + singleton _ever so slightly_, in that it makes all "decorator arguments" into keyword-only args. It was previously legal to pass them positionally. I think this is ok because (1) we're still experimental and (2) in practice it's unlikely people were passing these parameters positionally anyway.

lib/streamlit/caching/memo_decorator.py

@@ -19,7 +19,7 @@
 import threading
 import time
 import types
-from typing import Optional, Any, Dict, cast, List
+from typing import Optional, Any, Dict, cast, List, Callable, TypeVar, overload
 from typing import Union
 
 import math
@@ -197,8 +197,33 @@ def get_function_cache(self, function_key: str) -> Cache:
         )
 
 
+# Type-annotate the decorator.
+# (See https://mypy.readthedocs.io/en/stable/generics.html#decorator-factories)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Bare decorator usage
+@overload
+def memo(func: F) -> F:
+    ...
+
+
+# Decorator with arguments
+@overload
+def memo(
+    *,
+    persist: Optional[str] = None,
+    show_spinner: bool = True,
+    suppress_st_warning=False,
+    max_entries: Optional[int] = None,
+    ttl: Optional[float] = None,
+) -> Callable[[F], F]:
+    ...
+
+
 def memo(
-    func: Optional[types.FunctionType] = None,
+    func: Optional[F] = None,
+    *,
     persist: Optional[str] = None,
     show_spinner: bool = True,
     suppress_st_warning=False,
@@ -307,7 +332,7 @@ def memo(
 
     return create_cache_wrapper(
         MemoizedFunction(
-            func=func,
+            func=cast(types.FunctionType, func),
             persist=persist,
             show_spinner=show_spinner,
             suppress_st_warning=suppress_st_warning,

lib/streamlit/caching/singleton_decorator.py

@@ -16,7 +16,7 @@
 
 import threading
 import types
-from typing import Optional, Any, Dict, List
+from typing import Optional, Any, Dict, List, TypeVar, Callable, overload, cast
 
 from pympler import asizeof
 
@@ -111,8 +111,30 @@ def get_function_cache(self, function_key: str) -> Cache:
         )
 
 
+# Type-annotate the decorator.
+# (See https://mypy.readthedocs.io/en/stable/generics.html#decorator-factories)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Bare decorator usage
+@overload
+def singleton(func: F) -> F:
+    ...
+
+
+# Decorator with arguments
+@overload
+def singleton(
+    *,
+    show_spinner: bool = True,
+    suppress_st_warning=False,
+) -> Callable[[F], F]:
+    ...
+
+
 def singleton(
-    func: Optional[types.FunctionType] = None,
+    func: Optional[F] = None,
+    *,
     show_spinner: bool = True,
     suppress_st_warning=False,
 ):
@@ -189,7 +211,7 @@ def singleton(
 
     return create_cache_wrapper(
         SingletonFunction(
-            func=func,
+            func=cast(types.FunctionType, func),
             show_spinner=show_spinner,
             suppress_st_warning=suppress_st_warning,
         )