MAINT: Split numpy.typing into a public and private component

i.e. `numpy.typing` and `numpy._typing`

numpy/__init__.pyi

@@ -16,7 +16,7 @@ if sys.version_info >= (3, 9):
 from numpy._pytesttester import PytestTester
 from numpy.core._internal import _ctypes
 
-from numpy.typing import (
+from numpy._typing import (
     # Arrays
     ArrayLike,
     NDArray,
@@ -126,7 +126,7 @@ from numpy.typing import (
     _GUFunc_Nin2_Nout1,
 )
 
-from numpy.typing._callable import (
+from numpy._typing._callable import (
     _BoolOp,
     _BoolBitOp,
     _BoolSub,
@@ -153,7 +153,7 @@ from numpy.typing._callable import (
 
 # NOTE: Numpy's mypy plugin is used for removing the types unavailable
 # to the specific platform
-from numpy.typing._extended_precision import (
+from numpy._typing._extended_precision import (
     uint128 as uint128,
     uint256 as uint256,
     int128 as int128,
@@ -3139,7 +3139,7 @@ UFUNC_PYVALS_NAME: L["UFUNC_PYVALS"]
 
 newaxis: None
 
-# See `npt._ufunc` for more concrete nin-/nout-specific stubs
+# See `numpy._typing._ufunc` for more concrete nin-/nout-specific stubs
 @final
 class ufunc:
     @property

numpy/_typing/__init__.py

@@ -0,0 +1,218 @@
+"""Private counterpart of ``numpy.typing``."""
+
+from __future__ import annotations
+
+from numpy import ufunc
+from numpy.core.overrides import set_module
+from typing import TYPE_CHECKING, final
+
+
+@final  # Disallow the creation of arbitrary `NBitBase` subclasses
+@set_module("numpy.typing")
+class NBitBase:
+    """
+    A type representing `numpy.number` precision during static type checking.
+
+    Used exclusively for the purpose static type checking, `NBitBase`
+    represents the base of a hierarchical set of subclasses.
+    Each subsequent subclass is herein used for representing a lower level
+    of precision, *e.g.* ``64Bit > 32Bit > 16Bit``.
+
+    .. versionadded:: 1.20
+
+    Examples
+    --------
+    Below is a typical usage example: `NBitBase` is herein used for annotating
+    a function that takes a float and integer of arbitrary precision
+    as arguments and returns a new float of whichever precision is largest
+    (*e.g.* ``np.float16 + np.int64 -> np.float64``).
+
+    .. code-block:: python
+
+        >>> from __future__ import annotations
+        >>> from typing import TypeVar, TYPE_CHECKING
+        >>> import numpy as np
+        >>> import numpy.typing as npt
+
+        >>> T1 = TypeVar("T1", bound=npt.NBitBase)
+        >>> T2 = TypeVar("T2", bound=npt.NBitBase)
+
+        >>> def add(a: np.floating[T1], b: np.integer[T2]) -> np.floating[T1 | T2]:
+        ...     return a + b
+
+        >>> a = np.float16()
+        >>> b = np.int64()
+        >>> out = add(a, b)
+
+        >>> if TYPE_CHECKING:
+        ...     reveal_locals()
+        ...     # note: Revealed local types are:
+        ...     # note:     a: numpy.floating[numpy.typing._16Bit*]
+        ...     # note:     b: numpy.signedinteger[numpy.typing._64Bit*]
+        ...     # note:     out: numpy.floating[numpy.typing._64Bit*]
+
+    """
+
+    def __init_subclass__(cls) -> None:
+        allowed_names = {
+            "NBitBase", "_256Bit", "_128Bit", "_96Bit", "_80Bit",
+            "_64Bit", "_32Bit", "_16Bit", "_8Bit",
+        }
+        if cls.__name__ not in allowed_names:
+            raise TypeError('cannot inherit from final class "NBitBase"')
+        super().__init_subclass__()
+
+
+# Silence errors about subclassing a `@final`-decorated class
+class _256Bit(NBitBase):  # type: ignore[misc]
+    pass
+
+class _128Bit(_256Bit):  # type: ignore[misc]
+    pass
+
+class _96Bit(_128Bit):  # type: ignore[misc]
+    pass
+
+class _80Bit(_96Bit):  # type: ignore[misc]
+    pass
+
+class _64Bit(_80Bit):  # type: ignore[misc]
+    pass
+
+class _32Bit(_64Bit):  # type: ignore[misc]
+    pass
+
+class _16Bit(_32Bit):  # type: ignore[misc]
+    pass
+
+class _8Bit(_16Bit):  # type: ignore[misc]
+    pass
+
+
+from ._nested_sequence import _NestedSequence
+from ._nbit import (
+    _NBitByte,
+    _NBitShort,
+    _NBitIntC,
+    _NBitIntP,
+    _NBitInt,
+    _NBitLongLong,
+    _NBitHalf,
+    _NBitSingle,
+    _NBitDouble,
+    _NBitLongDouble,
+)
+from ._char_codes import (
+    _BoolCodes,
+    _UInt8Codes,
+    _UInt16Codes,
+    _UInt32Codes,
+    _UInt64Codes,
+    _Int8Codes,
+    _Int16Codes,
+    _Int32Codes,
+    _Int64Codes,
+    _Float16Codes,
+    _Float32Codes,
+    _Float64Codes,
+    _Complex64Codes,
+    _Complex128Codes,
+    _ByteCodes,
+    _ShortCodes,
+    _IntCCodes,
+    _IntPCodes,
+    _IntCodes,
+    _LongLongCodes,
+    _UByteCodes,
+    _UShortCodes,
+    _UIntCCodes,
+    _UIntPCodes,
+    _UIntCodes,
+    _ULongLongCodes,
+    _HalfCodes,
+    _SingleCodes,
+    _DoubleCodes,
+    _LongDoubleCodes,
+    _CSingleCodes,
+    _CDoubleCodes,
+    _CLongDoubleCodes,
+    _DT64Codes,
+    _TD64Codes,
+    _StrCodes,
+    _BytesCodes,
+    _VoidCodes,
+    _ObjectCodes,
+)
+from ._scalars import (
+    _CharLike_co,
+    _BoolLike_co,
+    _UIntLike_co,
+    _IntLike_co,
+    _FloatLike_co,
+    _ComplexLike_co,
+    _TD64Like_co,
+    _NumberLike_co,
+    _ScalarLike_co,
+    _VoidLike_co,
+)
+from ._shape import _Shape, _ShapeLike
+from ._dtype_like import (
+    DTypeLike as DTypeLike,
+    _DTypeLike,
+    _SupportsDType,
+    _VoidDTypeLike,
+    _DTypeLikeBool,
+    _DTypeLikeUInt,
+    _DTypeLikeInt,
+    _DTypeLikeFloat,
+    _DTypeLikeComplex,
+    _DTypeLikeTD64,
+    _DTypeLikeDT64,
+    _DTypeLikeObject,
+    _DTypeLikeVoid,
+    _DTypeLikeStr,
+    _DTypeLikeBytes,
+    _DTypeLikeComplex_co,
+)
+from ._array_like import (
+    ArrayLike as ArrayLike,
+    _ArrayLike,
+    _FiniteNestedSequence,
+    _SupportsArray,
+    _SupportsArrayFunc,
+    _ArrayLikeInt,
+    _ArrayLikeBool_co,
+    _ArrayLikeUInt_co,
+    _ArrayLikeInt_co,
+    _ArrayLikeFloat_co,
+    _ArrayLikeComplex_co,
+    _ArrayLikeNumber_co,
+    _ArrayLikeTD64_co,
+    _ArrayLikeDT64_co,
+    _ArrayLikeObject_co,
+    _ArrayLikeVoid_co,
+    _ArrayLikeStr_co,
+    _ArrayLikeBytes_co,
+)
+from ._generic_alias import (
+    NDArray as NDArray,
+    _DType,
+    _GenericAlias,
+)
+
+if TYPE_CHECKING:
+    from ._ufunc import (
+        _UFunc_Nin1_Nout1,
+        _UFunc_Nin2_Nout1,
+        _UFunc_Nin1_Nout2,
+        _UFunc_Nin2_Nout2,
+        _GUFunc_Nin2_Nout1,
+    )
+else:
+    # Declare the (type-check-only) ufunc subclasses as ufunc aliases during
+    # runtime; this helps autocompletion tools such as Jedi (numpy/numpy#19834)
+    _UFunc_Nin1_Nout1 = ufunc
+    _UFunc_Nin2_Nout1 = ufunc
+    _UFunc_Nin1_Nout2 = ufunc
+    _UFunc_Nin2_Nout2 = ufunc
+    _GUFunc_Nin2_Nout1 = ufunc

numpy/typing/_nested_sequence.py → numpy/_typing/_nested_sequence.py

@@ -36,7 +36,7 @@ class _NestedSequence(Protocol[_T_co]):
 
         >>> from typing import TYPE_CHECKING
         >>> import numpy as np
-        >>> from numpy.typing import _NestedSequnce
+        >>> from numpy._typing import _NestedSequnce
 
         >>> def get_dtype(seq: _NestedSequnce[float]) -> np.dtype[np.float64]:
         ...     return np.asarray(seq).dtype
@@ -49,10 +49,10 @@ class _NestedSequence(Protocol[_T_co]):
         >>> if TYPE_CHECKING:
         ...     reveal_locals()
         ...     # note: Revealed local types are:
-        ...     # note:     a: numpy.dtype[numpy.floating[numpy.typing._64Bit]]
-        ...     # note:     b: numpy.dtype[numpy.floating[numpy.typing._64Bit]]
-        ...     # note:     c: numpy.dtype[numpy.floating[numpy.typing._64Bit]]
-        ...     # note:     d: numpy.dtype[numpy.floating[numpy.typing._64Bit]]
+        ...     # note:     a: numpy.dtype[numpy.floating[numpy._typing._64Bit]]
+        ...     # note:     b: numpy.dtype[numpy.floating[numpy._typing._64Bit]]
+        ...     # note:     c: numpy.dtype[numpy.floating[numpy._typing._64Bit]]
+        ...     # note:     d: numpy.dtype[numpy.floating[numpy._typing._64Bit]]
 
     """
 

numpy/_typing/setup.py

@@ -0,0 +1,10 @@
+def configuration(parent_package='', top_path=None):
+    from numpy.distutils.misc_util import Configuration
+    config = Configuration('_typing', parent_package, top_path)
+    config.add_data_files('*.pyi')
+    return config
+
+
+if __name__ == '__main__':
+    from numpy.distutils.core import setup
+    setup(configuration=configuration)

numpy/core/_asarray.pyi

@@ -2,7 +2,7 @@ from collections.abc import Iterable
 from typing import TypeVar, Union, overload, Literal
 
 from numpy import ndarray
-from numpy.typing import DTypeLike, _SupportsArrayFunc
+from numpy._typing import DTypeLike, _SupportsArrayFunc
 
 _ArrayType = TypeVar("_ArrayType", bound=ndarray)
 

numpy/core/arrayprint.pyi

@@ -21,7 +21,7 @@ from numpy import (
     longdouble,
     clongdouble,
 )
-from numpy.typing import ArrayLike, _CharLike_co, _FloatLike_co
+from numpy._typing import ArrayLike, _CharLike_co, _FloatLike_co
 
 _FloatMode = Literal["fixed", "unique", "maxprec", "maxprec_equal"]
 

numpy/core/defchararray.pyi

@@ -16,7 +16,7 @@ from numpy import (
     _OrderKACF,
 )
 
-from numpy.typing import (
+from numpy._typing import (
     NDArray,
     _ArrayLikeStr_co as U_co,
     _ArrayLikeBytes_co as S_co,

numpy/core/einsumfunc.pyi

@@ -12,7 +12,7 @@ from numpy import (
     number,
     _OrderKACF,
 )
-from numpy.typing import (
+from numpy._typing import (
     _ArrayLikeBool_co,
     _ArrayLikeUInt_co,
     _ArrayLikeInt_co,

numpy/core/fromnumeric.pyi

@@ -22,7 +22,7 @@ from numpy import (
     _SortKind,
     _SortSide,
 )
-from numpy.typing import (
+from numpy._typing import (
     DTypeLike,
     _DTypeLike,
     ArrayLike,

numpy/core/function_base.pyi

@@ -7,7 +7,7 @@ from typing import (
 )
 
 from numpy import floating, complexfloating, generic
-from numpy.typing import (
+from numpy._typing import (
     NDArray,
     DTypeLike,
     _DTypeLike,

numpy/core/multiarray.pyi

@@ -48,7 +48,7 @@ from numpy import (
     _NDIterOpFlagsKind,
 )
 
-from numpy.typing import (
+from numpy._typing import (
     # Shapes
     _ShapeLike,
 

numpy/core/numeric.pyi

@@ -27,7 +27,7 @@ from numpy import (
     _OrderCF,
 )
 
-from numpy.typing import (
+from numpy._typing import (
     ArrayLike,
     NDArray,
     DTypeLike,

numpy/core/numerictypes.pyi

@@ -46,7 +46,7 @@ from numpy.core._type_aliases import (
     sctypes as sctypes,
 )
 
-from numpy.typing import DTypeLike, ArrayLike, _DTypeLike
+from numpy._typing import DTypeLike, ArrayLike, _DTypeLike
 
 _T = TypeVar("_T")
 _SCT = TypeVar("_SCT", bound=generic)

numpy/core/records.pyi

@@ -18,7 +18,7 @@ from numpy import (
     _SupportsBuffer,
 )
 
-from numpy.typing import (
+from numpy._typing import (
     ArrayLike,
     DTypeLike,
     NDArray,

numpy/core/shape_base.pyi

@@ -2,7 +2,7 @@ from collections.abc import Sequence
 from typing import TypeVar, overload, Any, SupportsIndex
 
 from numpy import generic
-from numpy.typing import ArrayLike, NDArray, _ArrayLike
+from numpy._typing import ArrayLike, NDArray, _ArrayLike
 
 _SCT = TypeVar("_SCT", bound=generic)
 _ArrayType = TypeVar("_ArrayType", bound=NDArray[Any])

numpy/ctypeslib.pyi

@@ -38,7 +38,7 @@ from numpy import (
 )
 from numpy.core._internal import _ctypes
 from numpy.core.multiarray import flagsobj
-from numpy.typing import (
+from numpy._typing import (
     # Arrays
     NDArray,
     _ArrayLike,