TYP: CallableDynamicDoc (#46786)

* TYP: CallableDynamicDoc

* using cast

* tighten NDFrameIndexerBase

* dtype and clarification for _IndexingMixinT

Co-authored-by: Matthew Roeschke <[email protected]>

Author: twoertwein

pandas/_config/config.py

@@ -58,13 +58,17 @@
 from typing import (
     Any,
     Callable,
+    Generic,
     Iterable,
     NamedTuple,
     cast,
 )
 import warnings
 
-from pandas._typing import F
+from pandas._typing import (
+    F,
+    T,
+)
 
 
 class DeprecatedOption(NamedTuple):
@@ -124,7 +128,7 @@ def _get_single_key(pat: str, silent: bool) -> str:
     return key
 
 
-def _get_option(pat: str, silent: bool = False):
+def _get_option(pat: str, silent: bool = False) -> Any:
     key = _get_single_key(pat, silent)
 
     # walk the nested dict
@@ -164,7 +168,7 @@ def _set_option(*args, **kwargs) -> None:
                 o.cb(key)
 
 
-def _describe_option(pat: str = "", _print_desc: bool = True):
+def _describe_option(pat: str = "", _print_desc: bool = True) -> str | None:
 
     keys = _select_options(pat)
     if len(keys) == 0:
@@ -174,8 +178,8 @@ def _describe_option(pat: str = "", _print_desc: bool = True):
 
     if _print_desc:
         print(s)
-    else:
-        return s
+        return None
+    return s
 
 
 def _reset_option(pat: str, silent: bool = False) -> None:
@@ -247,16 +251,17 @@ def __dir__(self) -> Iterable[str]:
 # of options, and option descriptions.
 
 
-class CallableDynamicDoc:
-    def __init__(self, func, doc_tmpl) -> None:
+class CallableDynamicDoc(Generic[T]):
+    def __init__(self, func: Callable[..., T], doc_tmpl: str) -> None:
         self.__doc_tmpl__ = doc_tmpl
         self.__func__ = func
 
-    def __call__(self, *args, **kwds):
+    def __call__(self, *args, **kwds) -> T:
         return self.__func__(*args, **kwds)
 
+    # error: Signature of "__doc__" incompatible with supertype "object"
     @property
-    def __doc__(self):
+    def __doc__(self) -> str:  # type: ignore[override]
         opts_desc = _describe_option("all", _print_desc=False)
         opts_list = pp_options_list(list(_registered_options.keys()))
         return self.__doc_tmpl__.format(opts_desc=opts_desc, opts_list=opts_list)

pandas/_libs/indexing.pyi

@@ -0,0 +1,17 @@
+from typing import (
+    Generic,
+    TypeVar,
+)
+
+from pandas.core.indexing import IndexingMixin
+
+_IndexingMixinT = TypeVar("_IndexingMixinT", bound=IndexingMixin)
+
+class NDFrameIndexerBase(Generic[_IndexingMixinT]):
+    name: str
+    # in practise obj is either a DataFrame or a Series
+    obj: _IndexingMixinT
+
+    def __init__(self, name: str, obj: _IndexingMixinT) -> None: ...
+    @property
+    def ndim(self) -> int: ...

pandas/_libs/json.pyi

@@ -0,0 +1,23 @@
+from typing import (
+    Any,
+    Callable,
+)
+
+def dumps(
+    obj: Any,
+    ensure_ascii: bool = ...,
+    double_precision: int = ...,
+    indent: int = ...,
+    orient: str = ...,
+    date_unit: str = ...,
+    iso_dates: bool = ...,
+    default_handler: None
+    | Callable[[Any], str | int | float | bool | list | dict | None] = ...,
+) -> str: ...
+def loads(
+    s: str,
+    precise_float: bool = ...,
+    numpy: bool = ...,
+    dtype: None = ...,
+    labelled: bool = ...,
+) -> Any: ...

pandas/_libs/reduction.pyi

@@ -0,0 +1,8 @@
+from typing import Any
+
+import numpy as np
+
+from pandas._typing import ExtensionDtype
+
+def check_result_array(obj: object, dtype: np.dtype | ExtensionDtype) -> None: ...
+def extract_result(res: object) -> Any: ...

pandas/core/indexing.py

@@ -5,6 +5,7 @@
     TYPE_CHECKING,
     Hashable,
     Sequence,
+    cast,
     final,
 )
 import warnings
@@ -629,6 +630,9 @@ class _LocationIndexer(NDFrameIndexerBase):
     _valid_types: str
     axis: int | None = None
 
+    # sub-classes need to set _takeable
+    _takeable: bool
+
     @final
     def __call__(self, axis=None):
         # we need to return a copy of ourselves
@@ -924,7 +928,9 @@ def _getitem_lowerdim(self, tup: tuple):
             #  is equivalent.
             #  (see the other place where we call _handle_lowerdim_multi_index_axis0)
             with suppress(IndexingError):
-                return self._handle_lowerdim_multi_index_axis0(tup)
+                # error "_LocationIndexer" has no attribute
+                # "_handle_lowerdim_multi_index_axis0"
+                return cast(_LocIndexer, self)._handle_lowerdim_multi_index_axis0(tup)
 
         tup = self._validate_key_length(tup)
 
@@ -980,7 +986,11 @@ def _getitem_nested_tuple(self, tup: tuple):
                 #  DataFrame, IndexingError is not raised when slice(None,None,None)
                 #  with one row.
                 with suppress(IndexingError):
-                    return self._handle_lowerdim_multi_index_axis0(tup)
+                    # error "_LocationIndexer" has no attribute
+                    # "_handle_lowerdim_multi_index_axis0"
+                    return cast(_LocIndexer, self)._handle_lowerdim_multi_index_axis0(
+                        tup
+                    )
             elif isinstance(self.obj, ABCSeries) and any(
                 isinstance(k, tuple) for k in tup
             ):
@@ -2303,6 +2313,9 @@ class _ScalarAccessIndexer(NDFrameIndexerBase):
     Access scalars quickly.
     """
 
+    # sub-classes need to set _takeable
+    _takeable: bool
+
     def _convert_key(self, key):
         raise AbstractMethodError(self)
 

pandas/io/sas/_sas.pyi

@@ -0,0 +1,5 @@
+from pandas.io.sas.sas7bdat import SAS7BDATReader
+
+class Parser:
+    def __init__(self, parser: SAS7BDATReader) -> None: ...
+    def read(self, nrows: int) -> None: ...