Merge pull request #18842 from BvB93/placeholder_main

ENH: Improve the placeholder annotations within sub-modules

9 files changed, 372 insertions, 151 deletions

diff --git a/numpy/__init__.pyi b/numpy/__init__.pyi
index 08050a524..6899343c0 100644
--- a/numpy/__init__.pyi
+++ b/numpy/__init__.pyi
@@ -408,7 +408,47 @@ class chararray(ndarray[_ShapeType, _DType_co]):
         strides: Any = ...,
         order: Any = ...,
     ) -> Any: ...
-    def __getattr__(self, key: str) -> Any: ...
+    def __array_finalize__(self, obj): ...
+    def argsort(self, axis=..., kind=..., order=...): ...
+    def capitalize(self): ...
+    def center(self, width, fillchar=...): ...
+    def count(self, sub, start=..., end=...): ...
+    def decode(self, encoding=..., errors=...): ...
+    def encode(self, encoding=..., errors=...): ...
+    def endswith(self, suffix, start=..., end=...): ...
+    def expandtabs(self, tabsize=...): ...
+    def find(self, sub, start=..., end=...): ...
+    def index(self, sub, start=..., end=...): ...
+    def isalnum(self): ...
+    def isalpha(self): ...
+    def isdigit(self): ...
+    def islower(self): ...
+    def isspace(self): ...
+    def istitle(self): ...
+    def isupper(self): ...
+    def join(self, seq): ...
+    def ljust(self, width, fillchar=...): ...
+    def lower(self): ...
+    def lstrip(self, chars=...): ...
+    def partition(self, sep): ...
+    def replace(self, old, new, count=...): ...
+    def rfind(self, sub, start=..., end=...): ...
+    def rindex(self, sub, start=..., end=...): ...
+    def rjust(self, width, fillchar=...): ...
+    def rpartition(self, sep): ...
+    def rsplit(self, sep=..., maxsplit=...): ...
+    def rstrip(self, chars=...): ...
+    def split(self, sep=..., maxsplit=...): ...
+    def splitlines(self, keepends=...): ...
+    def startswith(self, prefix, start=..., end=...): ...
+    def strip(self, chars=...): ...
+    def swapcase(self): ...
+    def title(self): ...
+    def translate(self, table, deletechars=...): ...
+    def upper(self): ...
+    def zfill(self, width): ...
+    def isnumeric(self): ...
+    def isdecimal(self): ...
 
 class finfo:
     def __new__(cls, dtype: Any) -> Any: ...
@@ -423,7 +463,6 @@ class format_parser:
         aligned: Any = ...,
         byteorder: Any = ...,
     ) -> None: ...
-    def __getattr__(self, key: str) -> Any: ...
 
 class iinfo:
     def __init__(self, int_type: Any) -> None: ...
@@ -436,7 +475,45 @@ class matrix(ndarray[_ShapeType, _DType_co]):
         dtype: Any = ...,
         copy: Any = ...,
     ) -> Any: ...
-    def __getattr__(self, key: str) -> Any: ...
+    def __array_finalize__(self, obj): ...
+    def __getitem__(self, index): ...
+    def __mul__(self, other): ...
+    def __rmul__(self, other): ...
+    def __imul__(self, other): ...
+    def __pow__(self, other): ...
+    def __ipow__(self, other): ...
+    def __rpow__(self, other): ...
+    def tolist(self): ...
+    def sum(self, axis=..., dtype=..., out=...): ...
+    def squeeze(self, axis=...): ...
+    def flatten(self, order=...): ...
+    def mean(self, axis=..., dtype=..., out=...): ...
+    def std(self, axis=..., dtype=..., out=..., ddof=...): ...
+    def var(self, axis=..., dtype=..., out=..., ddof=...): ...
+    def prod(self, axis=..., dtype=..., out=...): ...
+    def any(self, axis=..., out=...): ...
+    def all(self, axis=..., out=...): ...
+    def max(self, axis=..., out=...): ...
+    def argmax(self, axis=..., out=...): ...
+    def min(self, axis=..., out=...): ...
+    def argmin(self, axis=..., out=...): ...
+    def ptp(self, axis=..., out=...): ...
+    def ravel(self, order=...): ...
+    @property
+    def T(self): ...
+    @property
+    def I(self): ...
+    @property
+    def A(self): ...
+    @property
+    def A1(self): ...
+    @property
+    def H(self): ...
+    def getT(self): ...
+    def getA(self): ...
+    def getA1(self): ...
+    def getH(self): ...
+    def getI(self): ...
 
 class memmap(ndarray[_ShapeType, _DType_co]):
     def __new__(
@@ -490,10 +567,17 @@ class recarray(ndarray[_ShapeType, _DType_co]):
         aligned: Any = ...,
         order: Any = ...,
     ) -> Any: ...
-    def __getattr__(self, key: str) -> Any: ...
+    def __array_finalize__(self, obj): ...
+    def __getattribute__(self, attr): ...
+    def __setattr__(self, attr, val): ...
+    def __getitem__(self, indx): ...
+    def field(self, attr, val=...): ...
 
 class record(void):
-    def __getattr__(self, key: str) -> Any: ...
+    def __getattribute__(self, attr): ...
+    def __setattr__(self, attr, val): ...
+    def __getitem__(self, indx): ...
+    def pprint(self): ...
 
 class vectorize:
     def __init__(
@@ -2963,6 +3047,8 @@ class void(flexible):
     def setfield(
         self, val: ArrayLike, dtype: DTypeLike, offset: int = ...
     ) -> None: ...
+    def __getitem__(self, key: SupportsIndex) -> Any: ...
+    def __setitem__(self, key: SupportsIndex, value: ArrayLike) -> None: ...
 
 void0 = void
 
diff --git a/numpy/char.pyi b/numpy/char.pyi
index 0e3596bb2..4904aa27a 100644
--- a/numpy/char.pyi
+++ b/numpy/char.pyi
@@ -1,56 +1,59 @@
 from typing import Any, List
 
+from numpy import (
+    chararray as chararray,
+)
+
 __all__: List[str]
 
-equal: Any
-not_equal: Any
-greater_equal: Any
-less_equal: Any
-greater: Any
-less: Any
-str_len: Any
-add: Any
-multiply: Any
-mod: Any
-capitalize: Any
-center: Any
-count: Any
-decode: Any
-encode: Any
-endswith: Any
-expandtabs: Any
-find: Any
-index: Any
-isalnum: Any
-isalpha: Any
-isdigit: Any
-islower: Any
-isspace: Any
-istitle: Any
-isupper: Any
-join: Any
-ljust: Any
-lower: Any
-lstrip: Any
-partition: Any
-replace: Any
-rfind: Any
-rindex: Any
-rjust: Any
-rpartition: Any
-rsplit: Any
-rstrip: Any
-split: Any
-splitlines: Any
-startswith: Any
-strip: Any
-swapcase: Any
-title: Any
-translate: Any
-upper: Any
-zfill: Any
-isnumeric: Any
-isdecimal: Any
-array: Any
-asarray: Any
-chararray: Any
+def equal(x1, x2): ...
+def not_equal(x1, x2): ...
+def greater_equal(x1, x2): ...
+def less_equal(x1, x2): ...
+def greater(x1, x2): ...
+def less(x1, x2): ...
+def str_len(a): ...
+def add(x1, x2): ...
+def multiply(a, i): ...
+def mod(a, values): ...
+def capitalize(a): ...
+def center(a, width, fillchar=...): ...
+def count(a, sub, start=..., end=...): ...
+def decode(a, encoding=..., errors=...): ...
+def encode(a, encoding=..., errors=...): ...
+def endswith(a, suffix, start=..., end=...): ...
+def expandtabs(a, tabsize=...): ...
+def find(a, sub, start=..., end=...): ...
+def index(a, sub, start=..., end=...): ...
+def isalnum(a): ...
+def isalpha(a): ...
+def isdigit(a): ...
+def islower(a): ...
+def isspace(a): ...
+def istitle(a): ...
+def isupper(a): ...
+def join(sep, seq): ...
+def ljust(a, width, fillchar=...): ...
+def lower(a): ...
+def lstrip(a, chars=...): ...
+def partition(a, sep): ...
+def replace(a, old, new, count=...): ...
+def rfind(a, sub, start=..., end=...): ...
+def rindex(a, sub, start=..., end=...): ...
+def rjust(a, width, fillchar=...): ...
+def rpartition(a, sep): ...
+def rsplit(a, sep=..., maxsplit=...): ...
+def rstrip(a, chars=...): ...
+def split(a, sep=..., maxsplit=...): ...
+def splitlines(a, keepends=...): ...
+def startswith(a, prefix, start=..., end=...): ...
+def strip(a, chars=...): ...
+def swapcase(a): ...
+def title(a): ...
+def translate(a, table, deletechars=...): ...
+def upper(a): ...
+def zfill(a, width): ...
+def isnumeric(a): ...
+def isdecimal(a): ...
+def array(obj, itemsize=..., copy=..., unicode=..., order=...): ...
+def asarray(obj, itemsize=..., unicode=..., order=...): ...
diff --git a/numpy/ctypeslib.pyi b/numpy/ctypeslib.pyi
index 125c20f89..689ea4164 100644
--- a/numpy/ctypeslib.pyi
+++ b/numpy/ctypeslib.pyi
@@ -1,10 +1,14 @@
-from typing import Any, List
+from typing import List, Type
+from ctypes import _SimpleCData
 
 __all__: List[str]
 
-load_library: Any
-ndpointer: Any
-c_intp: Any
-as_ctypes: Any
-as_array: Any
-as_ctypes_type: Any
+# TODO: Update the `npt.mypy_plugin` such that it substitutes `c_intp` for
+# a specific `_SimpleCData[int]` subclass (e.g. `ctypes.c_long`)
+c_intp: Type[_SimpleCData[int]]
+
+def load_library(libname, loader_path): ...
+def ndpointer(dtype=..., ndim=..., shape=..., flags=...): ...
+def as_ctypes(obj): ...
+def as_array(obj, shape=...): ...
+def as_ctypes_type(dtype): ...
diff --git a/numpy/emath.pyi b/numpy/emath.pyi
index 5aae84b6c..d0d4af41e 100644
--- a/numpy/emath.pyi
+++ b/numpy/emath.pyi
@@ -1,13 +1,13 @@
-from typing import Any, List
+from typing import List
 
 __all__: List[str]
 
-sqrt: Any
-log: Any
-log2: Any
-logn: Any
-log10: Any
-power: Any
-arccos: Any
-arcsin: Any
-arctanh: Any
+def sqrt(x): ...
+def log(x): ...
+def log10(x): ...
+def logn(n, x): ...
+def log2(x): ...
+def power(x, p): ...
+def arccos(x): ...
+def arcsin(x): ...
+def arctanh(x): ...
diff --git a/numpy/f2py/__init__.pyi b/numpy/f2py/__init__.pyi
index 50594c1e3..3f7231fed 100644
--- a/numpy/f2py/__init__.pyi
+++ b/numpy/f2py/__init__.pyi
@@ -1,7 +1,18 @@
 from typing import Any, List
 
+from numpy.f2py import (
+    f2py_testing as f2py_testing,
+)
+
 __all__: List[str]
 
-run_main: Any
-compile: Any
-f2py_testing: Any
+def run_main(comline_list): ...
+def compile(
+    source,
+    modulename=...,
+    extra_args=...,
+    verbose=...,
+    source_fn=...,
+    extension=...,
+    full_output=...,
+): ...
diff --git a/numpy/fft/__init__.pyi b/numpy/fft/__init__.pyi
index bb4fae903..3c191a35f 100644
--- a/numpy/fft/__init__.pyi
+++ b/numpy/fft/__init__.pyi
@@ -2,21 +2,21 @@ from typing import Any, List
 
 __all__: List[str]
 
-fft: Any
-ifft: Any
-rfft: Any
-irfft: Any
-hfft: Any
-ihfft: Any
-rfftn: Any
-irfftn: Any
-rfft2: Any
-irfft2: Any
-fft2: Any
-ifft2: Any
-fftn: Any
-ifftn: Any
-fftshift: Any
-ifftshift: Any
-fftfreq: Any
-rfftfreq: Any
+def fft(a, n=..., axis=..., norm=...): ...
+def ifft(a, n=..., axis=..., norm=...): ...
+def rfft(a, n=..., axis=..., norm=...): ...
+def irfft(a, n=..., axis=..., norm=...): ...
+def hfft(a, n=..., axis=..., norm=...): ...
+def ihfft(a, n=..., axis=..., norm=...): ...
+def fftn(a, s=..., axes=..., norm=...): ...
+def ifftn(a, s=..., axes=..., norm=...): ...
+def rfftn(a, s=..., axes=..., norm=...): ...
+def irfftn(a, s=..., axes=..., norm=...): ...
+def fft2(a, s=..., axes=..., norm=...): ...
+def ifft2(a, s=..., axes=..., norm=...): ...
+def rfft2(a, s=..., axes=..., norm=...): ...
+def irfft2(a, s=..., axes=..., norm=...): ...
+def fftshift(x, axes=...): ...
+def ifftshift(x, axes=...): ...
+def fftfreq(n, d=...): ...
+def rfftfreq(n, d=...): ...
diff --git a/numpy/matrixlib/__init__.pyi b/numpy/matrixlib/__init__.pyi
index b9005c4aa..e4b5c19a2 100644
--- a/numpy/matrixlib/__init__.pyi
+++ b/numpy/matrixlib/__init__.pyi
@@ -1,8 +1,11 @@
 from typing import Any, List
 
+from numpy import (
+    matrix as matrix,
+)
+
 __all__: List[str]
 
-matrix: Any
-bmat: Any
-mat: Any
-asmatrix: Any
+def bmat(obj, ldict=..., gdict=...): ...
+def asmatrix(data, dtype=...): ...
+mat = asmatrix
diff --git a/numpy/rec.pyi b/numpy/rec.pyi
index 883e2dd5b..198636058 100644
--- a/numpy/rec.pyi
+++ b/numpy/rec.pyi
@@ -1,12 +1,65 @@
-from typing import Any, List
+from typing import List
+
+from numpy import (
+    format_parser as format_parser,
+    record as record,
+    recarray as recarray,
+)
 
 __all__: List[str]
 
-record: Any
-recarray: Any
-format_parser: Any
-fromarrays: Any
-fromrecords: Any
-fromstring: Any
-fromfile: Any
-array: Any
+def fromarrays(
+    arrayList,
+    dtype=...,
+    shape=...,
+    formats=...,
+    names=...,
+    titles=...,
+    aligned=...,
+    byteorder=...,
+): ...
+def fromrecords(
+    recList,
+    dtype=...,
+    shape=...,
+    formats=...,
+    names=...,
+    titles=...,
+    aligned=...,
+    byteorder=...,
+): ...
+def fromstring(
+    datastring,
+    dtype=...,
+    shape=...,
+    offset=...,
+    formats=...,
+    names=...,
+    titles=...,
+    aligned=...,
+    byteorder=...,
+): ...
+def fromfile(
+    fd,
+    dtype=...,
+    shape=...,
+    offset=...,
+    formats=...,
+    names=...,
+    titles=...,
+    aligned=...,
+    byteorder=...,
+): ...
+def array(
+    obj,
+    dtype=...,
+    shape=...,
+    offset=...,
+    strides=...,
+    formats=...,
+    names=...,
+    titles=...,
+    aligned=...,
+    byteorder=...,
+    copy=...,
+): ...
diff --git a/numpy/testing/__init__.pyi b/numpy/testing/__init__.pyi
index 7dad2c9db..efb6bcd91 100644
--- a/numpy/testing/__init__.pyi
+++ b/numpy/testing/__init__.pyi
@@ -1,46 +1,107 @@
-from typing import Any, List
+import sys
+import warnings
+from typing import Any, List, ClassVar, Tuple, Set
+
+if sys.version_info >= (3, 8):
+    from typing import Final
+else:
+    from typing_extensions import Final
+
+from unittest.case import (
+    SkipTest as SkipTest,
+)
 
 __all__: List[str]
 
-assert_equal: Any
-assert_almost_equal: Any
-assert_approx_equal: Any
-assert_array_equal: Any
-assert_array_less: Any
-assert_string_equal: Any
-assert_array_almost_equal: Any
-assert_raises: Any
-build_err_msg: Any
-decorate_methods: Any
-jiffies: Any
-memusage: Any
-print_assert_equal: Any
-raises: Any
-rundocs: Any
-runstring: Any
-verbose: Any
-measure: Any
-assert_: Any
-assert_array_almost_equal_nulp: Any
-assert_raises_regex: Any
-assert_array_max_ulp: Any
-assert_warns: Any
-assert_no_warnings: Any
-assert_allclose: Any
-IgnoreException: Any
-clear_and_catch_warnings: Any
-SkipTest: Any
-KnownFailureException: Any
-temppath: Any
-tempdir: Any
-IS_PYPY: Any
-HAS_REFCOUNT: Any
-suppress_warnings: Any
-assert_array_compare: Any
-_assert_valid_refcount: Any
-_gen_alignment_data: Any
-assert_no_gc_cycles: Any
-break_cycles: Any
-HAS_LAPACK64: Any
-TestCase: Any
-run_module_suite: Any
+class KnownFailureException(Exception): ...
+class IgnoreException(Exception): ...
+
+class clear_and_catch_warnings(warnings.catch_warnings):
+    class_modules: ClassVar[Tuple[str, ...]]
+    modules: Set[str]
+    def __init__(self, record=..., modules=...): ...
+    def __enter__(self): ...
+    def __exit__(self, *exc_info): ...
+
+class suppress_warnings:
+    log: List[warnings.WarningMessage]
+    def __init__(self, forwarding_rule=...): ...
+    def filter(self, category=..., message=..., module=...): ...
+    def record(self, category=..., message=..., module=...): ...
+    def __enter__(self): ...
+    def __exit__(self, *exc_info): ...
+    def __call__(self, func): ...
+
+verbose: int
+IS_PYPY: Final[bool]
+HAS_REFCOUNT: Final[bool]
+HAS_LAPACK64: Final[bool]
+
+def assert_(val, msg=...): ...
+def memusage(processName=..., instance=...): ...
+def jiffies(_proc_pid_stat=..., _load_time=...): ...
+def build_err_msg(
+    arrays,
+    err_msg,
+    header=...,
+    verbose=...,
+    names=...,
+    precision=...,
+): ...
+def assert_equal(actual, desired, err_msg=..., verbose=...): ...
+def print_assert_equal(test_string, actual, desired): ...
+def assert_almost_equal(
+    actual,
+    desired,
+    decimal=...,
+    err_msg=...,
+    verbose=...,
+): ...
+def assert_approx_equal(
+    actual,
+    desired,
+    significant=...,
+    err_msg=...,
+    verbose=...,
+): ...
+def assert_array_compare(
+    comparison,
+    x,
+    y,
+    err_msg=...,
+    verbose=...,
+    header=...,
+    precision=...,
+    equal_nan=...,
+    equal_inf=...,
+): ...
+def assert_array_equal(x, y, err_msg=..., verbose=...): ...
+def assert_array_almost_equal(x, y, decimal=..., err_msg=..., verbose=...): ...
+def assert_array_less(x, y, err_msg=..., verbose=...): ...
+def runstring(astr, dict): ...
+def assert_string_equal(actual, desired): ...
+def rundocs(filename=..., raise_on_error=...): ...
+def raises(*args): ...
+def assert_raises(*args, **kwargs): ...
+def assert_raises_regex(exception_class, expected_regexp, *args, **kwargs): ...
+def decorate_methods(cls, decorator, testmatch=...): ...
+def measure(code_str, times=..., label=...): ...
+def assert_allclose(
+    actual,
+    desired,
+    rtol=...,
+    atol=...,
+    equal_nan=...,
+    err_msg=...,
+    verbose=...,
+): ...
+def assert_array_almost_equal_nulp(x, y, nulp=...): ...
+def assert_array_max_ulp(a, b, maxulp=..., dtype=...): ...
+def assert_warns(warning_class, *args, **kwargs): ...
+def assert_no_warnings(*args, **kwargs): ...
+def tempdir(*args, **kwargs): ...
+def temppath(*args, **kwargs): ...
+def assert_no_gc_cycles(*args, **kwargs): ...
+def break_cycles(): ...
+def _assert_valid_refcount(op): ...
+def _gen_alignment_data(dtype=..., type=..., max_size=...): ...