numpy 2.3.5__cp313-cp313-macosx_14_0_arm64.whl

numpy/_typing/__init__.py

@@ -0,0 +1,148 @@
+"""Private counterpart of ``numpy.typing``."""
+
+from ._array_like import ArrayLike as ArrayLike
+from ._array_like import NDArray as NDArray
+from ._array_like import _ArrayLike as _ArrayLike
+from ._array_like import _ArrayLikeAnyString_co as _ArrayLikeAnyString_co
+from ._array_like import _ArrayLikeBool_co as _ArrayLikeBool_co
+from ._array_like import _ArrayLikeBytes_co as _ArrayLikeBytes_co
+from ._array_like import _ArrayLikeComplex128_co as _ArrayLikeComplex128_co
+from ._array_like import _ArrayLikeComplex_co as _ArrayLikeComplex_co
+from ._array_like import _ArrayLikeDT64_co as _ArrayLikeDT64_co
+from ._array_like import _ArrayLikeFloat64_co as _ArrayLikeFloat64_co
+from ._array_like import _ArrayLikeFloat_co as _ArrayLikeFloat_co
+from ._array_like import _ArrayLikeInt as _ArrayLikeInt
+from ._array_like import _ArrayLikeInt_co as _ArrayLikeInt_co
+from ._array_like import _ArrayLikeNumber_co as _ArrayLikeNumber_co
+from ._array_like import _ArrayLikeObject_co as _ArrayLikeObject_co
+from ._array_like import _ArrayLikeStr_co as _ArrayLikeStr_co
+from ._array_like import _ArrayLikeString_co as _ArrayLikeString_co
+from ._array_like import _ArrayLikeTD64_co as _ArrayLikeTD64_co
+from ._array_like import _ArrayLikeUInt_co as _ArrayLikeUInt_co
+from ._array_like import _ArrayLikeVoid_co as _ArrayLikeVoid_co
+from ._array_like import _FiniteNestedSequence as _FiniteNestedSequence
+from ._array_like import _SupportsArray as _SupportsArray
+from ._array_like import _SupportsArrayFunc as _SupportsArrayFunc
+
+#
+from ._char_codes import _BoolCodes as _BoolCodes
+from ._char_codes import _ByteCodes as _ByteCodes
+from ._char_codes import _BytesCodes as _BytesCodes
+from ._char_codes import _CDoubleCodes as _CDoubleCodes
+from ._char_codes import _CharacterCodes as _CharacterCodes
+from ._char_codes import _CLongDoubleCodes as _CLongDoubleCodes
+from ._char_codes import _Complex64Codes as _Complex64Codes
+from ._char_codes import _Complex128Codes as _Complex128Codes
+from ._char_codes import _ComplexFloatingCodes as _ComplexFloatingCodes
+from ._char_codes import _CSingleCodes as _CSingleCodes
+from ._char_codes import _DoubleCodes as _DoubleCodes
+from ._char_codes import _DT64Codes as _DT64Codes
+from ._char_codes import _FlexibleCodes as _FlexibleCodes
+from ._char_codes import _Float16Codes as _Float16Codes
+from ._char_codes import _Float32Codes as _Float32Codes
+from ._char_codes import _Float64Codes as _Float64Codes
+from ._char_codes import _FloatingCodes as _FloatingCodes
+from ._char_codes import _GenericCodes as _GenericCodes
+from ._char_codes import _HalfCodes as _HalfCodes
+from ._char_codes import _InexactCodes as _InexactCodes
+from ._char_codes import _Int8Codes as _Int8Codes
+from ._char_codes import _Int16Codes as _Int16Codes
+from ._char_codes import _Int32Codes as _Int32Codes
+from ._char_codes import _Int64Codes as _Int64Codes
+from ._char_codes import _IntCCodes as _IntCCodes
+from ._char_codes import _IntCodes as _IntCodes
+from ._char_codes import _IntegerCodes as _IntegerCodes
+from ._char_codes import _IntPCodes as _IntPCodes
+from ._char_codes import _LongCodes as _LongCodes
+from ._char_codes import _LongDoubleCodes as _LongDoubleCodes
+from ._char_codes import _LongLongCodes as _LongLongCodes
+from ._char_codes import _NumberCodes as _NumberCodes
+from ._char_codes import _ObjectCodes as _ObjectCodes
+from ._char_codes import _ShortCodes as _ShortCodes
+from ._char_codes import _SignedIntegerCodes as _SignedIntegerCodes
+from ._char_codes import _SingleCodes as _SingleCodes
+from ._char_codes import _StrCodes as _StrCodes
+from ._char_codes import _StringCodes as _StringCodes
+from ._char_codes import _TD64Codes as _TD64Codes
+from ._char_codes import _UByteCodes as _UByteCodes
+from ._char_codes import _UInt8Codes as _UInt8Codes
+from ._char_codes import _UInt16Codes as _UInt16Codes
+from ._char_codes import _UInt32Codes as _UInt32Codes
+from ._char_codes import _UInt64Codes as _UInt64Codes
+from ._char_codes import _UIntCCodes as _UIntCCodes
+from ._char_codes import _UIntCodes as _UIntCodes
+from ._char_codes import _UIntPCodes as _UIntPCodes
+from ._char_codes import _ULongCodes as _ULongCodes
+from ._char_codes import _ULongLongCodes as _ULongLongCodes
+from ._char_codes import _UnsignedIntegerCodes as _UnsignedIntegerCodes
+from ._char_codes import _UShortCodes as _UShortCodes
+from ._char_codes import _VoidCodes as _VoidCodes
+
+#
+from ._dtype_like import DTypeLike as DTypeLike
+from ._dtype_like import _DTypeLike as _DTypeLike
+from ._dtype_like import _DTypeLikeBool as _DTypeLikeBool
+from ._dtype_like import _DTypeLikeBytes as _DTypeLikeBytes
+from ._dtype_like import _DTypeLikeComplex as _DTypeLikeComplex
+from ._dtype_like import _DTypeLikeComplex_co as _DTypeLikeComplex_co
+from ._dtype_like import _DTypeLikeDT64 as _DTypeLikeDT64
+from ._dtype_like import _DTypeLikeFloat as _DTypeLikeFloat
+from ._dtype_like import _DTypeLikeInt as _DTypeLikeInt
+from ._dtype_like import _DTypeLikeObject as _DTypeLikeObject
+from ._dtype_like import _DTypeLikeStr as _DTypeLikeStr
+from ._dtype_like import _DTypeLikeTD64 as _DTypeLikeTD64
+from ._dtype_like import _DTypeLikeUInt as _DTypeLikeUInt
+from ._dtype_like import _DTypeLikeVoid as _DTypeLikeVoid
+from ._dtype_like import _SupportsDType as _SupportsDType
+from ._dtype_like import _VoidDTypeLike as _VoidDTypeLike
+
+#
+from ._nbit import _NBitByte as _NBitByte
+from ._nbit import _NBitDouble as _NBitDouble
+from ._nbit import _NBitHalf as _NBitHalf
+from ._nbit import _NBitInt as _NBitInt
+from ._nbit import _NBitIntC as _NBitIntC
+from ._nbit import _NBitIntP as _NBitIntP
+from ._nbit import _NBitLong as _NBitLong
+from ._nbit import _NBitLongDouble as _NBitLongDouble
+from ._nbit import _NBitLongLong as _NBitLongLong
+from ._nbit import _NBitShort as _NBitShort
+from ._nbit import _NBitSingle as _NBitSingle
+
+#
+from ._nbit_base import (
+    NBitBase as NBitBase,  # type: ignore[deprecated]  # pyright: ignore[reportDeprecated]
+)
+from ._nbit_base import _8Bit as _8Bit
+from ._nbit_base import _16Bit as _16Bit
+from ._nbit_base import _32Bit as _32Bit
+from ._nbit_base import _64Bit as _64Bit
+from ._nbit_base import _96Bit as _96Bit
+from ._nbit_base import _128Bit as _128Bit
+
+#
+from ._nested_sequence import _NestedSequence as _NestedSequence
+
+#
+from ._scalars import _BoolLike_co as _BoolLike_co
+from ._scalars import _CharLike_co as _CharLike_co
+from ._scalars import _ComplexLike_co as _ComplexLike_co
+from ._scalars import _FloatLike_co as _FloatLike_co
+from ._scalars import _IntLike_co as _IntLike_co
+from ._scalars import _NumberLike_co as _NumberLike_co
+from ._scalars import _ScalarLike_co as _ScalarLike_co
+from ._scalars import _TD64Like_co as _TD64Like_co
+from ._scalars import _UIntLike_co as _UIntLike_co
+from ._scalars import _VoidLike_co as _VoidLike_co
+
+#
+from ._shape import _AnyShape as _AnyShape
+from ._shape import _Shape as _Shape
+from ._shape import _ShapeLike as _ShapeLike
+
+#
+from ._ufunc import _GUFunc_Nin2_Nout1 as _GUFunc_Nin2_Nout1
+from ._ufunc import _UFunc_Nin1_Nout1 as _UFunc_Nin1_Nout1
+from ._ufunc import _UFunc_Nin1_Nout2 as _UFunc_Nin1_Nout2
+from ._ufunc import _UFunc_Nin2_Nout1 as _UFunc_Nin2_Nout1
+from ._ufunc import _UFunc_Nin2_Nout2 as _UFunc_Nin2_Nout2

numpy/_typing/_add_docstring.py

@@ -0,0 +1,153 @@
+"""A module for creating docstrings for sphinx ``data`` domains."""
+
+import re
+import textwrap
+
+from ._array_like import NDArray
+
+_docstrings_list = []
+
+
+def add_newdoc(name: str, value: str, doc: str) -> None:
+    """Append ``_docstrings_list`` with a docstring for `name`.
+
+    Parameters
+    ----------
+    name : str
+        The name of the object.
+    value : str
+        A string-representation of the object.
+    doc : str
+        The docstring of the object.
+
+    """
+    _docstrings_list.append((name, value, doc))
+
+
+def _parse_docstrings() -> str:
+    """Convert all docstrings in ``_docstrings_list`` into a single
+    sphinx-legible text block.
+
+    """
+    type_list_ret = []
+    for name, value, doc in _docstrings_list:
+        s = textwrap.dedent(doc).replace("\n", "\n    ")
+
+        # Replace sections by rubrics
+        lines = s.split("\n")
+        new_lines = []
+        indent = ""
+        for line in lines:
+            m = re.match(r'^(\s+)[-=]+\s*$', line)
+            if m and new_lines:
+                prev = textwrap.dedent(new_lines.pop())
+                if prev == "Examples":
+                    indent = ""
+                    new_lines.append(f'{m.group(1)}.. rubric:: {prev}')
+                else:
+                    indent = 4 * " "
+                    new_lines.append(f'{m.group(1)}.. admonition:: {prev}')
+                new_lines.append("")
+            else:
+                new_lines.append(f"{indent}{line}")
+
+        s = "\n".join(new_lines)
+        s_block = f""".. data:: {name}\n    :value: {value}\n    {s}"""
+        type_list_ret.append(s_block)
+    return "\n".join(type_list_ret)
+
+
+add_newdoc('ArrayLike', 'typing.Union[...]',
+    """
+    A `~typing.Union` representing objects that can be coerced
+    into an `~numpy.ndarray`.
+
+    Among others this includes the likes of:
+
+    * Scalars.
+    * (Nested) sequences.
+    * Objects implementing the `~class.__array__` protocol.
+
+    .. versionadded:: 1.20
+
+    See Also
+    --------
+    :term:`array_like`:
+        Any scalar or sequence that can be interpreted as an ndarray.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        >>> import numpy as np
+        >>> import numpy.typing as npt
+
+        >>> def as_array(a: npt.ArrayLike) -> np.ndarray:
+        ...     return np.array(a)
+
+    """)
+
+add_newdoc('DTypeLike', 'typing.Union[...]',
+    """
+    A `~typing.Union` representing objects that can be coerced
+    into a `~numpy.dtype`.
+
+    Among others this includes the likes of:
+
+    * :class:`type` objects.
+    * Character codes or the names of :class:`type` objects.
+    * Objects with the ``.dtype`` attribute.
+
+    .. versionadded:: 1.20
+
+    See Also
+    --------
+    :ref:`Specifying and constructing data types <arrays.dtypes.constructing>`
+        A comprehensive overview of all objects that can be coerced
+        into data types.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        >>> import numpy as np
+        >>> import numpy.typing as npt
+
+        >>> def as_dtype(d: npt.DTypeLike) -> np.dtype:
+        ...     return np.dtype(d)
+
+    """)
+
+add_newdoc('NDArray', repr(NDArray),
+    """
+    A `np.ndarray[tuple[Any, ...], np.dtype[ScalarT]] <numpy.ndarray>`
+    type alias :term:`generic <generic type>` w.r.t. its
+    `dtype.type <numpy.dtype.type>`.
+
+    Can be used during runtime for typing arrays with a given dtype
+    and unspecified shape.
+
+    .. versionadded:: 1.21
+
+    Examples
+    --------
+    .. code-block:: python
+
+        >>> import numpy as np
+        >>> import numpy.typing as npt
+
+        >>> print(npt.NDArray)
+        numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[~_ScalarT]]
+
+        >>> print(npt.NDArray[np.float64])
+        numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]]
+
+        >>> NDArrayInt = npt.NDArray[np.int_]
+        >>> a: NDArrayInt = np.arange(10)
+
+        >>> def func(a: npt.ArrayLike) -> npt.NDArray[Any]:
+        ...     return np.array(a)
+
+    """)
+
+_docstrings = _parse_docstrings()

numpy/_typing/_array_like.py

@@ -0,0 +1,106 @@
+import sys
+from collections.abc import Callable, Collection, Sequence
+from typing import TYPE_CHECKING, Any, Protocol, TypeAlias, TypeVar, runtime_checkable
+
+import numpy as np
+from numpy import dtype
+
+from ._nbit_base import _32Bit, _64Bit
+from ._nested_sequence import _NestedSequence
+from ._shape import _AnyShape
+
+if TYPE_CHECKING:
+    StringDType = np.dtypes.StringDType
+else:
+    # at runtime outside of type checking importing this from numpy.dtypes
+    # would lead to a circular import
+    from numpy._core.multiarray import StringDType
+
+_T = TypeVar("_T")
+_ScalarT = TypeVar("_ScalarT", bound=np.generic)
+_DTypeT = TypeVar("_DTypeT", bound=dtype[Any])
+_DTypeT_co = TypeVar("_DTypeT_co", covariant=True, bound=dtype[Any])
+
+NDArray: TypeAlias = np.ndarray[_AnyShape, dtype[_ScalarT]]
+
+# The `_SupportsArray` protocol only cares about the default dtype
+# (i.e. `dtype=None` or no `dtype` parameter at all) of the to-be returned
+# array.
+# Concrete implementations of the protocol are responsible for adding
+# any and all remaining overloads
+@runtime_checkable
+class _SupportsArray(Protocol[_DTypeT_co]):
+    def __array__(self) -> np.ndarray[Any, _DTypeT_co]: ...
+
+
+@runtime_checkable
+class _SupportsArrayFunc(Protocol):
+    """A protocol class representing `~class.__array_function__`."""
+    def __array_function__(
+        self,
+        func: Callable[..., Any],
+        types: Collection[type[Any]],
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+    ) -> object: ...
+
+
+# TODO: Wait until mypy supports recursive objects in combination with typevars
+_FiniteNestedSequence: TypeAlias = (
+    _T
+    | Sequence[_T]
+    | Sequence[Sequence[_T]]
+    | Sequence[Sequence[Sequence[_T]]]
+    | Sequence[Sequence[Sequence[Sequence[_T]]]]
+)
+
+# A subset of `npt.ArrayLike` that can be parametrized w.r.t. `np.generic`
+_ArrayLike: TypeAlias = (
+    _SupportsArray[dtype[_ScalarT]]
+    | _NestedSequence[_SupportsArray[dtype[_ScalarT]]]
+)
+
+# A union representing array-like objects; consists of two typevars:
+# One representing types that can be parametrized w.r.t. `np.dtype`
+# and another one for the rest
+_DualArrayLike: TypeAlias = (
+    _SupportsArray[_DTypeT]
+    | _NestedSequence[_SupportsArray[_DTypeT]]
+    | _T
+    | _NestedSequence[_T]
+)
+
+if sys.version_info >= (3, 12):
+    from collections.abc import Buffer as _Buffer
+else:
+    @runtime_checkable
+    class _Buffer(Protocol):
+        def __buffer__(self, flags: int, /) -> memoryview: ...
+
+ArrayLike: TypeAlias = _Buffer | _DualArrayLike[dtype[Any], complex | bytes | str]
+
+# `ArrayLike<X>_co`: array-like objects that can be coerced into `X`
+# given the casting rules `same_kind`
+_ArrayLikeBool_co: TypeAlias = _DualArrayLike[dtype[np.bool], bool]
+_ArrayLikeUInt_co: TypeAlias = _DualArrayLike[dtype[np.bool | np.unsignedinteger], bool]
+_ArrayLikeInt_co: TypeAlias = _DualArrayLike[dtype[np.bool | np.integer], int]
+_ArrayLikeFloat_co: TypeAlias = _DualArrayLike[dtype[np.bool | np.integer | np.floating], float]
+_ArrayLikeComplex_co: TypeAlias = _DualArrayLike[dtype[np.bool | np.number], complex]
+_ArrayLikeNumber_co: TypeAlias = _ArrayLikeComplex_co
+_ArrayLikeTD64_co: TypeAlias = _DualArrayLike[dtype[np.bool | np.integer | np.timedelta64], int]
+_ArrayLikeDT64_co: TypeAlias = _ArrayLike[np.datetime64]
+_ArrayLikeObject_co: TypeAlias = _ArrayLike[np.object_]
+
+_ArrayLikeVoid_co: TypeAlias = _ArrayLike[np.void]
+_ArrayLikeBytes_co: TypeAlias = _DualArrayLike[dtype[np.bytes_], bytes]
+_ArrayLikeStr_co: TypeAlias = _DualArrayLike[dtype[np.str_], str]
+_ArrayLikeString_co: TypeAlias = _DualArrayLike[StringDType, str]
+_ArrayLikeAnyString_co: TypeAlias = _DualArrayLike[dtype[np.character] | StringDType, bytes | str]
+
+__Float64_co: TypeAlias = np.floating[_64Bit] | np.float32 | np.float16 | np.integer | np.bool
+__Complex128_co: TypeAlias = np.number[_64Bit] | np.number[_32Bit] | np.float16 | np.integer | np.bool
+_ArrayLikeFloat64_co: TypeAlias = _DualArrayLike[dtype[__Float64_co], float]
+_ArrayLikeComplex128_co: TypeAlias = _DualArrayLike[dtype[__Complex128_co], complex]
+
+# NOTE: This includes `builtins.bool`, but not `numpy.bool`.
+_ArrayLikeInt: TypeAlias = _DualArrayLike[dtype[np.integer], int]

numpy/_typing/_char_codes.py

@@ -0,0 +1,213 @@
+from typing import Literal
+
+_BoolCodes = Literal[
+    "bool", "bool_",
+    "?", "|?", "=?", "<?", ">?",
+    "b1", "|b1", "=b1", "<b1", ">b1",
+]  # fmt: skip
+
+_UInt8Codes = Literal["uint8", "u1", "|u1", "=u1", "<u1", ">u1"]
+_UInt16Codes = Literal["uint16", "u2", "|u2", "=u2", "<u2", ">u2"]
+_UInt32Codes = Literal["uint32", "u4", "|u4", "=u4", "<u4", ">u4"]
+_UInt64Codes = Literal["uint64", "u8", "|u8", "=u8", "<u8", ">u8"]
+
+_Int8Codes = Literal["int8", "i1", "|i1", "=i1", "<i1", ">i1"]
+_Int16Codes = Literal["int16", "i2", "|i2", "=i2", "<i2", ">i2"]
+_Int32Codes = Literal["int32", "i4", "|i4", "=i4", "<i4", ">i4"]
+_Int64Codes = Literal["int64", "i8", "|i8", "=i8", "<i8", ">i8"]
+
+_Float16Codes = Literal["float16", "f2", "|f2", "=f2", "<f2", ">f2"]
+_Float32Codes = Literal["float32", "f4", "|f4", "=f4", "<f4", ">f4"]
+_Float64Codes = Literal["float64", "f8", "|f8", "=f8", "<f8", ">f8"]
+
+_Complex64Codes = Literal["complex64", "c8", "|c8", "=c8", "<c8", ">c8"]
+_Complex128Codes = Literal["complex128", "c16", "|c16", "=c16", "<c16", ">c16"]
+
+_ByteCodes = Literal["byte", "b", "|b", "=b", "<b", ">b"]
+_ShortCodes = Literal["short", "h", "|h", "=h", "<h", ">h"]
+_IntCCodes = Literal["intc", "i", "|i", "=i", "<i", ">i"]
+_IntPCodes = Literal["intp", "int", "int_", "n", "|n", "=n", "<n", ">n"]
+_LongCodes = Literal["long", "l", "|l", "=l", "<l", ">l"]
+_IntCodes = _IntPCodes
+_LongLongCodes = Literal["longlong", "q", "|q", "=q", "<q", ">q"]
+
+_UByteCodes = Literal["ubyte", "B", "|B", "=B", "<B", ">B"]
+_UShortCodes = Literal["ushort", "H", "|H", "=H", "<H", ">H"]
+_UIntCCodes = Literal["uintc", "I", "|I", "=I", "<I", ">I"]
+_UIntPCodes = Literal["uintp", "uint", "N", "|N", "=N", "<N", ">N"]
+_ULongCodes = Literal["ulong", "L", "|L", "=L", "<L", ">L"]
+_UIntCodes = _UIntPCodes
+_ULongLongCodes = Literal["ulonglong", "Q", "|Q", "=Q", "<Q", ">Q"]
+
+_HalfCodes = Literal["half", "e", "|e", "=e", "<e", ">e"]
+_SingleCodes = Literal["single", "f", "|f", "=f", "<f", ">f"]
+_DoubleCodes = Literal["double", "float", "d", "|d", "=d", "<d", ">d"]
+_LongDoubleCodes = Literal["longdouble", "g", "|g", "=g", "<g", ">g"]
+
+_CSingleCodes = Literal["csingle", "F", "|F", "=F", "<F", ">F"]
+_CDoubleCodes = Literal["cdouble", "complex", "D", "|D", "=D", "<D", ">D"]
+_CLongDoubleCodes = Literal["clongdouble", "G", "|G", "=G", "<G", ">G"]
+
+_StrCodes = Literal["str", "str_", "unicode", "U", "|U", "=U", "<U", ">U"]
+_BytesCodes = Literal["bytes", "bytes_", "S", "|S", "=S", "<S", ">S"]
+_VoidCodes = Literal["void", "V", "|V", "=V", "<V", ">V"]
+_ObjectCodes = Literal["object", "object_", "O", "|O", "=O", "<O", ">O"]
+
+_DT64Codes = Literal[
+    "datetime64", "|datetime64", "=datetime64",
+    "<datetime64", ">datetime64",
+    "datetime64[Y]", "|datetime64[Y]", "=datetime64[Y]",
+    "<datetime64[Y]", ">datetime64[Y]",
+    "datetime64[M]", "|datetime64[M]", "=datetime64[M]",
+    "<datetime64[M]", ">datetime64[M]",
+    "datetime64[W]", "|datetime64[W]", "=datetime64[W]",
+    "<datetime64[W]", ">datetime64[W]",
+    "datetime64[D]", "|datetime64[D]", "=datetime64[D]",
+    "<datetime64[D]", ">datetime64[D]",
+    "datetime64[h]", "|datetime64[h]", "=datetime64[h]",
+    "<datetime64[h]", ">datetime64[h]",
+    "datetime64[m]", "|datetime64[m]", "=datetime64[m]",
+    "<datetime64[m]", ">datetime64[m]",
+    "datetime64[s]", "|datetime64[s]", "=datetime64[s]",
+    "<datetime64[s]", ">datetime64[s]",
+    "datetime64[ms]", "|datetime64[ms]", "=datetime64[ms]",
+    "<datetime64[ms]", ">datetime64[ms]",
+    "datetime64[us]", "|datetime64[us]", "=datetime64[us]",
+    "<datetime64[us]", ">datetime64[us]",
+    "datetime64[ns]", "|datetime64[ns]", "=datetime64[ns]",
+    "<datetime64[ns]", ">datetime64[ns]",
+    "datetime64[ps]", "|datetime64[ps]", "=datetime64[ps]",
+    "<datetime64[ps]", ">datetime64[ps]",
+    "datetime64[fs]", "|datetime64[fs]", "=datetime64[fs]",
+    "<datetime64[fs]", ">datetime64[fs]",
+    "datetime64[as]", "|datetime64[as]", "=datetime64[as]",
+    "<datetime64[as]", ">datetime64[as]",
+    "M", "|M", "=M", "<M", ">M",
+    "M8", "|M8", "=M8", "<M8", ">M8",
+    "M8[Y]", "|M8[Y]", "=M8[Y]", "<M8[Y]", ">M8[Y]",
+    "M8[M]", "|M8[M]", "=M8[M]", "<M8[M]", ">M8[M]",
+    "M8[W]", "|M8[W]", "=M8[W]", "<M8[W]", ">M8[W]",
+    "M8[D]", "|M8[D]", "=M8[D]", "<M8[D]", ">M8[D]",
+    "M8[h]", "|M8[h]", "=M8[h]", "<M8[h]", ">M8[h]",
+    "M8[m]", "|M8[m]", "=M8[m]", "<M8[m]", ">M8[m]",
+    "M8[s]", "|M8[s]", "=M8[s]", "<M8[s]", ">M8[s]",
+    "M8[ms]", "|M8[ms]", "=M8[ms]", "<M8[ms]", ">M8[ms]",
+    "M8[us]", "|M8[us]", "=M8[us]", "<M8[us]", ">M8[us]",
+    "M8[ns]", "|M8[ns]", "=M8[ns]", "<M8[ns]", ">M8[ns]",
+    "M8[ps]", "|M8[ps]", "=M8[ps]", "<M8[ps]", ">M8[ps]",
+    "M8[fs]", "|M8[fs]", "=M8[fs]", "<M8[fs]", ">M8[fs]",
+    "M8[as]", "|M8[as]", "=M8[as]", "<M8[as]", ">M8[as]",
+]
+_TD64Codes = Literal[
+    "timedelta64", "|timedelta64", "=timedelta64",
+    "<timedelta64", ">timedelta64",
+    "timedelta64[Y]", "|timedelta64[Y]", "=timedelta64[Y]",
+    "<timedelta64[Y]", ">timedelta64[Y]",
+    "timedelta64[M]", "|timedelta64[M]", "=timedelta64[M]",
+    "<timedelta64[M]", ">timedelta64[M]",
+    "timedelta64[W]", "|timedelta64[W]", "=timedelta64[W]",
+    "<timedelta64[W]", ">timedelta64[W]",
+    "timedelta64[D]", "|timedelta64[D]", "=timedelta64[D]",
+    "<timedelta64[D]", ">timedelta64[D]",
+    "timedelta64[h]", "|timedelta64[h]", "=timedelta64[h]",
+    "<timedelta64[h]", ">timedelta64[h]",
+    "timedelta64[m]", "|timedelta64[m]", "=timedelta64[m]",
+    "<timedelta64[m]", ">timedelta64[m]",
+    "timedelta64[s]", "|timedelta64[s]", "=timedelta64[s]",
+    "<timedelta64[s]", ">timedelta64[s]",
+    "timedelta64[ms]", "|timedelta64[ms]", "=timedelta64[ms]",
+    "<timedelta64[ms]", ">timedelta64[ms]",
+    "timedelta64[us]", "|timedelta64[us]", "=timedelta64[us]",
+    "<timedelta64[us]", ">timedelta64[us]",
+    "timedelta64[ns]", "|timedelta64[ns]", "=timedelta64[ns]",
+    "<timedelta64[ns]", ">timedelta64[ns]",
+    "timedelta64[ps]", "|timedelta64[ps]", "=timedelta64[ps]",
+    "<timedelta64[ps]", ">timedelta64[ps]",
+    "timedelta64[fs]", "|timedelta64[fs]", "=timedelta64[fs]",
+    "<timedelta64[fs]", ">timedelta64[fs]",
+    "timedelta64[as]", "|timedelta64[as]", "=timedelta64[as]",
+    "<timedelta64[as]", ">timedelta64[as]",
+    "m", "|m", "=m", "<m", ">m",
+    "m8", "|m8", "=m8", "<m8", ">m8",
+    "m8[Y]", "|m8[Y]", "=m8[Y]", "<m8[Y]", ">m8[Y]",
+    "m8[M]", "|m8[M]", "=m8[M]", "<m8[M]", ">m8[M]",
+    "m8[W]", "|m8[W]", "=m8[W]", "<m8[W]", ">m8[W]",
+    "m8[D]", "|m8[D]", "=m8[D]", "<m8[D]", ">m8[D]",
+    "m8[h]", "|m8[h]", "=m8[h]", "<m8[h]", ">m8[h]",
+    "m8[m]", "|m8[m]", "=m8[m]", "<m8[m]", ">m8[m]",
+    "m8[s]", "|m8[s]", "=m8[s]", "<m8[s]", ">m8[s]",
+    "m8[ms]", "|m8[ms]", "=m8[ms]", "<m8[ms]", ">m8[ms]",
+    "m8[us]", "|m8[us]", "=m8[us]", "<m8[us]", ">m8[us]",
+    "m8[ns]", "|m8[ns]", "=m8[ns]", "<m8[ns]", ">m8[ns]",
+    "m8[ps]", "|m8[ps]", "=m8[ps]", "<m8[ps]", ">m8[ps]",
+    "m8[fs]", "|m8[fs]", "=m8[fs]", "<m8[fs]", ">m8[fs]",
+    "m8[as]", "|m8[as]", "=m8[as]", "<m8[as]", ">m8[as]",
+]
+
+# NOTE: `StringDType' has no scalar type, and therefore has no name that can
+# be passed to the `dtype` constructor
+_StringCodes = Literal["T", "|T", "=T", "<T", ">T"]
+
+# NOTE: Nested literals get flattened and de-duplicated at runtime, which isn't
+# the case for a `Union` of `Literal`s.
+# So even though they're equivalent when type-checking, they differ at runtime.
+# Another advantage of nesting, is that they always have a "flat"
+# `Literal.__args__`, which is a tuple of *literally* all its literal values.
+
+_UnsignedIntegerCodes = Literal[
+    _UInt8Codes,
+    _UInt16Codes,
+    _UInt32Codes,
+    _UInt64Codes,
+    _UIntCodes,
+    _UByteCodes,
+    _UShortCodes,
+    _UIntCCodes,
+    _ULongCodes,
+    _ULongLongCodes,
+]
+_SignedIntegerCodes = Literal[
+    _Int8Codes,
+    _Int16Codes,
+    _Int32Codes,
+    _Int64Codes,
+    _IntCodes,
+    _ByteCodes,
+    _ShortCodes,
+    _IntCCodes,
+    _LongCodes,
+    _LongLongCodes,
+]
+_FloatingCodes = Literal[
+    _Float16Codes,
+    _Float32Codes,
+    _Float64Codes,
+    _HalfCodes,
+    _SingleCodes,
+    _DoubleCodes,
+    _LongDoubleCodes
+]
+_ComplexFloatingCodes = Literal[
+    _Complex64Codes,
+    _Complex128Codes,
+    _CSingleCodes,
+    _CDoubleCodes,
+    _CLongDoubleCodes,
+]
+_IntegerCodes = Literal[_UnsignedIntegerCodes, _SignedIntegerCodes]
+_InexactCodes = Literal[_FloatingCodes, _ComplexFloatingCodes]
+_NumberCodes = Literal[_IntegerCodes, _InexactCodes]
+
+_CharacterCodes = Literal[_StrCodes, _BytesCodes]
+_FlexibleCodes = Literal[_VoidCodes, _CharacterCodes]
+
+_GenericCodes = Literal[
+    _BoolCodes,
+    _NumberCodes,
+    _FlexibleCodes,
+    _DT64Codes,
+    _TD64Codes,
+    _ObjectCodes,
+    # TODO: add `_StringCodes` once it has a scalar type
+    # _StringCodes,
+]