Merge pull request numpy#27510 from jorenham/typing/type_check_only

TYP: Mark stub-only classes as `@type_check_only`

Author: charris

numpy/__init__.pyi

@@ -8,7 +8,6 @@ import datetime as dt
 import enum
 from abc import abstractmethod
 from types import EllipsisType, TracebackType, MappingProxyType, GenericAlias
-from contextlib import contextmanager
 from decimal import Decimal
 from fractions import Fraction
 from uuid import UUID
@@ -25,7 +24,6 @@ from numpy._typing import (
     _SupportsArray,
     _NestedSequence,
     _FiniteNestedSequence,
-    _SupportsArray,
     _ArrayLikeBool_co,
     _ArrayLikeUInt_co,
     _ArrayLikeInt_co,
@@ -207,6 +205,7 @@ from typing import (
     final,
     ClassVar,
     TypeAlias,
+    type_check_only,
 )
 
 # NOTE: `typing_extensions` is always available in `.pyi` stubs or when
@@ -744,6 +743,7 @@ _AnyStr_contra = TypeVar("_AnyStr_contra", LiteralString, builtins.str, bytes, c
 
 # Protocol for representing file-like-objects accepted
 # by `ndarray.tofile` and `fromfile`
+@type_check_only
 class _IOProtocol(Protocol):
     def flush(self) -> object: ...
     def fileno(self) -> int: ...
@@ -752,6 +752,7 @@ class _IOProtocol(Protocol):
 
 # NOTE: `seek`, `write` and `flush` are technically only required
 # for `readwrite`/`write` modes
+@type_check_only
 class _MemMapIOProtocol(Protocol):
     def flush(self) -> object: ...
     def fileno(self) -> SupportsIndex: ...
@@ -761,19 +762,14 @@ class _MemMapIOProtocol(Protocol):
     @property
     def read(self) -> object: ...
 
+@type_check_only
 class _SupportsWrite(Protocol[_AnyStr_contra]):
     def write(self, s: _AnyStr_contra, /) -> object: ...
 
-def __dir__() -> Sequence[str]: ...
-
 __version__: LiteralString
 __array_api_version__: LiteralString
 test: PytestTester
 
-# TODO: Move placeholders to their respective module once
-# their annotations are properly implemented
-#
-# Placeholders for classes
 
 def show_config() -> None: ...
 
@@ -1390,6 +1386,7 @@ _SortKind: TypeAlias = L[
 ]
 _SortSide: TypeAlias = L["left", "right"]
 
+@type_check_only
 class _ArrayOrScalarCommon:
     @property
     def T(self) -> Self: ...
@@ -1812,13 +1809,16 @@ else:
 
 _ArrayAPIVersion: TypeAlias = L["2021.12", "2022.12", "2023.12"]
 
+@type_check_only
 class _SupportsItem(Protocol[_T_co]):
     def item(self, args: Any, /) -> _T_co: ...
 
+@type_check_only
 class _SupportsReal(Protocol[_T_co]):
     @property
     def real(self) -> _T_co: ...
 
+@type_check_only
 class _SupportsImag(Protocol[_T_co]):
     @property
     def imag(self) -> _T_co: ...
@@ -3376,11 +3376,12 @@ class bool(generic):
 bool_: TypeAlias = bool
 
 _StringType = TypeVar("_StringType", bound=str | bytes)
-_ShapeType = TypeVar("_ShapeType", bound=Any)
+_ShapeType = TypeVar("_ShapeType", bound=_Shape)
 _ObjectType = TypeVar("_ObjectType", bound=object)
 
 # A sequence-like interface like `collections.abc.Sequence`, but without the
 # irrelevant methods.
+@type_check_only
 class _SimpleSequence(Protocol):
     def __len__(self, /) -> int: ...
     def __getitem__(self, index: int, /) -> Any: ...
@@ -3421,6 +3422,7 @@ class object_(generic):
 
 # The `datetime64` constructors requires an object with the three attributes below,
 # and thus supports datetime duck typing
+@type_check_only
 class _DatetimeScalar(Protocol):
     @property
     def day(self) -> int: ...
@@ -4727,6 +4729,7 @@ class matrix(ndarray[_Shape2DType_co, _DType_co]):
     def getH(self) -> matrix[_Shape2D, _DType_co]: ...
 
 
+@type_check_only
 class _SupportsDLPack(Protocol[_T_contra]):
     def __dlpack__(self, *, stream: None | _T_contra = ...) -> _PyCapsule: ...
 

numpy/_array_api_info.pyi

@@ -6,6 +6,7 @@ from typing import (
     TypeVar,
     final,
     overload,
+    type_check_only,
 )
 from typing_extensions import Never
 
@@ -63,38 +64,44 @@ _Permute3: TypeAlias = (
     | tuple[_T3, _T1, _T2] | tuple[_T3, _T2, _T1]
 )
 
+@type_check_only
 class _DTypesBool(TypedDict):
     bool: np.dtype[np.bool]
 
+@type_check_only
 class _DTypesInt(TypedDict):
     int8: np.dtype[np.int8]
     int16: np.dtype[np.int16]
     int32: np.dtype[np.int32]
     int64: np.dtype[np.int64]
 
+@type_check_only
 class _DTypesUInt(TypedDict):
     uint8: np.dtype[np.uint8]
     uint16: np.dtype[np.uint16]
     uint32: np.dtype[np.uint32]
     uint64: np.dtype[np.uint64]
 
-class _DTypesInteger(_DTypesInt, _DTypesUInt):
-    ...
+@type_check_only
+class _DTypesInteger(_DTypesInt, _DTypesUInt): ...
 
+@type_check_only
 class _DTypesFloat(TypedDict):
     float32: np.dtype[np.float32]
     float64: np.dtype[np.float64]
 
+@type_check_only
 class _DTypesComplex(TypedDict):
     complex64: np.dtype[np.complex64]
     complex128: np.dtype[np.complex128]
 
-class _DTypesNumber(_DTypesInteger, _DTypesFloat, _DTypesComplex):
-    ...
+@type_check_only
+class _DTypesNumber(_DTypesInteger, _DTypesFloat, _DTypesComplex): ...
 
-class _DTypes(_DTypesBool, _DTypesNumber):
-    ...
+@type_check_only
+class _DTypes(_DTypesBool, _DTypesNumber): ...
 
+@type_check_only
 class _DTypesUnion(TypedDict, total=False):
     bool: np.dtype[np.bool]
     int8: np.dtype[np.int8]
@@ -112,7 +119,6 @@ class _DTypesUnion(TypedDict, total=False):
 
 _EmptyDict: TypeAlias = dict[Never, Never]
 
-
 @final
 class __array_namespace_info__:
     __module__: ClassVar[Literal['numpy']]

numpy/_core/_type_aliases.pyi

@@ -1,5 +1,5 @@
 from collections.abc import Collection
-from typing import Any, Final, Literal as L, TypeAlias, TypedDict
+from typing import Any, Final, Literal as L, TypeAlias, TypedDict, type_check_only
 
 import numpy as np
 
@@ -16,6 +16,7 @@ __all__ = (
 sctypeDict: Final[dict[str, type[np.generic]]]
 allTypes: Final[dict[str, type[np.generic]]]
 
+@type_check_only
 class _CNamesDict(TypedDict):
     BOOL: np.dtype[np.bool]
     HALF: np.dtype[np.half]
@@ -58,7 +59,7 @@ _AbstractTypeName: TypeAlias = L[
 ]
 _abstract_type_names: Final[set[_AbstractTypeName]]
 
-
+@type_check_only
 class _AliasesType(TypedDict):
     double: L["float64"]
     cdouble: L["complex128"]
@@ -71,6 +72,7 @@ class _AliasesType(TypedDict):
 
 _aliases: Final[_AliasesType]
 
+@type_check_only
 class _ExtraAliasesType(TypedDict):
     float: L["float64"]
     complex: L["complex128"]
@@ -83,6 +85,7 @@ class _ExtraAliasesType(TypedDict):
 
 _extra_aliases: Final[_ExtraAliasesType]
 
+@type_check_only
 class _SCTypes(TypedDict):
     int: Collection[type[np.signedinteger[Any]]]
     uint: Collection[type[np.unsignedinteger[Any]]]

numpy/_core/_ufunc_config.pyi

@@ -1,17 +1,19 @@
 from collections.abc import Callable
-from typing import Any, Literal, TypeAlias, TypedDict
+from typing import Any, Literal, TypeAlias, TypedDict, type_check_only
 
 from numpy import _SupportsWrite
 
 _ErrKind: TypeAlias = Literal["ignore", "warn", "raise", "call", "print", "log"]
 _ErrFunc: TypeAlias = Callable[[str, int], Any]
 
+@type_check_only
 class _ErrDict(TypedDict):
     divide: _ErrKind
     over: _ErrKind
     under: _ErrKind
     invalid: _ErrKind
 
+@type_check_only
 class _ErrDictOptional(TypedDict, total=False):
     all: None | _ErrKind
     divide: None | _ErrKind

numpy/_core/arrayprint.pyi

@@ -1,5 +1,5 @@
 from collections.abc import Callable
-from typing import Any, Literal, TypeAlias, TypedDict, SupportsIndex
+from typing import Any, Literal, TypeAlias, TypedDict, SupportsIndex, type_check_only
 
 # Using a private class is by no means ideal, but it is simply a consequence
 # of a `contextlib.context` returning an instance of aforementioned class
@@ -20,6 +20,7 @@ from numpy._typing import NDArray, _CharLike_co, _FloatLike_co
 
 _FloatMode: TypeAlias = Literal["fixed", "unique", "maxprec", "maxprec_equal"]
 
+@type_check_only
 class _FormatDict(TypedDict, total=False):
     bool: Callable[[np.bool], str]
     int: Callable[[integer[Any]], str]
@@ -38,6 +39,7 @@ class _FormatDict(TypedDict, total=False):
     complex_kind: Callable[[complexfloating[Any, Any]], str]
     str_kind: Callable[[_CharLike_co], str]
 
+@type_check_only
 class _FormatOptions(TypedDict):
     precision: int
     threshold: int

numpy/_core/multiarray.pyi

@@ -136,10 +136,12 @@ _RollKind: TypeAlias = L[  # `raise` is deliberately excluded
     "modifiedpreceding",
 ]
 
+@type_check_only
 class _SupportsLenAndGetItem(Protocol[_T_contra, _T_co]):
     def __len__(self) -> int: ...
     def __getitem__(self, key: _T_contra, /) -> _T_co: ...
 
+@type_check_only
 class _SupportsArray(Protocol[_ArrayType_co]):
     def __array__(self, /) -> _ArrayType_co: ...
 

numpy/_core/numerictypes.pyi

@@ -3,6 +3,7 @@ from typing import (
     Any,
     TypeVar,
     TypedDict,
+    type_check_only,
 )
 
 import numpy as np
@@ -43,6 +44,7 @@ from numpy._typing import DTypeLike
 _T = TypeVar("_T")
 _SCT = TypeVar("_SCT", bound=generic)
 
+@type_check_only
 class _TypeCodes(TypedDict):
     Character: L['c']
     Integer: L['bhilqnp']

numpy/_core/records.pyi

@@ -8,7 +8,8 @@ from typing import (
     overload,
     Protocol,
     SupportsIndex,
-    Literal
+    Literal,
+    type_check_only
 )
 
 from numpy import (
@@ -38,6 +39,7 @@ _SCT = TypeVar("_SCT", bound=generic)
 
 _RecArray: TypeAlias = recarray[Any, dtype[_SCT]]
 
+@type_check_only
 class _SupportsReadInto(Protocol):
     def seek(self, offset: int, whence: int, /) -> object: ...
     def tell(self, /) -> int: ...