ENH: Centralize all `DTypeLike` string aliases in `numpy.typing`

3 files changed, 282 insertions, 246 deletions

diff --git a/numpy/__init__.pyi b/numpy/__init__.pyi
index 6df10d7a7..514f4dc4a 100644
--- a/numpy/__init__.pyi
+++ b/numpy/__init__.pyi
@@ -40,6 +40,47 @@ from numpy.typing import (
     _NBitDouble,
     _NBitLongDouble,
 )
+from numpy.typing 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 numpy.typing._callable import (
     _BoolOp,
     _BoolBitOp,
@@ -555,269 +596,108 @@ class dtype(Generic[_DTypeScalar]):
     #
     # so we have to make sure the overloads for the narrowest type is
     # first.
+    # Builtin types
     @overload
-    def __new__(
-        cls,
-        dtype: Union[
-            Type[bool],
-            Literal[
-                "?",
-                "=?",
-                "<?",
-                ">?",
-                "bool",
-                "bool_",
-            ],
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[bool_]: ...
+    def __new__(cls, dtype: Type[bool], align: bool = ..., copy: bool = ...) -> dtype[bool_]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "uint8",
-            "u1",
-            "=u1",
-            "<u1",
-            ">u1",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[uint8]: ...
+    def __new__(cls, dtype: Type[int], align: bool = ..., copy: bool = ...) -> dtype[int_]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "uint16",
-            "u2",
-            "=u2",
-            "<u2",
-            ">u2",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[uint16]: ...
+    def __new__(cls, dtype: Optional[Type[float]], align: bool = ..., copy: bool = ...) -> dtype[float_]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "uint32",
-            "u4",
-            "=u4",
-            "<u4",
-            ">u4",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[uint32]: ...
+    def __new__(cls, dtype: Type[complex], align: bool = ..., copy: bool = ...) -> dtype[complex_]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "uint64",
-            "u8",
-            "=u8",
-            "<u8",
-            ">u8",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[uint64]: ...
+    def __new__(cls, dtype: Type[str], align: bool = ..., copy: bool = ...) -> dtype[str_]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "int8",
-            "i1",
-            "=i1",
-            "<i1",
-            ">i1",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[int8]: ...
+    def __new__(cls, dtype: Type[bytes], align: bool = ..., copy: bool = ...) -> dtype[bytes_]: ...
+
+    # `unsignedinteger` string-based representations
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "int16",
-            "i2",
-            "=i2",
-            "<i2",
-            ">i2",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[int16]: ...
+    def __new__(cls, dtype: _UInt8Codes, align: bool = ..., copy: bool = ...) -> dtype[uint8]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "int32",
-            "i4",
-            "=i4",
-            "<i4",
-            ">i4",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[int32]: ...
+    def __new__(cls, dtype: _UInt16Codes, align: bool = ..., copy: bool = ...) -> dtype[uint16]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "int64",
-            "i8",
-            "=i8",
-            "<i8",
-            ">i8",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[int64]: ...
-    # "int"/int resolve to int_, which is system dependent and as of
-    # now untyped. Long-term we'll do something fancier here.
+    def __new__(cls, dtype: _UInt32Codes, align: bool = ..., copy: bool = ...) -> dtype[uint32]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Union[Type[int], Literal["int"]],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype: ...
+    def __new__(cls, dtype: _UInt64Codes, align: bool = ..., copy: bool = ...) -> dtype[uint64]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "float16",
-            "f4",
-            "=f4",
-            "<f4",
-            ">f4",
-            "e",
-            "=e",
-            "<e",
-            ">e",
-            "half",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[float16]: ...
+    def __new__(cls, dtype: _UByteCodes, align: bool = ..., copy: bool = ...) -> dtype[ubyte]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "float32",
-            "f4",
-            "=f4",
-            "<f4",
-            ">f4",
-            "f",
-            "=f",
-            "<f",
-            ">f",
-            "single",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[float32]: ...
+    def __new__(cls, dtype: _UShortCodes, align: bool = ..., copy: bool = ...) -> dtype[ushort]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Union[
-            None,
-            Type[float],
-            Literal[
-                "float64",
-                "f8",
-                "=f8",
-                "<f8",
-                ">f8",
-                "d",
-                "<d",
-                ">d",
-                "float",
-                "double",
-                "float_",
-            ],
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[float64]: ...
+    def __new__(cls, dtype: _UIntCCodes, align: bool = ..., copy: bool = ...) -> dtype[uintc]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Literal[
-            "complex64",
-            "c8",
-            "=c8",
-            "<c8",
-            ">c8",
-            "F",
-            "=F",
-            "<F",
-            ">F",
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[complex64]: ...
+    def __new__(cls, dtype: _UIntPCodes, align: bool = ..., copy: bool = ...) -> dtype[uintp]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Union[
-            Type[complex],
-            Literal[
-                "complex128",
-                "c16",
-                "=c16",
-                "<c16",
-                ">c16",
-                "D",
-                "=D",
-                "<D",
-                ">D",
-            ],
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[complex128]: ...
+    def __new__(cls, dtype: _UIntCodes, align: bool = ..., copy: bool = ...) -> dtype[uint]: ...
     @overload
-    def __new__(
-        cls,
-        dtype: Union[
-            Type[bytes],
-            Literal[
-                "S",
-                "=S",
-                "<S",
-                ">S",
-                "bytes",
-                "bytes_",
-                "bytes0",
-            ],
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[bytes_]: ...
+    def __new__(cls, dtype: _ULongLongCodes, align: bool = ..., copy: bool = ...) -> dtype[ulonglong]: ...
+
+    # `signedinteger` string-based representations
     @overload
-    def __new__(
-        cls,
-        dtype: Union[
-            Type[str],
-            Literal[
-                "U",
-                "=U",
-                # <U and >U intentionally not included; they are not
-                # the same dtype and which one dtype("U") translates
-                # to is platform-dependent.
-                "str",
-                "str_",
-                "str0",
-            ],
-        ],
-        align: bool = ...,
-        copy: bool = ...,
-    ) -> dtype[str_]: ...
+    def __new__(cls, dtype: _Int8Codes, align: bool = ..., copy: bool = ...) -> dtype[int8]: ...
+    @overload
+    def __new__(cls, dtype: _Int16Codes, align: bool = ..., copy: bool = ...) -> dtype[int16]: ...
+    @overload
+    def __new__(cls, dtype: _Int32Codes, align: bool = ..., copy: bool = ...) -> dtype[int32]: ...
+    @overload
+    def __new__(cls, dtype: _Int64Codes, align: bool = ..., copy: bool = ...) -> dtype[int64]: ...
+    @overload
+    def __new__(cls, dtype: _ByteCodes, align: bool = ..., copy: bool = ...) -> dtype[byte]: ...
+    @overload
+    def __new__(cls, dtype: _ShortCodes, align: bool = ..., copy: bool = ...) -> dtype[short]: ...
+    @overload
+    def __new__(cls, dtype: _IntCCodes, align: bool = ..., copy: bool = ...) -> dtype[intc]: ...
+    @overload
+    def __new__(cls, dtype: _IntPCodes, align: bool = ..., copy: bool = ...) -> dtype[intp]: ...
+    @overload
+    def __new__(cls, dtype: _IntCodes, align: bool = ..., copy: bool = ...) -> dtype[int_]: ...
+    @overload
+    def __new__(cls, dtype: _LongLongCodes, align: bool = ..., copy: bool = ...) -> dtype[longlong]: ...
+
+    # `floating` string-based representations
+    @overload
+    def __new__(cls, dtype: _Float16Codes, align: bool = ..., copy: bool = ...) -> dtype[float16]: ...
+    @overload
+    def __new__(cls, dtype: _Float32Codes, align: bool = ..., copy: bool = ...) -> dtype[float32]: ...
+    @overload
+    def __new__(cls, dtype: _Float64Codes, align: bool = ..., copy: bool = ...) -> dtype[float64]: ...
+    @overload
+    def __new__(cls, dtype: _HalfCodes, align: bool = ..., copy: bool = ...) -> dtype[half]: ...
+    @overload
+    def __new__(cls, dtype: _SingleCodes, align: bool = ..., copy: bool = ...) -> dtype[single]: ...
+    @overload
+    def __new__(cls, dtype: _DoubleCodes, align: bool = ..., copy: bool = ...) -> dtype[double]: ...
+    @overload
+    def __new__(cls, dtype: _LongDoubleCodes, align: bool = ..., copy: bool = ...) -> dtype[longdouble]: ...
+
+    # `complexfloating` string-based representations
+    @overload
+    def __new__(cls, dtype: _Complex64Codes, align: bool = ..., copy: bool = ...) -> dtype[complex64]: ...
+    @overload
+    def __new__(cls, dtype: _Complex128Codes, align: bool = ..., copy: bool = ...) -> dtype[complex128]: ...
+    @overload
+    def __new__(cls, dtype: _CSingleCodes, align: bool = ..., copy: bool = ...) -> dtype[csingle]: ...
+    @overload
+    def __new__(cls, dtype: _CDoubleCodes, align: bool = ..., copy: bool = ...) -> dtype[cdouble]: ...
+    @overload
+    def __new__(cls, dtype: _CLongDoubleCodes, align: bool = ..., copy: bool = ...) -> dtype[clongdouble]: ...
+
+    # Miscellaneous string-based representations
+    @overload
+    def __new__(cls, dtype: _BoolCodes, align: bool = ..., copy: bool = ...) -> dtype[bool_]: ...
+    @overload
+    def __new__(cls, dtype: _TD64Codes, align: bool = ..., copy: bool = ...) -> dtype[timedelta64]: ...
+    @overload
+    def __new__(cls, dtype: _DT64Codes, align: bool = ..., copy: bool = ...) -> dtype[datetime64]: ...
+    @overload
+    def __new__(cls, dtype: _StrCodes, align: bool = ..., copy: bool = ...) -> dtype[str_]: ...
+    @overload
+    def __new__(cls, dtype: _BytesCodes, align: bool = ..., copy: bool = ...) -> dtype[bytes_]: ...
+    @overload
+    def __new__(cls, dtype: _VoidCodes, align: bool = ..., copy: bool = ...) -> dtype[void]: ...
+    @overload
+    def __new__(cls, dtype: _ObjectCodes, align: bool = ..., copy: bool = ...) -> dtype[object_]: ...
+
     # dtype of a dtype is the same dtype
     @overload
     def __new__(
diff --git a/numpy/typing/__init__.py b/numpy/typing/__init__.py
index 694046609..9f8e27573 100644
--- a/numpy/typing/__init__.py
+++ b/numpy/typing/__init__.py
@@ -241,6 +241,47 @@ from ._nbit import (
     _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,
     _BoolLike,
diff --git a/numpy/typing/_char_codes.py b/numpy/typing/_char_codes.py
new file mode 100644
index 000000000..7e5b82cfa
--- /dev/null
+++ b/numpy/typing/_char_codes.py
@@ -0,0 +1,115 @@
+import sys
+from typing import Any, TYPE_CHECKING
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+    HAVE_LITERAL = True
+else:
+    try:
+        from typing_extensions import Literal
+    except ImportError:
+        HAVE_LITERAL = False
+    else:
+        HAVE_LITERAL = True
+
+if TYPE_CHECKING or HAVE_LITERAL:
+    _BoolCodes = Literal["?", "=?", "<?", ">?", "bool", "bool_", "bool8"]
+
+    _UInt8Codes = Literal["uint8", "u1", "=u1", "<u1", ">u1"]
+    _UInt16Codes = Literal["uint16", "u2", "=u2", "<u2", ">u2"]
+    _UInt32Codes = Literal["uint32", "u4", "=u4", "<u4", ">u4"]
+    _UInt64Codes = Literal["uint64", "u8", "=u8", "<u8", ">u8"]
+
+    _Int8Codes = Literal["int8", "i1", "=i1", "<i1", ">i1"]
+    _Int16Codes = Literal["int16", "i2", "=i2", "<i2", ">i2"]
+    _Int32Codes = Literal["int32", "i4", "=i4", "<i4", ">i4"]
+    _Int64Codes = Literal["int64", "i8", "=i8", "<i8", ">i8"]
+
+    _Float16Codes = Literal["float16", "f2", "=f2", "<f2", ">f2"]
+    _Float32Codes = Literal["float32", "f4", "=f4", "<f4", ">f4"]
+    _Float64Codes = Literal["float64", "f8", "=f8", "<f8", ">f8"]
+
+    _Complex64Codes = Literal["complex64", "c8", "=c8", "<c8", ">c8"]
+    _Complex128Codes = Literal["complex128", "c16", "=c16", "<c16", ">c16"]
+
+    _ByteCodes = Literal["byte", "b", "=b", "<b", ">b"]
+    _ShortCodes = Literal["short", "h", "=h", "<h", ">h"]
+    _IntCCodes = Literal["intc", "i", "=i", "<i", ">i"]
+    _IntPCodes = Literal["intp", "int0", "p", "=p", "<p", ">p"]
+    _IntCodes = Literal["long", "int", "int_", "l", "=l", "<l", ">l"]
+    _LongLongCodes = Literal["longlong", "q", "=q", "<q", ">q"]
+
+    _UByteCodes = Literal["ubyte", "B", "=B", "<B", ">B"]
+    _UShortCodes = Literal["ushort", "H", "=H", "<H", ">H"]
+    _UIntCCodes = Literal["uintc", "I", "=I", "<I", ">I"]
+    _UIntPCodes = Literal["uintp", "uint0", "P", "=P", "<P", ">P"]
+    _UIntCodes = Literal["uint", "L", "=L", "<L", ">L"]
+    _ULongLongCodes = Literal["ulonglong", "Q", "=Q", "<Q", ">Q"]
+
+    _HalfCodes = Literal["half", "e", "=e", "<e", ">e"]
+    _SingleCodes = Literal["single", "f", "=f", "<f", ">f"]
+    _DoubleCodes = Literal["double" "float", "float_", "d", "=d", "<d", ">d"]
+    _LongDoubleCodes = Literal["longdouble", "longfloat", "g", "=g", "<g", ">g"]
+
+    _CSingleCodes = Literal["csingle", "singlecomplex", "F", "=F", "<F", ">F"]
+    _CDoubleCodes = Literal["cdouble" "complex", "complex_", "cfloat", "D", "=D", "<D", ">D"]
+    _CLongDoubleCodes = Literal["clongdouble", "clongfloat", "longcomplex", "G", "=G", "<G", ">G"]
+
+    _DT64Codes = Literal["datetime64", "M", "=M", "<M", ">M"]
+    _TD64Codes = Literal["timedelta64", "m", "=m", "<m", ">m"]
+
+    _StrCodes = Literal["str", "str_", "str0", "unicode", "unicode_", "U", "=U", "<U", ">U"]
+    _BytesCodes = Literal["bytes", "bytes_", "bytes0", "S", "=S", "<S", ">S"]
+    _VoidCodes = Literal["void", "void0", "V", "=V", "<V", ">V"]
+    _ObjectCodes = Literal["object", "object_", "O", "=O", "<O", ">O"]
+
+else:
+    _BoolCodes = Any
+
+    _UInt8Codes = Any
+    _UInt16Codes = Any
+    _UInt32Codes = Any
+    _UInt64Codes = Any
+
+    _Int8Codes = Any
+    _Int16Codes = Any
+    _Int32Codes = Any
+    _Int64Codes = Any
+
+    _Float16Codes = Any
+    _Float32Codes = Any
+    _Float64Codes = Any
+
+    _Complex64Codes = Any
+    _Complex128Codes = Any
+
+    _ByteCodes = Any
+    _ShortCodes = Any
+    _IntCCodes = Any
+    _IntPCodes = Any
+    _IntCodes = Any
+    _LongLongCodes = Any
+
+    _UByteCodes = Any
+    _UShortCodes = Any
+    _UIntCCodes = Any
+    _UIntPCodes = Any
+    _UIntCodes = Any
+    _ULongLongCodes = Any
+
+    _HalfCodes = Any
+    _SingleCodes = Any
+    _DoubleCodes = Any
+    _LongDoubleCodes = Any
+
+    _CSingleCodes = Any
+    _CDoubleCodes = Any
+    _CLongDoubleCodes = Any
+
+    _DT64Codes = Any
+    _TD64Codes = Any
+
+    _StrCodes = Any
+    _BytesCodes = Any
+    _VoidCodes = Any
+    _ObjectCodes = Any