sync 2026-10-29 07:40 GMT (part 3)

v12x/pylib/numpy/_array_api_info.py

@@ -0,0 +1,349 @@
+"""
+Array API Inspection namespace
+
+This is the namespace for inspection functions as defined by the array API
+standard. See
+https://data-apis.org/array-api/latest/API_specification/inspection.html for
+more details.
+
+"""
+from numpy._core import (
+    bool,
+    complex64,
+    complex128,
+    dtype,
+    float32,
+    float64,
+    int8,
+    int16,
+    int32,
+    int64,
+    intp,
+    uint8,
+    uint16,
+    uint32,
+    uint64,
+)
+from numpy._utils import set_module
+
+
+@set_module('numpy')
+class __array_namespace_info__:
+    """
+    Get the array API inspection namespace for NumPy.
+
+    The array API inspection namespace defines the following functions:
+
+    - capabilities()
+    - default_device()
+    - default_dtypes()
+    - dtypes()
+    - devices()
+
+    See
+    https://data-apis.org/array-api/latest/API_specification/inspection.html
+    for more details.
+
+    Returns
+    -------
+    info : ModuleType
+        The array API inspection namespace for NumPy.
+
+    Examples
+    --------
+    >>> info = np.__array_namespace_info__()
+    >>> info.default_dtypes()
+    {'real floating': numpy.float64,
+     'complex floating': numpy.complex128,
+     'integral': numpy.int64,
+     'indexing': numpy.int64}
+
+    """
+
+    def capabilities(self):
+        """
+        Return a dictionary of array API library capabilities.
+
+        The resulting dictionary has the following keys:
+
+        - **"boolean indexing"**: boolean indicating whether an array library
+          supports boolean indexing. Always ``True`` for NumPy.
+
+        - **"data-dependent shapes"**: boolean indicating whether an array
+          library supports data-dependent output shapes. Always ``True`` for
+          NumPy.
+
+        - **"max dimensions"**: integer indicating maximum number of supported
+          dimensions. Always ``64`` for NumPy.
+
+        See
+        https://data-apis.org/array-api/latest/API_specification/generated/array_api.info.capabilities.html
+        for more details.
+
+        See Also
+        --------
+        __array_namespace_info__.default_device,
+        __array_namespace_info__.default_dtypes,
+        __array_namespace_info__.dtypes,
+        __array_namespace_info__.devices
+
+        Returns
+        -------
+        capabilities : dict
+            A dictionary of array API library capabilities.
+
+        Examples
+        --------
+        >>> info = np.__array_namespace_info__()
+        >>> info.capabilities()
+        {'boolean indexing': True,
+         'data-dependent shapes': True,
+         'max dimensions': 64}
+
+        """
+        return {
+            "boolean indexing": True,
+            "data-dependent shapes": True,
+            "max dimensions": 64,
+        }
+
+    def default_device(self):
+        """
+        The default device used for new NumPy arrays.
+
+        For NumPy, this always returns ``'cpu'``.
+
+        See Also
+        --------
+        __array_namespace_info__.capabilities,
+        __array_namespace_info__.default_dtypes,
+        __array_namespace_info__.dtypes,
+        __array_namespace_info__.devices
+
+        Returns
+        -------
+        device : str
+            The default device used for new NumPy arrays.
+
+        Examples
+        --------
+        >>> info = np.__array_namespace_info__()
+        >>> info.default_device()
+        'cpu'
+
+        """
+        return "cpu"
+
+    def default_dtypes(self, *, device=None):
+        """
+        The default data types used for new NumPy arrays.
+
+        For NumPy, this always returns the following dictionary:
+
+        - **"real floating"**: ``numpy.float64``
+        - **"complex floating"**: ``numpy.complex128``
+        - **"integral"**: ``numpy.intp``
+        - **"indexing"**: ``numpy.intp``
+
+        Parameters
+        ----------
+        device : str, optional
+            The device to get the default data types for. For NumPy, only
+            ``'cpu'`` is allowed.
+
+        Returns
+        -------
+        dtypes : dict
+            A dictionary describing the default data types used for new NumPy
+            arrays.
+
+        See Also
+        --------
+        __array_namespace_info__.capabilities,
+        __array_namespace_info__.default_device,
+        __array_namespace_info__.dtypes,
+        __array_namespace_info__.devices
+
+        Examples
+        --------
+        >>> info = np.__array_namespace_info__()
+        >>> info.default_dtypes()
+        {'real floating': numpy.float64,
+         'complex floating': numpy.complex128,
+         'integral': numpy.int64,
+         'indexing': numpy.int64}
+
+        """
+        if device not in ["cpu", None]:
+            raise ValueError(
+                'Device not understood. Only "cpu" is allowed, but received:'
+                f' {device}'
+            )
+        return {
+            "real floating": dtype(float64),
+            "complex floating": dtype(complex128),
+            "integral": dtype(intp),
+            "indexing": dtype(intp),
+        }
+
+    def dtypes(self, *, device=None, kind=None):
+        """
+        The array API data types supported by NumPy.
+
+        Note that this function only returns data types that are defined by
+        the array API.
+
+        Parameters
+        ----------
+        device : str, optional
+            The device to get the data types for. For NumPy, only ``'cpu'`` is
+            allowed.
+        kind : str or tuple of str, optional
+            The kind of data types to return. If ``None``, all data types are
+            returned. If a string, only data types of that kind are returned.
+            If a tuple, a dictionary containing the union of the given kinds
+            is returned. The following kinds are supported:
+
+            - ``'bool'``: boolean data types (i.e., ``bool``).
+            - ``'signed integer'``: signed integer data types (i.e., ``int8``,
+              ``int16``, ``int32``, ``int64``).
+            - ``'unsigned integer'``: unsigned integer data types (i.e.,
+              ``uint8``, ``uint16``, ``uint32``, ``uint64``).
+            - ``'integral'``: integer data types. Shorthand for ``('signed
+              integer', 'unsigned integer')``.
+            - ``'real floating'``: real-valued floating-point data types
+              (i.e., ``float32``, ``float64``).
+            - ``'complex floating'``: complex floating-point data types (i.e.,
+              ``complex64``, ``complex128``).
+            - ``'numeric'``: numeric data types. Shorthand for ``('integral',
+              'real floating', 'complex floating')``.
+
+        Returns
+        -------
+        dtypes : dict
+            A dictionary mapping the names of data types to the corresponding
+            NumPy data types.
+
+        See Also
+        --------
+        __array_namespace_info__.capabilities,
+        __array_namespace_info__.default_device,
+        __array_namespace_info__.default_dtypes,
+        __array_namespace_info__.devices
+
+        Examples
+        --------
+        >>> info = np.__array_namespace_info__()
+        >>> info.dtypes(kind='signed integer')
+        {'int8': numpy.int8,
+         'int16': numpy.int16,
+         'int32': numpy.int32,
+         'int64': numpy.int64}
+
+        """
+        if device not in ["cpu", None]:
+            raise ValueError(
+                'Device not understood. Only "cpu" is allowed, but received:'
+                f' {device}'
+            )
+        if kind is None:
+            return {
+                "bool": dtype(bool),
+                "int8": dtype(int8),
+                "int16": dtype(int16),
+                "int32": dtype(int32),
+                "int64": dtype(int64),
+                "uint8": dtype(uint8),
+                "uint16": dtype(uint16),
+                "uint32": dtype(uint32),
+                "uint64": dtype(uint64),
+                "float32": dtype(float32),
+                "float64": dtype(float64),
+                "complex64": dtype(complex64),
+                "complex128": dtype(complex128),
+            }
+        if kind == "bool":
+            return {"bool": bool}
+        if kind == "signed integer":
+            return {
+                "int8": dtype(int8),
+                "int16": dtype(int16),
+                "int32": dtype(int32),
+                "int64": dtype(int64),
+            }
+        if kind == "unsigned integer":
+            return {
+                "uint8": dtype(uint8),
+                "uint16": dtype(uint16),
+                "uint32": dtype(uint32),
+                "uint64": dtype(uint64),
+            }
+        if kind == "integral":
+            return {
+                "int8": dtype(int8),
+                "int16": dtype(int16),
+                "int32": dtype(int32),
+                "int64": dtype(int64),
+                "uint8": dtype(uint8),
+                "uint16": dtype(uint16),
+                "uint32": dtype(uint32),
+                "uint64": dtype(uint64),
+            }
+        if kind == "real floating":
+            return {
+                "float32": dtype(float32),
+                "float64": dtype(float64),
+            }
+        if kind == "complex floating":
+            return {
+                "complex64": dtype(complex64),
+                "complex128": dtype(complex128),
+            }
+        if kind == "numeric":
+            return {
+                "int8": dtype(int8),
+                "int16": dtype(int16),
+                "int32": dtype(int32),
+                "int64": dtype(int64),
+                "uint8": dtype(uint8),
+                "uint16": dtype(uint16),
+                "uint32": dtype(uint32),
+                "uint64": dtype(uint64),
+                "float32": dtype(float32),
+                "float64": dtype(float64),
+                "complex64": dtype(complex64),
+                "complex128": dtype(complex128),
+            }
+        if isinstance(kind, tuple):
+            res = {}
+            for k in kind:
+                res.update(self.dtypes(kind=k))
+            return res
+        raise ValueError(f"unsupported kind: {kind!r}")
+
+    def devices(self):
+        """
+        The devices supported by NumPy.
+
+        For NumPy, this always returns ``('cpu',)``.
+
+        Returns
+        -------
+        devices : list of str
+            The devices supported by NumPy.
+
+        See Also
+        --------
+        __array_namespace_info__.capabilities,
+        __array_namespace_info__.default_device,
+        __array_namespace_info__.default_dtypes,
+        __array_namespace_info__.dtypes
+
+        Examples
+        --------
+        >>> info = np.__array_namespace_info__()
+        >>> info.devices()
+        ('cpu',)
+
+        """
+        return ("cpu",)

v12x/pylib/numpy/_configtool.py

@@ -0,0 +1,39 @@
+import argparse
+import sys
+from pathlib import Path
+
+from .lib._utils_impl import get_include
+from .version import __version__
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=__version__,
+        help="Print the version and exit.",
+    )
+    parser.add_argument(
+        "--cflags",
+        action="store_true",
+        help="Compile flag needed when using the NumPy headers.",
+    )
+    parser.add_argument(
+        "--pkgconfigdir",
+        action="store_true",
+        help=("Print the pkgconfig directory in which `numpy.pc` is stored "
+              "(useful for setting $PKG_CONFIG_PATH)."),
+    )
+    args = parser.parse_args()
+    if not sys.argv[1:]:
+        parser.print_help()
+    if args.cflags:
+        print("-I" + get_include())
+    if args.pkgconfigdir:
+        _path = Path(get_include()) / '..' / 'lib' / 'pkgconfig'
+        print(_path.resolve())
+
+
+if __name__ == "__main__":
+    main()

v12x/pylib/numpy/_core/__init__.py

@@ -0,0 +1,203 @@
+"""
+Contains the core of NumPy: ndarray, ufuncs, dtypes, etc.
+
+Please note that this module is private.  All functions and objects
+are available in the main ``numpy`` namespace - use that instead.
+
+"""
+
+import os
+
+from numpy.version import version as __version__
+
+# disables OpenBLAS affinity setting of the main thread that limits
+# python threads or processes to one core
+env_added = []
+for envkey in ['OPENBLAS_MAIN_FREE']:
+    if envkey not in os.environ:
+        # Note: using `putenv` (and `unsetenv` further down) instead of updating
+        # `os.environ` on purpose to avoid a race condition, see gh-30627.
+        os.putenv(envkey, '1')
+        env_added.append(envkey)
+
+try:
+    from . import multiarray
+except ImportError as exc:
+    import sys
+
+    # Bypass for the module re-initialization opt-out
+    if exc.msg == "cannot load module more than once per process":
+        raise
+
+    # Basically always, the problem should be that the C module is wrong/missing...
+    if (
+        isinstance(exc, ModuleNotFoundError)
+        and exc.name == "numpy._core._multiarray_umath"
+    ):
+        import sys
+        candidates = []
+        for path in __path__:
+            candidates.extend(
+                f for f in os.listdir(path) if f.startswith("_multiarray_umath"))
+        if len(candidates) == 0:
+            bad_c_module_info = (
+                "We found no compiled module, did NumPy build successfully?\n")
+        else:
+            candidate_str = '\n  * '.join(candidates)
+            # cache_tag is documented to be possibly None, so just use name if it is
+            # this guesses at cache_tag being the same as the extension module scheme
+            tag = sys.implementation.cache_tag or sys.implementation.name
+            bad_c_module_info = (
+                f"The following compiled module files exist, but seem incompatible\n"
+                f"with with either python '{tag}' or the "
+                f"platform '{sys.platform}':\n\n  * {candidate_str}\n"
+            )
+    else:
+        bad_c_module_info = ""
+
+    major, minor, *_ = sys.version_info
+    msg = f"""
+
+IMPORTANT: PLEASE READ THIS FOR ADVICE ON HOW TO SOLVE THIS ISSUE!
+
+Importing the numpy C-extensions failed. This error can happen for
+many reasons, often due to issues with your setup or how NumPy was
+installed.
+{bad_c_module_info}
+We have compiled some common reasons and troubleshooting tips at:
+
+    https://numpy.org/devdocs/user/troubleshooting-importerror.html
+
+Please note and check the following:
+
+  * The Python version is: Python {major}.{minor} from "{sys.executable}"
+  * The NumPy version is: "{__version__}"
+
+and make sure that they are the versions you expect.
+
+Please carefully study the information and documentation linked above.
+This is unlikely to be a NumPy issue but will be caused by a bad install
+or environment on your machine.
+
+Original error was: {exc}
+"""
+
+    raise ImportError(msg) from exc
+finally:
+    for envkey in env_added:
+        os.unsetenv(envkey)
+del envkey
+del env_added
+del os
+
+from . import umath
+
+# Check that multiarray,umath are pure python modules wrapping
+# _multiarray_umath and not either of the old c-extension modules
+if not (hasattr(multiarray, '_multiarray_umath') and
+        hasattr(umath, '_multiarray_umath')):
+    import sys
+    path = sys.modules['numpy'].__path__
+    msg = ("Something is wrong with the numpy installation. "
+        "While importing we detected an older version of "
+        "numpy in {}. One method of fixing this is to repeatedly uninstall "
+        "numpy until none is found, then reinstall this version.")
+    raise ImportError(msg.format(path))
+
+from . import numerictypes as nt
+from .numerictypes import sctypeDict, sctypes
+
+multiarray.set_typeDict(nt.sctypeDict)
+from . import einsumfunc, fromnumeric, function_base, getlimits, numeric, shape_base
+from .einsumfunc import *
+from .fromnumeric import *
+from .function_base import *
+from .getlimits import *
+
+# Note: module name memmap is overwritten by a class with same name
+from .memmap import *
+from .numeric import *
+from .records import recarray, record
+from .shape_base import *
+
+del nt
+
+# do this after everything else, to minimize the chance of this misleadingly
+# appearing in an import-time traceback
+# add these for module-freeze analysis (like PyInstaller)
+from . import (
+    _add_newdocs,
+    _add_newdocs_scalars,
+    _dtype,
+    _dtype_ctypes,
+    _internal,
+    _methods,
+)
+from .numeric import absolute as abs
+
+acos = numeric.arccos
+acosh = numeric.arccosh
+asin = numeric.arcsin
+asinh = numeric.arcsinh
+atan = numeric.arctan
+atanh = numeric.arctanh
+atan2 = numeric.arctan2
+concat = numeric.concatenate
+bitwise_left_shift = numeric.left_shift
+bitwise_invert = numeric.invert
+bitwise_right_shift = numeric.right_shift
+permute_dims = numeric.transpose
+pow = numeric.power
+
+__all__ = [
+    "abs", "acos", "acosh", "asin", "asinh", "atan", "atanh", "atan2",
+    "bitwise_invert", "bitwise_left_shift", "bitwise_right_shift", "concat",
+    "pow", "permute_dims", "memmap", "sctypeDict", "record", "recarray"
+]
+__all__ += numeric.__all__
+__all__ += function_base.__all__
+__all__ += getlimits.__all__
+__all__ += shape_base.__all__
+__all__ += einsumfunc.__all__
+
+
+def _ufunc_reduce(func):
+    # Report the `__name__`. pickle will try to find the module. Note that
+    # pickle supports for this `__name__` to be a `__qualname__`. It may
+    # make sense to add a `__qualname__` to ufuncs, to allow this more
+    # explicitly (Numba has ufuncs as attributes).
+    # See also: https://github.com/dask/distributed/issues/3450
+    return func.__name__
+
+
+def _DType_reconstruct(scalar_type):
+    # This is a work-around to pickle type(np.dtype(np.float64)), etc.
+    # and it should eventually be replaced with a better solution, e.g. when
+    # DTypes become HeapTypes.
+    return type(dtype(scalar_type))
+
+
+def _DType_reduce(DType):
+    # As types/classes, most DTypes can simply be pickled by their name:
+    if not DType._legacy or DType.__module__ == "numpy.dtypes":
+        return DType.__name__
+
+    # However, user defined legacy dtypes (like rational) do not end up in
+    # `numpy.dtypes` as module and do not have a public class at all.
+    # For these, we pickle them by reconstructing them from the scalar type:
+    scalar_type = DType.type
+    return _DType_reconstruct, (scalar_type,)
+
+
+import copyreg
+
+copyreg.pickle(ufunc, _ufunc_reduce)
+copyreg.pickle(type(dtype), _DType_reduce, _DType_reconstruct)
+
+# Unclutter namespace (must keep _*_reconstruct for unpickling)
+del copyreg, _ufunc_reduce, _DType_reduce
+
+from numpy._pytesttester import PytestTester
+
+test = PytestTester(__name__)
+del PytestTester

v12x/pylib/numpy/_core/_add_newdocs_scalars.py

@@ -0,0 +1,381 @@
+"""
+This file is separate from ``_add_newdocs.py`` so that it can be mocked out by
+our sphinx ``conf.py`` during doc builds, where we want to avoid showing
+platform-dependent information.
+"""
+import os
+import sys
+
+from numpy._core import dtype, numerictypes as _numerictypes
+from numpy._core.function_base import add_newdoc
+
+##############################################################################
+#
+# Documentation for concrete scalar classes
+#
+##############################################################################
+
+def numeric_type_aliases(aliases):
+    def type_aliases_gen():
+        for alias, doc in aliases:
+            try:
+                alias_type = getattr(_numerictypes, alias)
+            except AttributeError:
+                # The set of aliases that actually exist varies between platforms
+                pass
+            else:
+                yield (alias_type, alias, doc)
+    return list(type_aliases_gen())
+
+
+possible_aliases = numeric_type_aliases([
+    ('int8', '8-bit signed integer (``-128`` to ``127``)'),
+    ('int16', '16-bit signed integer (``-32_768`` to ``32_767``)'),
+    ('int32', '32-bit signed integer (``-2_147_483_648`` to ``2_147_483_647``)'),
+    ('int64', '64-bit signed integer (``-9_223_372_036_854_775_808`` to ``9_223_372_036_854_775_807``)'),
+    ('intp', 'Signed integer large enough to fit pointer, compatible with C ``intptr_t``'),
+    ('uint8', '8-bit unsigned integer (``0`` to ``255``)'),
+    ('uint16', '16-bit unsigned integer (``0`` to ``65_535``)'),
+    ('uint32', '32-bit unsigned integer (``0`` to ``4_294_967_295``)'),
+    ('uint64', '64-bit unsigned integer (``0`` to ``18_446_744_073_709_551_615``)'),
+    ('uintp', 'Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``'),
+    ('float16', '16-bit-precision floating-point number type: sign bit, 5 bits exponent, 10 bits mantissa'),
+    ('float32', '32-bit-precision floating-point number type: sign bit, 8 bits exponent, 23 bits mantissa'),
+    ('float64', '64-bit precision floating-point number type: sign bit, 11 bits exponent, 52 bits mantissa'),
+    ('float96', '96-bit extended-precision floating-point number type'),
+    ('float128', '128-bit extended-precision floating-point number type'),
+    ('complex64', 'Complex number type composed of 2 32-bit-precision floating-point numbers'),
+    ('complex128', 'Complex number type composed of 2 64-bit-precision floating-point numbers'),
+    ('complex192', 'Complex number type composed of 2 96-bit extended-precision floating-point numbers'),
+    ('complex256', 'Complex number type composed of 2 128-bit extended-precision floating-point numbers'),
+])
+
+
+def _get_platform_and_machine():
+    try:
+        system, _, _, _, machine = os.uname()
+    except AttributeError:
+        system = sys.platform
+        if system == 'win32':
+            machine = os.environ.get('PROCESSOR_ARCHITEW6432', '') \
+                    or os.environ.get('PROCESSOR_ARCHITECTURE', '')
+        else:
+            machine = 'unknown'
+    return system, machine
+
+
+_system, _machine = _get_platform_and_machine()
+_doc_alias_string = f":Alias on this platform ({_system} {_machine}):"
+
+# docstring prefix that cpython uses to populate `__text_signature__`
+_ARGUMENT_CLINIC_TEMPLATE = """{name}{signature}
+--
+
+{docstring}"""
+
+def add_newdoc_for_scalar_type(name: str, text_signature: str, doc: str) -> None:
+    # note: `:field: value` is rST syntax which renders as field lists.
+    cls = getattr(_numerictypes, name)
+    module = cls.__module__
+
+    lines_extra = [
+        "",  # blank line after main doc
+        f":Character code: ``{dtype(cls).char!r}``",
+    ]
+
+    if name != cls.__name__:
+        lines_extra.append(f":Canonical name: `{module}.{name}`")
+
+    lines_extra.extend(
+        f"{_doc_alias_string} `{module}.{alias}`: {doc}."
+        for alias_type, alias, doc in possible_aliases
+        if alias_type is cls
+    )
+
+    docstring = _ARGUMENT_CLINIC_TEMPLATE.format(
+        name=cls.__name__,  # must match the class name
+        signature=text_signature,
+        docstring="\n".join([doc.strip(), *lines_extra]),
+    )
+    add_newdoc('numpy._core.numerictypes', name, docstring)
+
+
+for bool_name in ('bool', 'bool_'):
+    add_newdoc_for_scalar_type(bool_name, '(value=False, /)', """
+Boolean type (True or False), stored as a byte.
+
+.. warning::
+
+    The :class:`bool` type is not a subclass of the :class:`int_` type
+    (the :class:`bool` is not even a number type). This is different
+    than Python's default implementation of :class:`bool` as a
+    sub-class of :class:`int`.
+""")
+
+add_newdoc_for_scalar_type('byte', '(value=0, /)', """
+Signed integer type, compatible with C ``char``.
+""")
+
+add_newdoc_for_scalar_type('short', '(value=0, /)', """
+Signed integer type, compatible with C ``short``.
+""")
+
+add_newdoc_for_scalar_type('intc', '(value=0, /)', """
+Signed integer type, compatible with C ``int``.
+""")
+
+add_newdoc_for_scalar_type('long', '(value=0, /)', """
+Signed integer type, compatible with C ``long``.
+""")
+
+# TODO: These docs probably need an if to highlight the default rather than
+#       the C-types (and be correct).
+add_newdoc_for_scalar_type('int_', '(value=0, /)', """
+Default signed integer type, 64bit on 64bit systems and 32bit on 32bit systems.
+""")
+
+add_newdoc_for_scalar_type('longlong', '(value=0, /)', """
+Signed integer type, compatible with C ``long long``.
+""")
+
+add_newdoc_for_scalar_type('ubyte', '(value=0, /)', """
+Unsigned integer type, compatible with C ``unsigned char``.
+""")
+
+add_newdoc_for_scalar_type('ushort', '(value=0, /)', """
+Unsigned integer type, compatible with C ``unsigned short``.
+""")
+
+add_newdoc_for_scalar_type('uintc', '(value=0, /)', """
+Unsigned integer type, compatible with C ``unsigned int``.
+""")
+
+add_newdoc_for_scalar_type('uint', '(value=0, /)', """
+Unsigned signed integer type, 64bit on 64bit systems and 32bit on 32bit systems.
+""")
+
+add_newdoc_for_scalar_type('ulong', '(value=0, /)', """
+Unsigned integer type, compatible with C ``unsigned long``.
+""")
+
+add_newdoc_for_scalar_type('ulonglong', '(value=0, /)', """
+Unsigned integer type, compatible with C ``unsigned long long``.
+""")
+
+add_newdoc_for_scalar_type('half', '(value=0, /)', """
+Half-precision floating-point number type.
+""")
+
+add_newdoc_for_scalar_type('single', '(value=0, /)', """
+Single-precision floating-point number type, compatible with C ``float``.
+""")
+
+add_newdoc_for_scalar_type('double', '(value=0, /)', """
+Double-precision floating-point number type, compatible with Python :class:`float` and C ``double``.
+""")
+
+add_newdoc_for_scalar_type('longdouble', '(value=0, /)', """
+Extended-precision floating-point number type, compatible with C ``long double``
+but not necessarily with IEEE 754 quadruple-precision.
+""")
+
+add_newdoc_for_scalar_type('csingle', '(real=0, imag=0, /)', """
+Complex number type composed of two single-precision floating-point numbers.
+""")
+
+add_newdoc_for_scalar_type('cdouble', '(real=0, imag=0, /)', """
+Complex number type composed of two double-precision floating-point numbers,
+compatible with Python :class:`complex`.
+""")
+
+add_newdoc_for_scalar_type('clongdouble', '(real=0, imag=0, /)', """
+Complex number type composed of two extended-precision floating-point numbers.
+""")
+
+add_newdoc_for_scalar_type('object_', '(value=None, /)', """
+Any Python object.
+""")
+
+add_newdoc_for_scalar_type('str_', '(value="", /, *args, **kwargs)', r"""
+A unicode string.
+
+This type strips trailing null codepoints.
+
+>>> s = np.str_("abc\x00")
+>>> s
+'abc'
+
+Unlike the builtin :class:`str`, this supports the
+:ref:`python:bufferobjects`, exposing its contents as UCS4:
+
+>>> m = memoryview(np.str_("abc"))
+>>> m.format
+'3w'
+>>> m.tobytes()
+b'a\x00\x00\x00b\x00\x00\x00c\x00\x00\x00'
+""")
+
+add_newdoc_for_scalar_type('bytes_', '(value="", /, *args, **kwargs)', r"""
+A byte string.
+
+When used in arrays, this type strips trailing null bytes.
+""")
+
+add_newdoc_for_scalar_type('void', '(length_or_data, /, dtype=None)', r"""
+np.void(length_or_data, /, dtype=None)
+
+Create a new structured or unstructured void scalar.
+
+Parameters
+----------
+length_or_data : int, array-like, bytes-like, object
+    One of multiple meanings (see notes).  The length or
+    bytes data of an unstructured void.  Or alternatively,
+    the data to be stored in the new scalar when `dtype`
+    is provided.
+    This can be an array-like, in which case an array may
+    be returned.
+dtype : dtype, optional
+    If provided the dtype of the new scalar.  This dtype must
+    be "void" dtype (i.e. a structured or unstructured void,
+    see also :ref:`defining-structured-types`).
+
+    .. versionadded:: 1.24
+
+Notes
+-----
+For historical reasons and because void scalars can represent both
+arbitrary byte data and structured dtypes, the void constructor
+has three calling conventions:
+
+1. ``np.void(5)`` creates a ``dtype="V5"`` scalar filled with five
+    ``\0`` bytes.  The 5 can be a Python or NumPy integer.
+2. ``np.void(b"bytes-like")`` creates a void scalar from the byte string.
+    The dtype itemsize will match the byte string length, here ``"V10"``.
+3. When a ``dtype=`` is passed the call is roughly the same as an
+    array creation.  However, a void scalar rather than array is returned.
+
+Please see the examples which show all three different conventions.
+
+Examples
+--------
+>>> np.void(5)
+np.void(b'\x00\x00\x00\x00\x00')
+>>> np.void(b'abcd')
+np.void(b'\x61\x62\x63\x64')
+>>> np.void((3.2, b'eggs'), dtype="d,S5")
+np.void((3.2, b'eggs'), dtype=[('f0', '<f8'), ('f1', 'S5')])
+>>> np.void(3, dtype=[('x', np.int8), ('y', np.int8)])
+np.void((3, 3), dtype=[('x', 'i1'), ('y', 'i1')])
+""")
+
+add_newdoc_for_scalar_type('datetime64', '(value=None, /, *args)', """
+If created from a 64-bit integer, it represents an offset from ``1970-01-01T00:00:00``.
+If created from string, the string can be in ISO 8601 date or datetime format.
+
+When parsing a string to create a datetime object, if the string contains
+a trailing timezone (A 'Z' or a timezone offset), the timezone will be
+dropped and a User Warning is given.
+
+Datetime64 objects should be considered to be UTC and therefore have an
+offset of +0000.
+
+>>> np.datetime64(10, 'Y')
+np.datetime64('1980')
+>>> np.datetime64('1980', 'Y')
+np.datetime64('1980')
+>>> np.datetime64(10, 'D')
+np.datetime64('1970-01-11')
+
+See :ref:`arrays.datetime` for more information.
+""")
+
+add_newdoc_for_scalar_type('timedelta64', '(value=0, /, *args)', """
+A timedelta stored as a 64-bit integer.
+
+See :ref:`arrays.datetime` for more information.
+""")
+
+add_newdoc('numpy._core.numerictypes', "integer", ('is_integer',
+    """
+    is_integer($self, /)
+    --
+
+    integer.is_integer() -> bool
+
+    Return ``True`` if the number is finite with integral value.
+
+    .. versionadded:: 1.22
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.int64(-2).is_integer()
+    True
+    >>> np.uint32(5).is_integer()
+    True
+    """))
+
+# TODO: work out how to put this on the base class, np.floating
+for float_name in ('half', 'single', 'double', 'longdouble'):
+    add_newdoc('numpy._core.numerictypes', float_name, ('as_integer_ratio',
+        f"""
+        as_integer_ratio($self, /)
+        --
+
+        {float_name}.as_integer_ratio() -> (int, int)
+
+        Return a pair of integers, whose ratio is exactly equal to the original
+        floating point number, and with a positive denominator.
+        Raise `OverflowError` on infinities and a `ValueError` on NaNs.
+
+        >>> np.{float_name}(10.0).as_integer_ratio()
+        (10, 1)
+        >>> np.{float_name}(0.0).as_integer_ratio()
+        (0, 1)
+        >>> np.{float_name}(-.25).as_integer_ratio()
+        (-1, 4)
+        """))
+
+    add_newdoc('numpy._core.numerictypes', float_name, ('is_integer',
+        f"""
+        is_integer($self, /)
+        --
+
+        {float_name}.is_integer() -> bool
+
+        Return ``True`` if the floating point number is finite with integral
+        value, and ``False`` otherwise.
+
+        .. versionadded:: 1.22
+
+        Examples
+        --------
+        >>> np.{float_name}(-2.0).is_integer()
+        True
+        >>> np.{float_name}(3.2).is_integer()
+        False
+        """))
+
+for int_name in ('int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32',
+                 'int64', 'uint64', 'int64', 'uint64', 'int64', 'uint64',
+                 'longlong', 'ulonglong'):
+    # Add negative examples for signed cases by checking typecode
+    add_newdoc('numpy._core.numerictypes', int_name, ('bit_count',
+        f"""
+        bit_count($self, /)
+        --
+
+        {int_name}.bit_count() -> int
+
+        Computes the number of 1-bits in the absolute value of the input.
+        Analogous to the builtin `int.bit_count` or ``popcount`` in C++.
+
+        Examples
+        --------
+        >>> np.{int_name}(127).bit_count()
+        7""" +
+        (f"""
+        >>> np.{int_name}(-127).bit_count()
+        7
+        """ if dtype(int_name).char.islower() else "")))

v12x/pylib/numpy/_core/_asarray.py

@@ -0,0 +1,130 @@
+"""
+Functions in the ``as*array`` family that promote array-likes into arrays.
+
+`require` fits this category despite its name not matching this pattern.
+"""
+from .multiarray import array, asanyarray
+from .overrides import array_function_dispatch, finalize_array_function_like, set_module
+
+__all__ = ["require"]
+
+
+POSSIBLE_FLAGS = {
+    'C': 'C', 'C_CONTIGUOUS': 'C', 'CONTIGUOUS': 'C',
+    'F': 'F', 'F_CONTIGUOUS': 'F', 'FORTRAN': 'F',
+    'A': 'A', 'ALIGNED': 'A',
+    'W': 'W', 'WRITEABLE': 'W',
+    'O': 'O', 'OWNDATA': 'O',
+    'E': 'E', 'ENSUREARRAY': 'E'
+}
+
+
+@finalize_array_function_like
+@set_module('numpy')
+def require(a, dtype=None, requirements=None, *, like=None):
+    """
+    Return an ndarray of the provided type that satisfies requirements.
+
+    This function is useful to be sure that an array with the correct flags
+    is returned for passing to compiled code (perhaps through ctypes).
+
+    Parameters
+    ----------
+    a : array_like
+       The object to be converted to a type-and-requirement-satisfying array.
+    dtype : data-type
+       The required data-type. If None preserve the current dtype. If your
+       application requires the data to be in native byteorder, include
+       a byteorder specification as a part of the dtype specification.
+    requirements : str or sequence of str
+       The requirements list can be any of the following
+
+       * 'F_CONTIGUOUS' ('F') - ensure a Fortran-contiguous array
+       * 'C_CONTIGUOUS' ('C') - ensure a C-contiguous array
+       * 'ALIGNED' ('A')      - ensure a data-type aligned array
+       * 'WRITEABLE' ('W')    - ensure a writable array
+       * 'OWNDATA' ('O')      - ensure an array that owns its own data
+       * 'ENSUREARRAY', ('E') - ensure a base array, instead of a subclass
+    ${ARRAY_FUNCTION_LIKE}
+
+        .. versionadded:: 1.20.0
+
+    Returns
+    -------
+    out : ndarray
+        Array with specified requirements and type if given.
+
+    See Also
+    --------
+    asarray : Convert input to an ndarray.
+    asanyarray : Convert to an ndarray, but pass through ndarray subclasses.
+    ascontiguousarray : Convert input to a contiguous array.
+    asfortranarray : Convert input to an ndarray with column-major
+                     memory order.
+    ndarray.flags : Information about the memory layout of the array.
+
+    Notes
+    -----
+    The returned array will be guaranteed to have the listed requirements
+    by making a copy if needed.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.arange(6).reshape(2,3)
+    >>> x.flags
+      C_CONTIGUOUS : True
+      F_CONTIGUOUS : False
+      OWNDATA : False
+      WRITEABLE : True
+      ALIGNED : True
+      WRITEBACKIFCOPY : False
+
+    >>> y = np.require(x, dtype=np.float32, requirements=['A', 'O', 'W', 'F'])
+    >>> y.flags
+      C_CONTIGUOUS : False
+      F_CONTIGUOUS : True
+      OWNDATA : True
+      WRITEABLE : True
+      ALIGNED : True
+      WRITEBACKIFCOPY : False
+
+    """
+    if like is not None:
+        return _require_with_like(
+            like,
+            a,
+            dtype=dtype,
+            requirements=requirements,
+        )
+
+    if not requirements:
+        return asanyarray(a, dtype=dtype)
+
+    requirements = {POSSIBLE_FLAGS[x.upper()] for x in requirements}
+
+    if 'E' in requirements:
+        requirements.remove('E')
+        subok = False
+    else:
+        subok = True
+
+    order = 'A'
+    if requirements >= {'C', 'F'}:
+        raise ValueError('Cannot specify both "C" and "F" order')
+    elif 'F' in requirements:
+        order = 'F'
+        requirements.remove('F')
+    elif 'C' in requirements:
+        order = 'C'
+        requirements.remove('C')
+
+    arr = array(a, dtype=dtype, order=order, copy=None, subok=subok)
+
+    for prop in requirements:
+        if not arr.flags[prop]:
+            return arr.copy(order)
+    return arr
+
+
+_require_with_like = array_function_dispatch()(require)

v12x/pylib/numpy/_core/_dtype.py

@@ -0,0 +1,366 @@
+"""
+A place for code to be called from the implementation of np.dtype
+
+String handling is much easier to do correctly in python.
+"""
+import numpy as np
+
+_kind_to_stem = {
+    'u': 'uint',
+    'i': 'int',
+    'c': 'complex',
+    'f': 'float',
+    'b': 'bool',
+    'V': 'void',
+    'O': 'object',
+    'M': 'datetime',
+    'm': 'timedelta',
+    'S': 'bytes',
+    'U': 'str',
+}
+
+
+def _kind_name(dtype):
+    try:
+        return _kind_to_stem[dtype.kind]
+    except KeyError as e:
+        raise RuntimeError(
+            f"internal dtype error, unknown kind {dtype.kind!r}"
+        ) from None
+
+
+def __str__(dtype):
+    if dtype.fields is not None:
+        return _struct_str(dtype, include_align=True)
+    elif dtype.subdtype:
+        return _subarray_str(dtype)
+    elif issubclass(dtype.type, np.flexible) or not dtype.isnative:
+        return dtype.str
+    else:
+        return dtype.name
+
+
+def __repr__(dtype):
+    arg_str = _construction_repr(dtype, include_align=False)
+    if dtype.isalignedstruct:
+        arg_str = arg_str + ", align=True"
+    return f"dtype({arg_str})"
+
+
+def _unpack_field(dtype, offset, title=None):
+    """
+    Helper function to normalize the items in dtype.fields.
+
+    Call as:
+
+    dtype, offset, title = _unpack_field(*dtype.fields[name])
+    """
+    return dtype, offset, title
+
+
+def _isunsized(dtype):
+    # PyDataType_ISUNSIZED
+    return dtype.itemsize == 0
+
+
+def _construction_repr(dtype, include_align=False, short=False):
+    """
+    Creates a string repr of the dtype, excluding the 'dtype()' part
+    surrounding the object. This object may be a string, a list, or
+    a dict depending on the nature of the dtype. This
+    is the object passed as the first parameter to the dtype
+    constructor, and if no additional constructor parameters are
+    given, will reproduce the exact memory layout.
+
+    Parameters
+    ----------
+    short : bool
+        If true, this creates a shorter repr using 'kind' and 'itemsize',
+        instead of the longer type name.
+
+    include_align : bool
+        If true, this includes the 'align=True' parameter
+        inside the struct dtype construction dict when needed. Use this flag
+        if you want a proper repr string without the 'dtype()' part around it.
+
+        If false, this does not preserve the
+        'align=True' parameter or sticky NPY_ALIGNED_STRUCT flag for
+        struct arrays like the regular repr does, because the 'align'
+        flag is not part of first dtype constructor parameter. This
+        mode is intended for a full 'repr', where the 'align=True' is
+        provided as the second parameter.
+    """
+    if dtype.fields is not None:
+        return _struct_str(dtype, include_align=include_align)
+    elif dtype.subdtype:
+        return _subarray_str(dtype)
+    else:
+        return _scalar_str(dtype, short=short)
+
+
+def _scalar_str(dtype, short):
+    byteorder = _byte_order_str(dtype)
+
+    if dtype.type == np.bool:
+        if short:
+            return "'?'"
+        else:
+            return "'bool'"
+
+    elif dtype.type == np.object_:
+        # The object reference may be different sizes on different
+        # platforms, so it should never include the itemsize here.
+        return "'O'"
+
+    elif dtype.type == np.bytes_:
+        if _isunsized(dtype):
+            return "'S'"
+        else:
+            return f"'S{dtype.itemsize}'"
+
+    elif dtype.type == np.str_:
+        if _isunsized(dtype):
+            return f"'{byteorder}U'"
+        else:
+            return f"'{byteorder}U{dtype.itemsize // 4}'"
+
+    elif dtype.type is str:
+        return "'T'"
+
+    elif not type(dtype)._legacy:
+        return f"'{byteorder}{type(dtype).__name__}{dtype.itemsize * 8}'"
+
+    # unlike the other types, subclasses of void are preserved - but
+    # historically the repr does not actually reveal the subclass
+    elif issubclass(dtype.type, np.void):
+        if _isunsized(dtype):
+            return "'V'"
+        else:
+            return f"'V{dtype.itemsize}'"
+
+    elif dtype.type == np.datetime64:
+        return f"'{byteorder}M8{_datetime_metadata_str(dtype)}'"
+
+    elif dtype.type == np.timedelta64:
+        return f"'{byteorder}m8{_datetime_metadata_str(dtype)}'"
+
+    elif dtype.isbuiltin == 2:
+        return dtype.type.__name__
+
+    elif np.issubdtype(dtype, np.number):
+        # Short repr with endianness, like '<f8'
+        if short or dtype.byteorder not in ('=', '|'):
+            return f"'{byteorder}{dtype.kind}{dtype.itemsize}'"
+
+        # Longer repr, like 'float64'
+        else:
+            return f"'{_kind_name(dtype)}{8 * dtype.itemsize}'"
+
+    else:
+        raise RuntimeError(
+            "Internal error: NumPy dtype unrecognized type number")
+
+
+def _byte_order_str(dtype):
+    """ Normalize byteorder to '<' or '>' """
+    # hack to obtain the native and swapped byte order characters
+    swapped = np.dtype(int).newbyteorder('S')
+    native = swapped.newbyteorder('S')
+
+    byteorder = dtype.byteorder
+    if byteorder == '=':
+        return native.byteorder
+    if byteorder == 'S':
+        # TODO: this path can never be reached
+        return swapped.byteorder
+    elif byteorder == '|':
+        return ''
+    else:
+        return byteorder
+
+
+def _datetime_metadata_str(dtype):
+    # TODO: this duplicates the C metastr_to_unicode functionality
+    unit, count = np.datetime_data(dtype)
+    if unit == 'generic':
+        return ''
+    elif count == 1:
+        return f'[{unit}]'
+    else:
+        return f'[{count}{unit}]'
+
+
+def _struct_dict_str(dtype, includealignedflag):
+    # unpack the fields dictionary into ls
+    names = dtype.names
+    fld_dtypes = []
+    offsets = []
+    titles = []
+    for name in names:
+        fld_dtype, offset, title = _unpack_field(*dtype.fields[name])
+        fld_dtypes.append(fld_dtype)
+        offsets.append(offset)
+        titles.append(title)
+
+    # Build up a string to make the dictionary
+
+    if np._core.arrayprint._get_legacy_print_mode() <= 121:
+        colon = ":"
+        fieldsep = ","
+    else:
+        colon = ": "
+        fieldsep = ", "
+
+    # First, the names
+    ret = f"{{'names'{colon}["
+    ret += fieldsep.join(repr(name) for name in names)
+
+    # Second, the formats
+    ret += f"], 'formats'{colon}["
+    ret += fieldsep.join(
+        _construction_repr(fld_dtype, short=True) for fld_dtype in fld_dtypes)
+
+    # Third, the offsets
+    ret += f"], 'offsets'{colon}["
+    ret += fieldsep.join(f"{offset}" for offset in offsets)
+
+    # Fourth, the titles
+    if any(title is not None for title in titles):
+        ret += f"], 'titles'{colon}["
+        ret += fieldsep.join(repr(title) for title in titles)
+
+    # Fifth, the itemsize
+    ret += f"], 'itemsize'{colon}{dtype.itemsize}"
+
+    if (includealignedflag and dtype.isalignedstruct):
+        # Finally, the aligned flag
+        ret += f", 'aligned'{colon}True}}"
+    else:
+        ret += "}"
+
+    return ret
+
+
+def _aligned_offset(offset, alignment):
+    # round up offset:
+    return - (-offset // alignment) * alignment
+
+
+def _is_packed(dtype):
+    """
+    Checks whether the structured data type in 'dtype'
+    has a simple layout, where all the fields are in order,
+    and follow each other with no alignment padding.
+
+    When this returns true, the dtype can be reconstructed
+    from a list of the field names and dtypes with no additional
+    dtype parameters.
+
+    Duplicates the C `is_dtype_struct_simple_unaligned_layout` function.
+    """
+    align = dtype.isalignedstruct
+    max_alignment = 1
+    total_offset = 0
+    for name in dtype.names:
+        fld_dtype, fld_offset, title = _unpack_field(*dtype.fields[name])
+
+        if align:
+            total_offset = _aligned_offset(total_offset, fld_dtype.alignment)
+            max_alignment = max(max_alignment, fld_dtype.alignment)
+
+        if fld_offset != total_offset:
+            return False
+        total_offset += fld_dtype.itemsize
+
+    if align:
+        total_offset = _aligned_offset(total_offset, max_alignment)
+
+    return total_offset == dtype.itemsize
+
+
+def _struct_list_str(dtype):
+    items = []
+    for name in dtype.names:
+        fld_dtype, fld_offset, title = _unpack_field(*dtype.fields[name])
+
+        item = "("
+        if title is not None:
+            item += f"({title!r}, {name!r}), "
+        else:
+            item += f"{name!r}, "
+        # Special case subarray handling here
+        if fld_dtype.subdtype is not None:
+            base, shape = fld_dtype.subdtype
+            item += f"{_construction_repr(base, short=True)}, {shape}"
+        else:
+            item += _construction_repr(fld_dtype, short=True)
+
+        item += ")"
+        items.append(item)
+
+    return "[" + ", ".join(items) + "]"
+
+
+def _struct_str(dtype, include_align):
+    # The list str representation can't include the 'align=' flag,
+    # so if it is requested and the struct has the aligned flag set,
+    # we must use the dict str instead.
+    if not (include_align and dtype.isalignedstruct) and _is_packed(dtype):
+        sub = _struct_list_str(dtype)
+
+    else:
+        sub = _struct_dict_str(dtype, include_align)
+
+    # If the data type isn't the default, void, show it
+    if dtype.type != np.void:
+        return f"({dtype.type.__module__}.{dtype.type.__name__}, {sub})"
+    else:
+        return sub
+
+
+def _subarray_str(dtype):
+    base, shape = dtype.subdtype
+    return f"({_construction_repr(base, short=True)}, {shape})"
+
+
+def _name_includes_bit_suffix(dtype):
+    if dtype.type == np.object_:
+        # pointer size varies by system, best to omit it
+        return False
+    elif dtype.type == np.bool:
+        # implied
+        return False
+    elif dtype.type is None:
+        return True
+    elif np.issubdtype(dtype, np.flexible) and _isunsized(dtype):
+        # unspecified
+        return False
+    else:
+        return True
+
+
+def _name_get(dtype):
+    # provides dtype.name.__get__, documented as returning a "bit name"
+
+    if dtype.isbuiltin == 2:
+        # user dtypes don't promise to do anything special
+        return dtype.type.__name__
+
+    if not type(dtype)._legacy:
+        name = type(dtype).__name__
+
+    elif issubclass(dtype.type, np.void):
+        # historically, void subclasses preserve their name, eg `record64`
+        name = dtype.type.__name__
+    else:
+        name = _kind_name(dtype)
+
+    # append bit counts
+    if _name_includes_bit_suffix(dtype):
+        name += f"{dtype.itemsize * 8}"
+
+    # append metadata to datetimes
+    if dtype.type in (np.datetime64, np.timedelta64):
+        name += _datetime_metadata_str(dtype)
+
+    return name

v12x/pylib/numpy/_core/_dtype_ctypes.py

@@ -0,0 +1,120 @@
+"""
+Conversion from ctypes to dtype.
+
+In an ideal world, we could achieve this through the PEP3118 buffer protocol,
+something like::
+
+    def dtype_from_ctypes_type(t):
+        # needed to ensure that the shape of `t` is within memoryview.format
+        class DummyStruct(ctypes.Structure):
+            _fields_ = [('a', t)]
+
+        # empty to avoid memory allocation
+        ctype_0 = (DummyStruct * 0)()
+        mv = memoryview(ctype_0)
+
+        # convert the struct, and slice back out the field
+        return _dtype_from_pep3118(mv.format)['a']
+
+Unfortunately, this fails because:
+
+* ctypes cannot handle length-0 arrays with PEP3118 (bpo-32782)
+* PEP3118 cannot represent unions, but both numpy and ctypes can
+* ctypes cannot handle big-endian structs with PEP3118 (bpo-32780)
+"""
+
+# We delay-import ctypes for distributions that do not include it.
+# While this module is not used unless the user passes in ctypes
+# members, it is eagerly imported from numpy/_core/__init__.py.
+import numpy as np
+
+
+def _from_ctypes_array(t):
+    return np.dtype((dtype_from_ctypes_type(t._type_), (t._length_,)))
+
+
+def _from_ctypes_structure(t):
+    for item in t._fields_:
+        if len(item) > 2:
+            raise TypeError(
+                "ctypes bitfields have no dtype equivalent")
+
+    if hasattr(t, "_pack_"):
+        import ctypes
+        formats = []
+        offsets = []
+        names = []
+        current_offset = 0
+        for fname, ftyp in t._fields_:
+            names.append(fname)
+            formats.append(dtype_from_ctypes_type(ftyp))
+            # Each type has a default offset, this is platform dependent
+            # for some types.
+            effective_pack = min(t._pack_, ctypes.alignment(ftyp))
+            current_offset = (
+                (current_offset + effective_pack - 1) // effective_pack
+            ) * effective_pack
+            offsets.append(current_offset)
+            current_offset += ctypes.sizeof(ftyp)
+
+        return np.dtype({
+            "formats": formats,
+            "offsets": offsets,
+            "names": names,
+            "itemsize": ctypes.sizeof(t)})
+    else:
+        fields = []
+        for fname, ftyp in t._fields_:
+            fields.append((fname, dtype_from_ctypes_type(ftyp)))
+
+        # by default, ctypes structs are aligned
+        return np.dtype(fields, align=True)
+
+
+def _from_ctypes_scalar(t):
+    """
+    Return the dtype type with endianness included if it's the case
+    """
+    if getattr(t, '__ctype_be__', None) is t:
+        return np.dtype('>' + t._type_)
+    elif getattr(t, '__ctype_le__', None) is t:
+        return np.dtype('<' + t._type_)
+    else:
+        return np.dtype(t._type_)
+
+
+def _from_ctypes_union(t):
+    import ctypes
+    formats = []
+    offsets = []
+    names = []
+    for fname, ftyp in t._fields_:
+        names.append(fname)
+        formats.append(dtype_from_ctypes_type(ftyp))
+        offsets.append(0)  # Union fields are offset to 0
+
+    return np.dtype({
+        "formats": formats,
+        "offsets": offsets,
+        "names": names,
+        "itemsize": ctypes.sizeof(t)})
+
+
+def dtype_from_ctypes_type(t):
+    """
+    Construct a dtype object from a ctypes type
+    """
+    import _ctypes
+    if issubclass(t, _ctypes.Array):
+        return _from_ctypes_array(t)
+    elif issubclass(t, _ctypes._Pointer):
+        raise TypeError("ctypes pointers have no dtype equivalent")
+    elif issubclass(t, _ctypes.Structure):
+        return _from_ctypes_structure(t)
+    elif issubclass(t, _ctypes.Union):
+        return _from_ctypes_union(t)
+    elif isinstance(getattr(t, '_type_', None), str):
+        return _from_ctypes_scalar(t)
+    else:
+        raise NotImplementedError(
+            f"Unknown ctypes type {t.__name__}")

v12x/pylib/numpy/_core/_exceptions.py

@@ -0,0 +1,162 @@
+"""
+Various richly-typed exceptions, that also help us deal with string formatting
+in python where it's easier.
+
+By putting the formatting in `__str__`, we also avoid paying the cost for
+users who silence the exceptions.
+"""
+
+def _unpack_tuple(tup):
+    if len(tup) == 1:
+        return tup[0]
+    else:
+        return tup
+
+
+def _display_as_base(cls):
+    """
+    A decorator that makes an exception class look like its base.
+
+    We use this to hide subclasses that are implementation details - the user
+    should catch the base type, which is what the traceback will show them.
+
+    Classes decorated with this decorator are subject to removal without a
+    deprecation warning.
+    """
+    assert issubclass(cls, Exception)
+    cls.__name__ = cls.__base__.__name__
+    return cls
+
+
+class UFuncTypeError(TypeError):
+    """ Base class for all ufunc exceptions """
+    def __init__(self, ufunc):
+        self.ufunc = ufunc
+
+
+@_display_as_base
+class _UFuncNoLoopError(UFuncTypeError):
+    """ Thrown when a ufunc loop cannot be found """
+    def __init__(self, ufunc, dtypes):
+        super().__init__(ufunc)
+        self.dtypes = tuple(dtypes)
+
+    def __str__(self):
+        return (
+            f"ufunc {self.ufunc.__name__!r} did not contain a loop with signature "
+            f"matching types {_unpack_tuple(self.dtypes[:self.ufunc.nin])!r} "
+            f"-> {_unpack_tuple(self.dtypes[self.ufunc.nin:])!r}"
+        )
+
+
+@_display_as_base
+class _UFuncBinaryResolutionError(_UFuncNoLoopError):
+    """ Thrown when a binary resolution fails """
+    def __init__(self, ufunc, dtypes):
+        super().__init__(ufunc, dtypes)
+        assert len(self.dtypes) == 2
+
+    def __str__(self):
+        return (
+            "ufunc {!r} cannot use operands with types {!r} and {!r}"
+        ).format(
+            self.ufunc.__name__, *self.dtypes
+        )
+
+
+@_display_as_base
+class _UFuncCastingError(UFuncTypeError):
+    def __init__(self, ufunc, casting, from_, to):
+        super().__init__(ufunc)
+        self.casting = casting
+        self.from_ = from_
+        self.to = to
+
+
+@_display_as_base
+class _UFuncInputCastingError(_UFuncCastingError):
+    """ Thrown when a ufunc input cannot be casted """
+    def __init__(self, ufunc, casting, from_, to, i):
+        super().__init__(ufunc, casting, from_, to)
+        self.in_i = i
+
+    def __str__(self):
+        # only show the number if more than one input exists
+        i_str = f"{self.in_i} " if self.ufunc.nin != 1 else ""
+        return (
+            f"Cannot cast ufunc {self.ufunc.__name__!r} input {i_str}from "
+            f"{self.from_!r} to {self.to!r} with casting rule {self.casting!r}"
+        )
+
+
+@_display_as_base
+class _UFuncOutputCastingError(_UFuncCastingError):
+    """ Thrown when a ufunc output cannot be casted """
+    def __init__(self, ufunc, casting, from_, to, i):
+        super().__init__(ufunc, casting, from_, to)
+        self.out_i = i
+
+    def __str__(self):
+        # only show the number if more than one output exists
+        i_str = f"{self.out_i} " if self.ufunc.nout != 1 else ""
+        return (
+            f"Cannot cast ufunc {self.ufunc.__name__!r} output {i_str}from "
+            f"{self.from_!r} to {self.to!r} with casting rule {self.casting!r}"
+        )
+
+
+@_display_as_base
+class _ArrayMemoryError(MemoryError):
+    """ Thrown when an array cannot be allocated"""
+    def __init__(self, shape, dtype):
+        self.shape = shape
+        self.dtype = dtype
+
+    @property
+    def _total_size(self):
+        num_bytes = self.dtype.itemsize
+        for dim in self.shape:
+            num_bytes *= dim
+        return num_bytes
+
+    @staticmethod
+    def _size_to_string(num_bytes):
+        """ Convert a number of bytes into a binary size string """
+
+        # https://en.wikipedia.org/wiki/Binary_prefix
+        LOG2_STEP = 10
+        STEP = 1024
+        units = ['bytes', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB']
+
+        unit_i = max(num_bytes.bit_length() - 1, 1) // LOG2_STEP
+        unit_val = 1 << (unit_i * LOG2_STEP)
+        n_units = num_bytes / unit_val
+        del unit_val
+
+        # ensure we pick a unit that is correct after rounding
+        if round(n_units) == STEP:
+            unit_i += 1
+            n_units /= STEP
+
+        # deal with sizes so large that we don't have units for them
+        if unit_i >= len(units):
+            new_unit_i = len(units) - 1
+            n_units *= 1 << ((unit_i - new_unit_i) * LOG2_STEP)
+            unit_i = new_unit_i
+
+        unit_name = units[unit_i]
+        # format with a sensible number of digits
+        if unit_i == 0:
+            # no decimal point on bytes
+            return f'{n_units:.0f} {unit_name}'
+        elif round(n_units) < 1000:
+            # 3 significant figures, if none are dropped to the left of the .
+            return f'{n_units:#.3g} {unit_name}'
+        else:
+            # just give all the digits otherwise
+            return f'{n_units:#.0f} {unit_name}'
+
+    def __str__(self):
+        size_str = self._size_to_string(self._total_size)
+        return (f"Unable to allocate {size_str} for an array with shape "
+                f"{self.shape} and data type {self.dtype}")

v12x/pylib/numpy/_core/_internal.py

@@ -0,0 +1,964 @@
+"""
+A place for internal code
+
+Some things are more easily handled Python.
+
+"""
+import ast
+import math
+import re
+import sys
+import warnings
+
+from numpy import _NoValue
+from numpy.exceptions import DTypePromotionError
+
+from ._multiarray_umath import _is_view_safe_cast
+from .multiarray import StringDType, array, dtype, promote_types
+
+try:
+    import ctypes
+except ImportError:
+    ctypes = None
+
+if sys.byteorder == 'little':
+    _nbo = '<'
+else:
+    _nbo = '>'
+
+def _makenames_list(adict, align):
+    allfields = []
+
+    for fname, obj in adict.items():
+        n = len(obj)
+        if not isinstance(obj, tuple) or n not in (2, 3):
+            raise ValueError("entry not a 2- or 3- tuple")
+        if n > 2 and obj[2] == fname:
+            continue
+        num = int(obj[1])
+        if num < 0:
+            raise ValueError("invalid offset.")
+        format = dtype(obj[0], align=align)
+        if n > 2:
+            title = obj[2]
+        else:
+            title = None
+        allfields.append((fname, format, num, title))
+    # sort by offsets
+    allfields.sort(key=lambda x: x[2])
+    names = [x[0] for x in allfields]
+    formats = [x[1] for x in allfields]
+    offsets = [x[2] for x in allfields]
+    titles = [x[3] for x in allfields]
+
+    return names, formats, offsets, titles
+
+# Called in PyArray_DescrConverter function when
+#  a dictionary without "names" and "formats"
+#  fields is used as a data-type descriptor.
+def _usefields(adict, align):
+    try:
+        names = adict[-1]
+    except KeyError:
+        names = None
+    if names is None:
+        names, formats, offsets, titles = _makenames_list(adict, align)
+    else:
+        formats = []
+        offsets = []
+        titles = []
+        for name in names:
+            res = adict[name]
+            formats.append(res[0])
+            offsets.append(res[1])
+            if len(res) > 2:
+                titles.append(res[2])
+            else:
+                titles.append(None)
+
+    return dtype({"names": names,
+                  "formats": formats,
+                  "offsets": offsets,
+                  "titles": titles}, align)
+
+
+# construct an array_protocol descriptor list
+#  from the fields attribute of a descriptor
+# This calls itself recursively but should eventually hit
+#  a descriptor that has no fields and then return
+#  a simple typestring
+
+def _array_descr(descriptor):
+    fields = descriptor.fields
+    if fields is None:
+        subdtype = descriptor.subdtype
+        if subdtype is None:
+            if descriptor.metadata is None:
+                return descriptor.str
+            else:
+                new = descriptor.metadata.copy()
+                if new:
+                    return (descriptor.str, new)
+                else:
+                    return descriptor.str
+        else:
+            return (_array_descr(subdtype[0]), subdtype[1])
+
+    names = descriptor.names
+    ordered_fields = [fields[x] + (x,) for x in names]
+    result = []
+    offset = 0
+    for field in ordered_fields:
+        if field[1] > offset:
+            num = field[1] - offset
+            result.append(('', f'|V{num}'))
+            offset += num
+        elif field[1] < offset:
+            raise ValueError(
+                "dtype.descr is not defined for types with overlapping or "
+                "out-of-order fields")
+        if len(field) > 3:
+            name = (field[2], field[3])
+        else:
+            name = field[2]
+        if field[0].subdtype:
+            tup = (name, _array_descr(field[0].subdtype[0]),
+                   field[0].subdtype[1])
+        else:
+            tup = (name, _array_descr(field[0]))
+        offset += field[0].itemsize
+        result.append(tup)
+
+    if descriptor.itemsize > offset:
+        num = descriptor.itemsize - offset
+        result.append(('', f'|V{num}'))
+
+    return result
+
+
+# format_re was originally from numarray by J. Todd Miller
+
+format_re = re.compile(r'(?P<order1>[<>|=]?)'
+                       r'(?P<repeats> *[(]?[ ,0-9]*[)]? *)'
+                       r'(?P<order2>[<>|=]?)'
+                       r'(?P<dtype>[A-Za-z0-9.?]*(?:\[[a-zA-Z0-9,.]+\])?)')
+sep_re = re.compile(r'\s*,\s*')
+space_re = re.compile(r'\s+$')
+
+# astr is a string (perhaps comma separated)
+
+_convorder = {'=': _nbo}
+
+def _commastring(astr):
+    startindex = 0
+    result = []
+    islist = False
+    while startindex < len(astr):
+        mo = format_re.match(astr, pos=startindex)
+        try:
+            (order1, repeats, order2, dtype) = mo.groups()
+        except (TypeError, AttributeError):
+            raise ValueError(
+                f'format number {len(result) + 1} of "{astr}" is not recognized'
+                ) from None
+        startindex = mo.end()
+        # Separator or ending padding
+        if startindex < len(astr):
+            if space_re.match(astr, pos=startindex):
+                startindex = len(astr)
+            else:
+                mo = sep_re.match(astr, pos=startindex)
+                if not mo:
+                    raise ValueError(
+                        f'format number {len(result) + 1} of "{astr}" '
+                        'is not recognized')
+                startindex = mo.end()
+                islist = True
+
+        if order2 == '':
+            order = order1
+        elif order1 == '':
+            order = order2
+        else:
+            order1 = _convorder.get(order1, order1)
+            order2 = _convorder.get(order2, order2)
+            if (order1 != order2):
+                raise ValueError(
+                    f'inconsistent byte-order specification {order1} and {order2}')
+            order = order1
+
+        if order in ('|', '=', _nbo):
+            order = ''
+        dtype = order + dtype
+        if repeats == '':
+            newitem = dtype
+        else:
+            if (repeats[0] == "(" and repeats[-1] == ")"
+                    and repeats[1:-1].strip() != ""
+                    and "," not in repeats):
+                warnings.warn(
+                    'Passing in a parenthesized single number for repeats '
+                    'is deprecated; pass either a single number or indicate '
+                    'a tuple with a comma, like "(2,)".', DeprecationWarning,
+                    stacklevel=2)
+            newitem = (dtype, ast.literal_eval(repeats))
+
+        result.append(newitem)
+
+    return result if islist else result[0]
+
+class dummy_ctype:
+
+    def __init__(self, cls):
+        self._cls = cls
+
+    def __mul__(self, other):
+        return self
+
+    def __call__(self, *other):
+        return self._cls(other)
+
+    def __eq__(self, other):
+        return self._cls == other._cls
+
+    def __ne__(self, other):
+        return self._cls != other._cls
+
+def _getintp_ctype():
+    val = _getintp_ctype.cache
+    if val is not None:
+        return val
+    if ctypes is None:
+        import numpy as np
+        val = dummy_ctype(np.intp)
+    else:
+        char = dtype('n').char
+        if char == 'i':
+            val = ctypes.c_int
+        elif char == 'l':
+            val = ctypes.c_long
+        elif char == 'q':
+            val = ctypes.c_longlong
+        else:
+            val = ctypes.c_long
+    _getintp_ctype.cache = val
+    return val
+
+
+_getintp_ctype.cache = None
+
+# Used for .ctypes attribute of ndarray
+
+class _missing_ctypes:
+    def cast(self, num, obj):
+        return num.value
+
+    class c_void_p:
+        def __init__(self, ptr):
+            self.value = ptr
+
+
+class _ctypes:
+    def __init__(self, array, ptr=None):
+        self._arr = array
+
+        if ctypes:
+            self._ctypes = ctypes
+            self._data = self._ctypes.c_void_p(ptr)
+        else:
+            # fake a pointer-like object that holds onto the reference
+            self._ctypes = _missing_ctypes()
+            self._data = self._ctypes.c_void_p(ptr)
+            self._data._objects = array
+
+        if self._arr.ndim == 0:
+            self._zerod = True
+        else:
+            self._zerod = False
+
+    def data_as(self, obj):
+        """
+        Return the data pointer cast to a particular c-types object.
+        For example, calling ``self._as_parameter_`` is equivalent to
+        ``self.data_as(ctypes.c_void_p)``. Perhaps you want to use
+        the data as a pointer to a ctypes array of floating-point data:
+        ``self.data_as(ctypes.POINTER(ctypes.c_double))``.
+
+        The returned pointer will keep a reference to the array.
+        """
+        # _ctypes.cast function causes a circular reference of self._data in
+        # self._data._objects. Attributes of self._data cannot be released
+        # until gc.collect is called. Make a copy of the pointer first then
+        # let it hold the array reference. This is a workaround to circumvent
+        # the CPython bug https://bugs.python.org/issue12836.
+        ptr = self._ctypes.cast(self._data, obj)
+        ptr._arr = self._arr
+        return ptr
+
+    def shape_as(self, obj):
+        """
+        Return the shape tuple as an array of some other c-types
+        type. For example: ``self.shape_as(ctypes.c_short)``.
+        """
+        if self._zerod:
+            return None
+        return (obj * self._arr.ndim)(*self._arr.shape)
+
+    def strides_as(self, obj):
+        """
+        Return the strides tuple as an array of some other
+        c-types type. For example: ``self.strides_as(ctypes.c_longlong)``.
+        """
+        if self._zerod:
+            return None
+        return (obj * self._arr.ndim)(*self._arr.strides)
+
+    @property
+    def data(self):
+        """
+        A pointer to the memory area of the array as a Python integer.
+        This memory area may contain data that is not aligned, or not in
+        correct byte-order. The memory area may not even be writeable.
+        The array flags and data-type of this array should be respected
+        when passing this attribute to arbitrary C-code to avoid trouble
+        that can include Python crashing. User Beware! The value of this
+        attribute is exactly the same as:
+        ``self._array_interface_['data'][0]``.
+
+        Note that unlike ``data_as``, a reference won't be kept to the array:
+        code like ``ctypes.c_void_p((a + b).ctypes.data)`` will result in a
+        pointer to a deallocated array, and should be spelt
+        ``(a + b).ctypes.data_as(ctypes.c_void_p)``
+        """
+        return self._data.value
+
+    @property
+    def shape(self):
+        """
+        (c_intp*self.ndim): A ctypes array of length self.ndim where
+        the basetype is the C-integer corresponding to ``dtype('p')`` on this
+        platform (see `~numpy.ctypeslib.c_intp`). This base-type could be
+        `ctypes.c_int`, `ctypes.c_long`, or `ctypes.c_longlong` depending on
+        the platform. The ctypes array contains the shape of
+        the underlying array.
+        """
+        return self.shape_as(_getintp_ctype())
+
+    @property
+    def strides(self):
+        """
+        (c_intp*self.ndim): A ctypes array of length self.ndim where
+        the basetype is the same as for the shape attribute. This ctypes
+        array contains the strides information from the underlying array.
+        This strides information is important for showing how many bytes
+        must be jumped to get to the next element in the array.
+        """
+        return self.strides_as(_getintp_ctype())
+
+    @property
+    def _as_parameter_(self):
+        """
+        Overrides the ctypes semi-magic method
+
+        Enables `c_func(some_array.ctypes)`
+        """
+        return self.data_as(ctypes.c_void_p)
+
+
+def _newnames(datatype, order):
+    """
+    Given a datatype and an order object, return a new names tuple, with the
+    order indicated
+    """
+    oldnames = datatype.names
+    nameslist = list(oldnames)
+    if isinstance(order, str):
+        order = [order]
+    seen = set()
+    if isinstance(order, (list, tuple)):
+        for name in order:
+            try:
+                nameslist.remove(name)
+            except ValueError:
+                if name in seen:
+                    raise ValueError(f"duplicate field name: {name}") from None
+                else:
+                    raise ValueError(f"unknown field name: {name}") from None
+            seen.add(name)
+        return tuple(list(order) + nameslist)
+    raise ValueError(f"unsupported order value: {order}")
+
+def _copy_fields(ary):
+    """Return copy of structured array with padding between fields removed.
+
+    Parameters
+    ----------
+    ary : ndarray
+       Structured array from which to remove padding bytes
+
+    Returns
+    -------
+    ary_copy : ndarray
+       Copy of ary with padding bytes removed
+    """
+    dt = ary.dtype
+    copy_dtype = {'names': dt.names,
+                  'formats': [dt.fields[name][0] for name in dt.names]}
+    return array(ary, dtype=copy_dtype, copy=True)
+
+def _promote_fields(dt1, dt2):
+    """ Perform type promotion for two structured dtypes.
+
+    Parameters
+    ----------
+    dt1 : structured dtype
+        First dtype.
+    dt2 : structured dtype
+        Second dtype.
+
+    Returns
+    -------
+    out : dtype
+        The promoted dtype
+
+    Notes
+    -----
+    If one of the inputs is aligned, the result will be.  The titles of
+    both descriptors must match (point to the same field).
+    """
+    # Both must be structured and have the same names in the same order
+    if (dt1.names is None or dt2.names is None) or dt1.names != dt2.names:
+        raise DTypePromotionError(
+                f"field names `{dt1.names}` and `{dt2.names}` mismatch.")
+
+    # if both are identical, we can (maybe!) just return the same dtype.
+    identical = dt1 is dt2
+    new_fields = []
+    for name in dt1.names:
+        field1 = dt1.fields[name]
+        field2 = dt2.fields[name]
+        new_descr = promote_types(field1[0], field2[0])
+        identical = identical and new_descr is field1[0]
+
+        # Check that the titles match (if given):
+        if field1[2:] != field2[2:]:
+            raise DTypePromotionError(
+                    f"field titles of field '{name}' mismatch")
+        if len(field1) == 2:
+            new_fields.append((name, new_descr))
+        else:
+            new_fields.append(((field1[2], name), new_descr))
+
+    res = dtype(new_fields, align=dt1.isalignedstruct or dt2.isalignedstruct)
+
+    # Might as well preserve identity (and metadata) if the dtype is identical
+    # and the itemsize, offsets are also unmodified.  This could probably be
+    # sped up, but also probably just be removed entirely.
+    if identical and res.itemsize == dt1.itemsize:
+        for name in dt1.names:
+            if dt1.fields[name][1] != res.fields[name][1]:
+                return res  # the dtype changed.
+        return dt1
+
+    return res
+
+
+def _getfield_is_safe(oldtype, newtype, offset):
+    """ Checks safety of getfield for object arrays.
+
+    As in _view_is_safe, we need to check that memory containing objects is not
+    reinterpreted as a non-object datatype and vice versa.
+
+    Parameters
+    ----------
+    oldtype : data-type
+        Data type of the original ndarray.
+    newtype : data-type
+        Data type of the field being accessed by ndarray.getfield
+    offset : int
+        Offset of the field being accessed by ndarray.getfield
+
+    Raises
+    ------
+    TypeError
+        If the field access is invalid
+
+    """
+    if newtype.hasobject or oldtype.hasobject:
+        if offset == 0 and _is_view_safe_cast(oldtype, newtype):
+            return
+        if oldtype.names is not None:
+            for name in oldtype.names:
+                if (oldtype.fields[name][1] == offset and
+                        oldtype.fields[name][0] == newtype):
+                    return
+        raise TypeError("Cannot get/set field of an object array")
+    return
+
+def _view_is_safe(oldtype, newtype):
+    """ Checks safety of a view involving object arrays, for example when
+    doing::
+
+        np.zeros(10, dtype=oldtype).view(newtype)
+
+    Parameters
+    ----------
+    oldtype : data-type
+        Data type of original ndarray
+    newtype : data-type
+        Data type of the view
+
+    Raises
+    ------
+    TypeError
+        If the new type is incompatible with the old type.
+
+    """
+
+    # more precise than ``oldtype == newtype``: e.g. dtype((np.record, 'i4,i4'))
+    # views safely as dtype((np.void, 'i4,i4')), while two equal StringDType
+    # instances with separate allocators do not
+    if _is_view_safe_cast(oldtype, newtype):
+        return
+
+    if newtype.hasobject or oldtype.hasobject:
+        raise TypeError("Cannot change data-type for array of references.")
+    return
+
+
+# Given a string containing a PEP 3118 format specifier,
+# construct a NumPy dtype
+
+_pep3118_native_map = {
+    '?': '?',
+    'c': 'S1',
+    'b': 'b',
+    'B': 'B',
+    'h': 'h',
+    'H': 'H',
+    'i': 'i',
+    'I': 'I',
+    'l': 'l',
+    'L': 'L',
+    'q': 'q',
+    'Q': 'Q',
+    'e': 'e',
+    'f': 'f',
+    'd': 'd',
+    'g': 'g',
+    'Zf': 'F',
+    'Zd': 'D',
+    'Zg': 'G',
+    's': 'S',
+    'w': 'U',
+    'O': 'O',
+    'x': 'V',  # padding
+}
+_pep3118_native_typechars = ''.join(_pep3118_native_map.keys())
+
+_pep3118_standard_map = {
+    '?': '?',
+    'c': 'S1',
+    'b': 'b',
+    'B': 'B',
+    'h': 'i2',
+    'H': 'u2',
+    'i': 'i4',
+    'I': 'u4',
+    'l': 'i4',
+    'L': 'u4',
+    'q': 'i8',
+    'Q': 'u8',
+    'e': 'f2',
+    'f': 'f',
+    'd': 'd',
+    'Zf': 'F',
+    'Zd': 'D',
+    's': 'S',
+    'w': 'U',
+    'O': 'O',
+    'x': 'V',  # padding
+}
+_pep3118_standard_typechars = ''.join(_pep3118_standard_map.keys())
+
+_pep3118_unsupported_map = {
+    'u': 'UCS-2 strings',
+    '&': 'pointers',
+    't': 'bitfields',
+    'X': 'function pointers',
+}
+
+class _Stream:
+    def __init__(self, s):
+        self.s = s
+        self.byteorder = '@'
+
+    def advance(self, n):
+        res = self.s[:n]
+        self.s = self.s[n:]
+        return res
+
+    def consume(self, c):
+        if self.s[:len(c)] == c:
+            self.advance(len(c))
+            return True
+        return False
+
+    def consume_until(self, c):
+        if callable(c):
+            i = 0
+            while i < len(self.s) and not c(self.s[i]):
+                i = i + 1
+            return self.advance(i)
+        else:
+            i = self.s.index(c)
+            res = self.advance(i)
+            self.advance(len(c))
+            return res
+
+    @property
+    def next(self):
+        return self.s[0]
+
+    def __bool__(self):
+        return bool(self.s)
+
+
+def _dtype_from_pep3118(spec):
+    stream = _Stream(spec)
+    dtype, align = __dtype_from_pep3118(stream, is_subdtype=False)
+    return dtype
+
+def __dtype_from_pep3118(stream, is_subdtype):
+    field_spec = {
+        'names': [],
+        'formats': [],
+        'offsets': [],
+        'itemsize': 0
+    }
+    offset = 0
+    common_alignment = 1
+    is_padding = False
+
+    # Parse spec
+    while stream:
+        value = None
+
+        # End of structure, bail out to upper level
+        if stream.consume('}'):
+            break
+
+        # Sub-arrays (1)
+        shape = None
+        if stream.consume('('):
+            shape = stream.consume_until(')')
+            shape = tuple(map(int, shape.split(',')))
+
+        # Byte order
+        if stream.next in ('@', '=', '<', '>', '^', '!'):
+            byteorder = stream.advance(1)
+            if byteorder == '!':
+                byteorder = '>'
+            stream.byteorder = byteorder
+
+        # Byte order characters also control native vs. standard type sizes
+        if stream.byteorder in ('@', '^'):
+            type_map = _pep3118_native_map
+            type_map_chars = _pep3118_native_typechars
+        else:
+            type_map = _pep3118_standard_map
+            type_map_chars = _pep3118_standard_typechars
+
+        # Item sizes
+        itemsize_str = stream.consume_until(lambda c: not c.isdigit())
+        if itemsize_str:
+            itemsize = int(itemsize_str)
+        else:
+            itemsize = 1
+
+        # Data types
+        is_padding = False
+
+        if stream.consume('T{'):
+            value, align = __dtype_from_pep3118(
+                stream, is_subdtype=True)
+        elif stream.next in type_map_chars:
+            if stream.next == 'Z':
+                typechar = stream.advance(2)
+            else:
+                typechar = stream.advance(1)
+
+            is_padding = (typechar == 'x')
+            dtypechar = type_map[typechar]
+            if dtypechar in 'USV':
+                dtypechar += f'{itemsize}'
+                itemsize = 1
+            numpy_byteorder = {'@': '=', '^': '='}.get(
+                stream.byteorder, stream.byteorder)
+            value = dtype(numpy_byteorder + dtypechar)
+            align = value.alignment
+        elif stream.next in _pep3118_unsupported_map:
+            desc = _pep3118_unsupported_map[stream.next]
+            raise NotImplementedError(
+                f"Unrepresentable PEP 3118 data type {stream.next!r} ({desc})")
+        else:
+            raise ValueError(
+                f"Unknown PEP 3118 data type specifier {stream.s!r}"
+            )
+
+        #
+        # Native alignment may require padding
+        #
+        # Here we assume that the presence of a '@' character implicitly
+        # implies that the start of the array is *already* aligned.
+        #
+        extra_offset = 0
+        if stream.byteorder == '@':
+            start_padding = (-offset) % align
+            intra_padding = (-value.itemsize) % align
+
+            offset += start_padding
+
+            if intra_padding != 0:
+                if itemsize > 1 or (shape is not None and _prod(shape) > 1):
+                    # Inject internal padding to the end of the sub-item
+                    value = _add_trailing_padding(value, intra_padding)
+                else:
+                    # We can postpone the injection of internal padding,
+                    # as the item appears at most once
+                    extra_offset += intra_padding
+
+            # Update common alignment
+            common_alignment = _lcm(align, common_alignment)
+
+        # Convert itemsize to sub-array
+        if itemsize != 1:
+            value = dtype((value, (itemsize,)))
+
+        # Sub-arrays (2)
+        if shape is not None:
+            value = dtype((value, shape))
+
+        # Field name
+        if stream.consume(':'):
+            name = stream.consume_until(':')
+        else:
+            name = None
+
+        if not (is_padding and name is None):
+            if name is not None and name in field_spec['names']:
+                raise RuntimeError(
+                    f"Duplicate field name '{name}' in PEP3118 format"
+                )
+            field_spec['names'].append(name)
+            field_spec['formats'].append(value)
+            field_spec['offsets'].append(offset)
+
+        offset += value.itemsize
+        offset += extra_offset
+
+        field_spec['itemsize'] = offset
+
+    # extra final padding for aligned types
+    if stream.byteorder == '@':
+        field_spec['itemsize'] += (-offset) % common_alignment
+
+    # Check if this was a simple 1-item type, and unwrap it
+    if (field_spec['names'] == [None]
+            and field_spec['offsets'][0] == 0
+            and field_spec['itemsize'] == field_spec['formats'][0].itemsize
+            and not is_subdtype):
+        ret = field_spec['formats'][0]
+    else:
+        _fix_names(field_spec)
+        ret = dtype(field_spec)
+
+    # Finished
+    return ret, common_alignment
+
+def _fix_names(field_spec):
+    """ Replace names which are None with the next unused f%d name """
+    names = field_spec['names']
+    for i, name in enumerate(names):
+        if name is not None:
+            continue
+
+        j = 0
+        while True:
+            name = f'f{j}'
+            if name not in names:
+                break
+            j = j + 1
+        names[i] = name
+
+def _add_trailing_padding(value, padding):
+    """Inject the specified number of padding bytes at the end of a dtype"""
+    if value.fields is None:
+        field_spec = {
+            'names': ['f0'],
+            'formats': [value],
+            'offsets': [0],
+            'itemsize': value.itemsize
+        }
+    else:
+        fields = value.fields
+        names = value.names
+        field_spec = {
+            'names': names,
+            'formats': [fields[name][0] for name in names],
+            'offsets': [fields[name][1] for name in names],
+            'itemsize': value.itemsize
+        }
+
+    field_spec['itemsize'] += padding
+    return dtype(field_spec)
+
+def _prod(a):
+    p = 1
+    for x in a:
+        p *= x
+    return p
+
+def _gcd(a, b):
+    """Calculate the greatest common divisor of a and b"""
+    if not (math.isfinite(a) and math.isfinite(b)):
+        raise ValueError('Can only find greatest common divisor of '
+                         f'finite arguments, found "{a}" and "{b}"')
+    while b:
+        a, b = b, a % b
+    return a
+
+def _lcm(a, b):
+    return a // _gcd(a, b) * b
+
+def array_ufunc_errmsg_formatter(dummy, ufunc, method, *inputs, **kwargs):
+    """ Format the error message for when __array_ufunc__ gives up. """
+    args_string = ', '.join([f'{arg!r}' for arg in inputs] +
+                            [f'{k}={v!r}'
+                             for k, v in kwargs.items()])
+    args = inputs + kwargs.get('out', ())
+    types_string = ', '.join(repr(type(arg).__name__) for arg in args)
+    return ('operand type(s) all returned NotImplemented from '
+            f'__array_ufunc__({ufunc!r}, {method!r}, {args_string}): {types_string}'
+            )
+
+
+def array_function_errmsg_formatter(public_api, types):
+    """ Format the error message for when __array_ufunc__ gives up. """
+    func_name = f'{public_api.__module__}.{public_api.__name__}'
+    return (f"no implementation found for '{func_name}' on types that implement "
+            f'__array_function__: {list(types)}')
+
+
+def _ufunc_doc_signature_formatter(ufunc):
+    """
+    Builds a signature string which resembles PEP 457
+
+    This is used to construct the first line of the docstring
+
+    Keep in sync with `_ufunc_inspect_signature_builder`.
+    """
+
+    # input arguments are simple
+    if ufunc.nin == 1:
+        in_args = 'x'
+    else:
+        in_args = ', '.join(f'x{i + 1}' for i in range(ufunc.nin))
+
+    # output arguments are both keyword or positional
+    if ufunc.nout == 0:
+        out_args = ', /, out=()'
+    elif ufunc.nout == 1:
+        out_args = ', /, out=None'
+    else:
+        out_args = '[, {positional}], / [, out={default}]'.format(
+            positional=', '.join(
+                f'out{i + 1}' for i in range(ufunc.nout)),
+            default=repr((None,) * ufunc.nout)
+        )
+
+    # keyword only args depend on whether this is a gufunc
+    kwargs = (
+        ", casting='same_kind'"
+        ", order='K'"
+        ", dtype=None"
+        ", subok=True"
+    )
+
+    # NOTE: gufuncs may or may not support the `axis` parameter
+    if ufunc.signature is None:
+        kwargs = f", where=True{kwargs}[, signature]"
+    else:
+        kwargs += "[, signature, axes, axis]"
+
+    # join all the parts together
+    return f'{ufunc.__name__}({in_args}{out_args}, *{kwargs})'
+
+
+def _ufunc_inspect_signature_builder(ufunc):
+    """
+    Builds a ``__signature__`` string.
+
+    Should be kept in sync with `_ufunc_doc_signature_formatter`.
+    """
+
+    from inspect import Parameter, Signature
+
+    params = []
+
+    # positional-only input parameters
+    if ufunc.nin == 1:
+        params.append(Parameter("x", Parameter.POSITIONAL_ONLY))
+    else:
+        params.extend(
+            Parameter(f"x{i}", Parameter.POSITIONAL_ONLY)
+            for i in range(1, ufunc.nin + 1)
+        )
+
+    # for the sake of simplicity, we only consider a single output parameter
+    if ufunc.nout == 1:
+        out_default = None
+    else:
+        out_default = (None,) * ufunc.nout
+    params.append(
+        Parameter("out", Parameter.POSITIONAL_OR_KEYWORD, default=out_default),
+    )
+
+    if ufunc.signature is None:
+        params.append(Parameter("where", Parameter.KEYWORD_ONLY, default=True))
+    else:
+        # NOTE: not all gufuncs support the `axis` parameters
+        params.append(Parameter("axes", Parameter.KEYWORD_ONLY, default=_NoValue))
+        params.append(Parameter("axis", Parameter.KEYWORD_ONLY, default=_NoValue))
+        params.append(Parameter("keepdims", Parameter.KEYWORD_ONLY, default=False))
+
+    params.extend((
+        Parameter("casting", Parameter.KEYWORD_ONLY, default='same_kind'),
+        Parameter("order", Parameter.KEYWORD_ONLY, default='K'),
+        Parameter("dtype", Parameter.KEYWORD_ONLY, default=None),
+        Parameter("subok", Parameter.KEYWORD_ONLY, default=True),
+        Parameter("signature", Parameter.KEYWORD_ONLY, default=None),
+    ))
+
+    return Signature(params)
+
+
+def npy_ctypes_check(cls):
+    # determine if a class comes from ctypes, in order to work around
+    # a bug in the buffer protocol for those objects, bpo-10746
+    try:
+        # ctypes class are new-style, so have an __mro__. This probably fails
+        # for ctypes classes with multiple inheritance.
+        # # (..., _ctypes._CData, object)
+        ctype_base = cls.__mro__[-2]
+        # right now, they're part of the _ctypes module
+        return '_ctypes' in ctype_base.__module__
+    except Exception:
+        return False
+
+# used to handle the _NoValue default argument for na_object
+# in the C implementation of the __reduce__ method for stringdtype
+def _convert_to_stringdtype_kwargs(coerce, na_object=_NoValue):
+    if na_object is _NoValue:
+        return StringDType(coerce=coerce)
+    return StringDType(coerce=coerce, na_object=na_object)

v12x/pylib/numpy/_core/_methods.py

@@ -0,0 +1,252 @@
+"""
+Array methods which are called by both the C-code for the method
+and the Python code for the NumPy-namespace function
+
+"""
+import os
+import pickle
+import warnings
+from contextlib import nullcontext
+
+import numpy as np
+from numpy._core import multiarray as mu, numerictypes as nt, umath as um
+from numpy._core.multiarray import asanyarray
+from numpy._globals import _NoValue
+
+# save those O(100) nanoseconds!
+bool_dt = mu.dtype("bool")
+umr_maximum = um.maximum.reduce
+umr_minimum = um.minimum.reduce
+umr_sum = um.add.reduce
+umr_prod = um.multiply.reduce
+umr_bitwise_count = um.bitwise_count
+umr_any = um.logical_or.reduce
+umr_all = um.logical_and.reduce
+
+# Complex types to -> (2,)float view for fast-path computation in _var()
+_complex_to_float = {
+    nt.dtype(nt.csingle): nt.dtype(nt.single),
+    nt.dtype(nt.cdouble): nt.dtype(nt.double),
+}
+# Special case for windows: ensure double takes precedence
+if nt.dtype(nt.longdouble) != nt.dtype(nt.double):
+    _complex_to_float.update({
+        nt.dtype(nt.clongdouble): nt.dtype(nt.longdouble),
+    })
+
+# avoid keyword arguments to speed up parsing, saves about 15%-20% for very
+# small reductions
+def _amax(a, axis=None, out=None, keepdims=False,
+          initial=_NoValue, where=True):
+    return umr_maximum(a, axis, None, out, keepdims, initial, where)
+
+def _amin(a, axis=None, out=None, keepdims=False,
+          initial=_NoValue, where=True):
+    return umr_minimum(a, axis, None, out, keepdims, initial, where)
+
+def _sum(a, axis=None, dtype=None, out=None, keepdims=False,
+         initial=_NoValue, where=True):
+    return umr_sum(a, axis, dtype, out, keepdims, initial, where)
+
+def _prod(a, axis=None, dtype=None, out=None, keepdims=False,
+          initial=_NoValue, where=True):
+    return umr_prod(a, axis, dtype, out, keepdims, initial, where)
+
+def _any(a, axis=None, dtype=None, out=None, keepdims=False, *, where=True):
+    # By default, return a boolean for any and all
+    if dtype is None:
+        dtype = bool_dt
+    # Parsing keyword arguments is currently fairly slow, so avoid it for now
+    if where is True:
+        return umr_any(a, axis, dtype, out, keepdims)
+    return umr_any(a, axis, dtype, out, keepdims, where=where)
+
+def _all(a, axis=None, dtype=None, out=None, keepdims=False, *, where=True):
+    # By default, return a boolean for any and all
+    if dtype is None:
+        dtype = bool_dt
+    # Parsing keyword arguments is currently fairly slow, so avoid it for now
+    if where is True:
+        return umr_all(a, axis, dtype, out, keepdims)
+    return umr_all(a, axis, dtype, out, keepdims, where=where)
+
+def _count_reduce_items(arr, axis, keepdims=False, where=True):
+    # fast-path for the default case
+    if where is True:
+        # no boolean mask given, calculate items according to axis
+        if axis is None:
+            axis = tuple(range(arr.ndim))
+        elif not isinstance(axis, tuple):
+            axis = (axis,)
+        items = 1
+        for ax in axis:
+            items *= arr.shape[mu.normalize_axis_index(ax, arr.ndim)]
+        items = nt.intp(items)
+    else:
+        # TODO: Optimize case when `where` is broadcast along a non-reduction
+        # axis and full sum is more excessive than needed.
+
+        # guarded to protect circular imports
+        from numpy.lib._stride_tricks_impl import broadcast_to
+        # count True values in (potentially broadcasted) boolean mask
+        items = umr_sum(broadcast_to(where, arr.shape), axis, nt.intp, None,
+                        keepdims)
+    return items
+
+def _clip(a, min=None, max=None, out=None, **kwargs):
+    if a.dtype.kind in "iu":
+        # If min/max is a Python integer, deal with out-of-bound values here.
+        # (This enforces NEP 50 rules as no value based promotion is done.)
+        if type(min) is int and min <= np.iinfo(a.dtype).min:
+            min = None
+        if type(max) is int and max >= np.iinfo(a.dtype).max:
+            max = None
+
+    if min is None and max is None:
+        # return identity
+        return um.positive(a, out=out, **kwargs)
+    elif min is None:
+        return um.minimum(a, max, out=out, **kwargs)
+    elif max is None:
+        return um.maximum(a, min, out=out, **kwargs)
+    else:
+        return um.clip(a, min, max, out=out, **kwargs)
+
+def _mean(a, axis=None, dtype=None, out=None, keepdims=False, *, where=True):
+    arr = asanyarray(a)
+
+    is_float16_result = False
+
+    rcount = _count_reduce_items(arr, axis, keepdims=keepdims, where=where)
+    if rcount == 0 if where is True else umr_any(rcount == 0, axis=None):
+        warnings.warn("Mean of empty slice", RuntimeWarning, stacklevel=2)
+
+    # Cast bool, unsigned int, and int to float64 by default
+    if dtype is None:
+        if issubclass(arr.dtype.type, (nt.integer, nt.bool)):
+            dtype = mu.dtype('f8')
+        elif issubclass(arr.dtype.type, nt.float16):
+            dtype = mu.dtype('f4')
+            is_float16_result = True
+
+    ret = umr_sum(arr, axis, dtype, out, keepdims, where=where)
+    if isinstance(ret, mu.ndarray):
+        ret = um.true_divide(
+                ret, rcount, out=ret, casting='unsafe', subok=False)
+        if is_float16_result and out is None:
+            ret = arr.dtype.type(ret)
+    elif hasattr(ret, 'dtype'):
+        if is_float16_result:
+            ret = arr.dtype.type(ret / rcount)
+        else:
+            ret = ret.dtype.type(ret / rcount)
+    else:
+        ret = ret / rcount
+
+    return ret
+
+def _var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=False, *,
+         where=True, mean=None):
+    arr = asanyarray(a)
+
+    rcount = _count_reduce_items(arr, axis, keepdims=keepdims, where=where)
+    # Make this warning show up on top.
+    if ddof >= rcount if where is True else umr_any(ddof >= rcount, axis=None):
+        warnings.warn("Degrees of freedom <= 0 for slice", RuntimeWarning,
+                      stacklevel=2)
+
+    # Cast bool, unsigned int, and int to float64 by default
+    if dtype is None and issubclass(arr.dtype.type, (nt.integer, nt.bool)):
+        dtype = mu.dtype('f8')
+
+    if mean is not None:
+        arrmean = mean
+    else:
+        # Compute the mean.
+        # Note that if dtype is not of inexact type then arraymean will
+        # not be either.
+        arrmean = umr_sum(arr, axis, dtype, keepdims=True, where=where)
+        # The shape of rcount has to match arrmean to not change the shape of
+        # out in broadcasting. Otherwise, it cannot be stored back to arrmean.
+        if rcount.ndim == 0:
+            # fast-path for default case when where is True
+            div = rcount
+        else:
+            # matching rcount to arrmean when where is specified as array
+            div = rcount.reshape(arrmean.shape)
+        if isinstance(arrmean, mu.ndarray):
+            arrmean = um.true_divide(arrmean, div, out=arrmean,
+                                     casting='unsafe', subok=False)
+        elif hasattr(arrmean, "dtype"):
+            arrmean = arrmean.dtype.type(arrmean / rcount)
+        else:
+            arrmean = arrmean / rcount
+
+    # Compute sum of squared deviations from mean
+    # Note that x may not be inexact and that we need it to be an array,
+    # not a scalar.
+    x = um.subtract(arr, arrmean, out=...)
+    if issubclass(arr.dtype.type, (nt.floating, nt.integer)):
+        x = um.square(x, out=x)
+    # Fast-paths for built-in complex types
+    elif (_float_dtype := _complex_to_float.get(x.dtype)) is not None:
+        xv = x.view(dtype=(_float_dtype, (2,)))
+        um.square(xv, out=xv)
+        x = um.add(xv[..., 0], xv[..., 1], out=x.real)
+    # Most general case; includes handling object arrays containing imaginary
+    # numbers and complex types with non-native byteorder
+    else:
+        x = um.multiply(x, um.conjugate(x), out=x).real
+
+    ret = umr_sum(x, axis, dtype, out, keepdims=keepdims, where=where)
+
+    # Compute degrees of freedom and make sure it is not negative.
+    rcount = um.maximum(rcount - ddof, 0)
+
+    # divide by degrees of freedom
+    if isinstance(ret, mu.ndarray):
+        ret = um.true_divide(
+                ret, rcount, out=ret, casting='unsafe', subok=False)
+    elif hasattr(ret, 'dtype'):
+        ret = ret.dtype.type(ret / rcount)
+    else:
+        ret = ret / rcount
+
+    return ret
+
+def _std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=False, *,
+         where=True, mean=None):
+    ret = _var(a, axis=axis, dtype=dtype, out=out, ddof=ddof,
+               keepdims=keepdims, where=where, mean=mean)
+
+    if isinstance(ret, mu.ndarray):
+        ret = um.sqrt(ret, out=ret)
+    elif hasattr(ret, 'dtype'):
+        ret = ret.dtype.type(um.sqrt(ret))
+    else:
+        ret = um.sqrt(ret)
+
+    return ret
+
+def _ptp(a, axis=None, out=None, keepdims=False):
+    return um.subtract(
+        umr_maximum(a, axis, None, out, keepdims),
+        umr_minimum(a, axis, None, None, keepdims),
+        out
+    )
+
+def _dump(self, file, protocol=2):
+    if hasattr(file, 'write'):
+        ctx = nullcontext(file)
+    else:
+        ctx = open(os.fspath(file), "wb")
+    with ctx as f:
+        pickle.dump(self, f, protocol=protocol)
+
+def _dumps(self, protocol=2):
+    return pickle.dumps(self, protocol=protocol)
+
+def _bitwise_count(a, out=None, *, where=True, casting='same_kind',
+          order='K', dtype=None, subok=True):
+    return umr_bitwise_count(a, out, where=where, casting=casting,
+            order=order, dtype=dtype, subok=subok)

v12x/pylib/numpy/_core/_string_helpers.py

@@ -0,0 +1,100 @@
+"""
+String-handling utilities to avoid locale-dependence.
+
+Used primarily to generate type name aliases.
+"""
+# "import string" is costly to import!
+# Construct the translation tables directly
+#   "A" = chr(65), "a" = chr(97)
+_all_chars = tuple(map(chr, range(256)))
+_ascii_upper = _all_chars[65:65 + 26]
+_ascii_lower = _all_chars[97:97 + 26]
+LOWER_TABLE = _all_chars[:65] + _ascii_lower + _all_chars[65 + 26:]
+UPPER_TABLE = _all_chars[:97] + _ascii_upper + _all_chars[97 + 26:]
+
+
+def english_lower(s):
+    """ Apply English case rules to convert ASCII strings to all lower case.
+
+    This is an internal utility function to replace calls to str.lower() such
+    that we can avoid changing behavior with changing locales. In particular,
+    Turkish has distinct dotted and dotless variants of the Latin letter "I" in
+    both lowercase and uppercase. Thus, "I".lower() != "i" in a "tr" locale.
+
+    Parameters
+    ----------
+    s : str
+
+    Returns
+    -------
+    lowered : str
+
+    Examples
+    --------
+    >>> from numpy._core.numerictypes import english_lower
+    >>> english_lower('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_')
+    'abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz0123456789_'
+    >>> english_lower('')
+    ''
+    """
+    lowered = s.translate(LOWER_TABLE)
+    return lowered
+
+
+def english_upper(s):
+    """ Apply English case rules to convert ASCII strings to all upper case.
+
+    This is an internal utility function to replace calls to str.upper() such
+    that we can avoid changing behavior with changing locales. In particular,
+    Turkish has distinct dotted and dotless variants of the Latin letter "I" in
+    both lowercase and uppercase. Thus, "i".upper() != "I" in a "tr" locale.
+
+    Parameters
+    ----------
+    s : str
+
+    Returns
+    -------
+    uppered : str
+
+    Examples
+    --------
+    >>> from numpy._core.numerictypes import english_upper
+    >>> english_upper('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_')
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_'
+    >>> english_upper('')
+    ''
+    """
+    uppered = s.translate(UPPER_TABLE)
+    return uppered
+
+
+def english_capitalize(s):
+    """ Apply English case rules to convert the first character of an ASCII
+    string to upper case.
+
+    This is an internal utility function to replace calls to str.capitalize()
+    such that we can avoid changing behavior with changing locales.
+
+    Parameters
+    ----------
+    s : str
+
+    Returns
+    -------
+    capitalized : str
+
+    Examples
+    --------
+    >>> from numpy._core.numerictypes import english_capitalize
+    >>> english_capitalize('int8')
+    'Int8'
+    >>> english_capitalize('Int8')
+    'Int8'
+    >>> english_capitalize('')
+    ''
+    """
+    if s:
+        return english_upper(s[0]) + s[1:]
+    else:
+        return s

v12x/pylib/numpy/_core/_type_aliases.py

@@ -0,0 +1,130 @@
+"""
+Due to compatibility, numpy has a very large number of different naming
+conventions for the scalar types (those subclassing from `numpy.generic`).
+This file produces a convoluted set of dictionaries mapping names to types,
+and sometimes other mappings too.
+
+.. data:: allTypes
+    A dictionary of names to types that will be exposed as attributes through
+    ``np._core.numerictypes.*``
+
+.. data:: sctypeDict
+    Similar to `allTypes`, but maps a broader set of aliases to their types.
+
+.. data:: sctypes
+    A dictionary keyed by a "type group" string, providing a list of types
+    under that group.
+
+"""
+
+import numpy._core.multiarray as ma
+from numpy._core.multiarray import dtype, typeinfo
+
+######################################
+# Building `sctypeDict` and `allTypes`
+######################################
+
+sctypeDict = {}
+allTypes = {}
+c_names_dict = {}
+
+_abstract_type_names = {
+    "generic", "integer", "inexact", "floating", "number",
+    "flexible", "character", "complexfloating", "unsignedinteger",
+    "signedinteger"
+}
+
+for _abstract_type_name in _abstract_type_names:
+    allTypes[_abstract_type_name] = getattr(ma, _abstract_type_name)
+    del _abstract_type_name
+
+for k, v in typeinfo.items():
+    if k.startswith("NPY_") and v not in c_names_dict:
+        c_names_dict[k[4:]] = v
+    else:
+        concrete_type = v.type
+        allTypes[k] = concrete_type
+        sctypeDict[k] = concrete_type
+        del concrete_type
+    del k, v
+
+_aliases = {
+    "double": "float64",
+    "cdouble": "complex128",
+    "single": "float32",
+    "csingle": "complex64",
+    "half": "float16",
+    "bool_": "bool",
+    # Default integer:
+    "int_": "intp",
+    "uint": "uintp",
+}
+
+for k, v in _aliases.items():
+    sctypeDict[k] = allTypes[v]
+    allTypes[k] = allTypes[v]
+    del k, v
+
+# extra aliases are added only to `sctypeDict`
+# to support dtype name access, such as`np.dtype("float")`
+_extra_aliases = {
+    "float": "float64",
+    "complex": "complex128",
+    "object": "object_",
+    "bytes": "bytes_",
+    "int": "int_",
+    "str": "str_",
+    "unicode": "str_",
+}
+
+for k, v in _extra_aliases.items():
+    sctypeDict[k] = allTypes[v]
+    del k, v
+
+# include extended precision sized aliases
+for is_complex, full_name in [(False, "longdouble"), (True, "clongdouble")]:
+    longdouble_type = allTypes[full_name]
+
+    bits = dtype(longdouble_type).itemsize * 8
+    base_name = "complex" if is_complex else "float"
+    extended_prec_name = f"{base_name}{bits}"
+    if extended_prec_name not in allTypes:
+        sctypeDict[extended_prec_name] = longdouble_type
+        allTypes[extended_prec_name] = longdouble_type
+
+    del is_complex, full_name, longdouble_type, bits, base_name, extended_prec_name
+
+
+####################
+# Building `sctypes`
+####################
+
+sctypes = {"int": set(), "uint": set(), "float": set(),
+           "complex": set(), "others": set()}
+
+for type_info in typeinfo.values():
+    if type_info.kind in ["M", "m"]:  # exclude timedelta and datetime
+        continue
+
+    concrete_type = type_info.type
+
+    # find proper group for each concrete type
+    for type_group, abstract_type in [
+        ("int", ma.signedinteger), ("uint", ma.unsignedinteger),
+        ("float", ma.floating), ("complex", ma.complexfloating),
+        ("others", ma.generic)
+    ]:
+        if issubclass(concrete_type, abstract_type):
+            sctypes[type_group].add(concrete_type)
+            del type_group, abstract_type
+            break
+
+    del type_info, concrete_type
+
+# sort sctype groups by bitsize, then by name (sort needs to be deterministic)
+for sctype_key in sctypes.keys():
+    sctype_list = list(sctypes[sctype_key])
+    sctype_list.sort(key=lambda x: (dtype(x).itemsize, x.__name__))
+    sctypes[sctype_key] = sctype_list
+
+    del sctype_key, sctype_list

v12x/pylib/numpy/_core/_ufunc_config.py

@@ -0,0 +1,515 @@
+"""
+Functions for changing global ufunc configuration
+
+This provides helpers which wrap `_get_extobj_dict` and `_make_extobj`, and
+`_extobj_contextvar` from umath.
+"""
+import functools
+
+from numpy._utils import set_module
+
+from .umath import _extobj_contextvar, _get_extobj_dict, _make_extobj
+
+__all__ = [
+    "seterr", "geterr", "setbufsize", "getbufsize", "seterrcall", "geterrcall",
+    "errstate"
+]
+
+
+@set_module('numpy')
+def seterr(all=None, divide=None, over=None, under=None, invalid=None):
+    """
+    Set how floating-point errors are handled.
+
+    Note that operations on integer scalar types (such as `int16`) are
+    handled like floating point, and are affected by these settings.
+
+    Parameters
+    ----------
+    all : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional
+        Set treatment for all types of floating-point errors at once:
+
+        - ignore: Take no action when the exception occurs.
+        - warn: Print a :exc:`RuntimeWarning` (via the Python `warnings`
+          module).
+        - raise: Raise a :exc:`FloatingPointError`.
+        - call: Call a function specified using the `seterrcall` function.
+        - print: Print a warning directly to ``stdout``.
+        - log: Record error in a Log object specified by `seterrcall`.
+
+        The default is not to change the current behavior.
+    divide : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional
+        Treatment for division by zero.
+    over : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional
+        Treatment for floating-point overflow.
+    under : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional
+        Treatment for floating-point underflow.
+    invalid : {'ignore', 'warn', 'raise', 'call', 'print', 'log'}, optional
+        Treatment for invalid floating-point operation.
+
+    Returns
+    -------
+    old_settings : dict
+        Dictionary containing the old settings.
+
+    See also
+    --------
+    seterrcall : Set a callback function for the 'call' mode.
+    geterr, geterrcall, errstate
+
+
+    Notes
+    -----
+    The floating-point exceptions are defined in the IEEE 754 standard [1]_:
+
+    - Division by zero: infinite result obtained from finite numbers.
+    - Overflow: result too large to be expressed.
+    - Underflow: result so close to zero that some precision
+      was lost.
+    - Invalid operation: result is not an expressible number, typically
+      indicates that a NaN was produced.
+
+    **Concurrency note:** see  :ref:`fp_error_handling`
+
+    .. [1] https://en.wikipedia.org/wiki/IEEE_754
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> orig_settings = np.seterr(all='ignore')  # seterr to known value
+    >>> np.int16(32000) * np.int16(3)
+    np.int16(30464)
+    >>> np.seterr(over='raise')
+    {'divide': 'ignore', 'over': 'ignore', 'under': 'ignore', 'invalid': 'ignore'}
+    >>> old_settings = np.seterr(all='warn', over='raise')
+    >>> np.int16(32000) * np.int16(3)
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    FloatingPointError: overflow encountered in scalar multiply
+
+    >>> old_settings = np.seterr(all='print')
+    >>> np.geterr()
+    {'divide': 'print', 'over': 'print', 'under': 'print', 'invalid': 'print'}
+    >>> np.int16(32000) * np.int16(3)
+    np.int16(30464)
+    >>> np.seterr(**orig_settings)  # restore original
+    {'divide': 'print', 'over': 'print', 'under': 'print', 'invalid': 'print'}
+
+    """
+
+    old = _get_extobj_dict()
+    # The errstate doesn't include call and bufsize, so pop them:
+    old.pop("call", None)
+    old.pop("bufsize", None)
+
+    extobj = _make_extobj(
+            all=all, divide=divide, over=over, under=under, invalid=invalid)
+    _extobj_contextvar.set(extobj)
+    return old
+
+
+@set_module('numpy')
+def geterr():
+    """
+    Get the current way of handling floating-point errors.
+
+    Returns
+    -------
+    res : dict
+        A dictionary with keys "divide", "over", "under", and "invalid",
+        whose values are from the strings "ignore", "print", "log", "warn",
+        "raise", and "call". The keys represent possible floating-point
+        exceptions, and the values define how these exceptions are handled.
+
+    See Also
+    --------
+    geterrcall, seterr, seterrcall
+
+    Notes
+    -----
+    For complete documentation of the types of floating-point exceptions and
+    treatment options, see `seterr`.
+
+    **Concurrency note:** see :doc:`/reference/routines.err`
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.geterr()
+    {'divide': 'warn', 'over': 'warn', 'under': 'ignore', 'invalid': 'warn'}
+    >>> np.arange(3.) / np.arange(3.)  # doctest: +SKIP
+    array([nan,  1.,  1.])
+    RuntimeWarning: invalid value encountered in divide
+
+    >>> oldsettings = np.seterr(all='warn', invalid='raise')
+    >>> np.geterr()
+    {'divide': 'warn', 'over': 'warn', 'under': 'warn', 'invalid': 'raise'}
+    >>> np.arange(3.) / np.arange(3.)
+    Traceback (most recent call last):
+      ...
+    FloatingPointError: invalid value encountered in divide
+    >>> oldsettings = np.seterr(**oldsettings)  # restore original
+
+    """
+    res = _get_extobj_dict()
+    # The "geterr" doesn't include call and bufsize,:
+    res.pop("call", None)
+    res.pop("bufsize", None)
+    return res
+
+
+@set_module('numpy')
+def setbufsize(size):
+    """
+    Set the size of the buffer used in ufuncs.
+
+    .. versionchanged:: 2.0
+        The scope of setting the buffer is tied to the `numpy.errstate`
+        context.  Exiting a ``with errstate():`` will also restore the bufsize.
+
+    Parameters
+    ----------
+    size : int
+        Size of buffer.
+
+    Returns
+    -------
+    bufsize : int
+        Previous size of ufunc buffer in bytes.
+
+    Notes
+    -----
+    **Concurrency note:** see :doc:`/reference/routines.err`
+
+    Examples
+    --------
+    When exiting a `numpy.errstate` context manager the bufsize is restored:
+
+    >>> import numpy as np
+    >>> with np.errstate():
+    ...     np.setbufsize(4096)
+    ...     print(np.getbufsize())
+    ...
+    8192
+    4096
+    >>> np.getbufsize()
+    8192
+
+    """
+    if size < 0:
+        raise ValueError("buffer size must be non-negative")
+    old = _get_extobj_dict()["bufsize"]
+    extobj = _make_extobj(bufsize=size)
+    _extobj_contextvar.set(extobj)
+    return old
+
+
+@set_module('numpy')
+def getbufsize():
+    """
+    Return the size of the buffer used in ufuncs.
+
+    Returns
+    -------
+    getbufsize : int
+        Size of ufunc buffer in bytes.
+
+    Notes
+    -----
+
+    **Concurrency note:** see :doc:`/reference/routines.err`
+
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.getbufsize()
+    8192
+
+    """
+    return _get_extobj_dict()["bufsize"]
+
+
+@set_module('numpy')
+def seterrcall(func):
+    """
+    Set the floating-point error callback function or log object.
+
+    There are two ways to capture floating-point error messages.  The first
+    is to set the error-handler to 'call', using `seterr`.  Then, set
+    the function to call using this function.
+
+    The second is to set the error-handler to 'log', using `seterr`.
+    Floating-point errors then trigger a call to the 'write' method of
+    the provided object.
+
+    Parameters
+    ----------
+    func : callable f(err, flag) or object with write method
+        Function to call upon floating-point errors ('call'-mode) or
+        object whose 'write' method is used to log such message ('log'-mode).
+
+        The call function takes two arguments. The first is a string describing
+        the type of error (such as "divide by zero", "overflow", "underflow",
+        or "invalid value"), and the second is the status flag.  The flag is a
+        byte, whose four least-significant bits indicate the type of error, one
+        of "divide", "over", "under", "invalid"::
+
+          [0 0 0 0 divide over under invalid]
+
+        In other words, ``flags = divide + 2*over + 4*under + 8*invalid``.
+
+        If an object is provided, its write method should take one argument,
+        a string.
+
+    Returns
+    -------
+    h : callable, log instance or None
+        The old error handler.
+
+    See Also
+    --------
+    seterr, geterr, geterrcall
+
+    Notes
+    -----
+
+    **Concurrency note:** see :doc:`/reference/routines.err`
+
+    Examples
+    --------
+    Callback upon error:
+
+    >>> def err_handler(type, flag):
+    ...     print("Floating point error (%s), with flag %s" % (type, flag))
+    ...
+
+    >>> import numpy as np
+
+    >>> orig_handler = np.seterrcall(err_handler)
+    >>> orig_err = np.seterr(all='call')
+
+    >>> np.array([1, 2, 3]) / 0.0
+    Floating point error (divide by zero), with flag 1
+    array([inf, inf, inf])
+
+    >>> np.seterrcall(orig_handler)
+    <function err_handler at 0x...>
+    >>> np.seterr(**orig_err)
+    {'divide': 'call', 'over': 'call', 'under': 'call', 'invalid': 'call'}
+
+    Log error message:
+
+    >>> class Log:
+    ...     def write(self, msg):
+    ...         print("LOG: %s" % msg)
+    ...
+
+    >>> log = Log()
+    >>> saved_handler = np.seterrcall(log)
+    >>> save_err = np.seterr(all='log')
+
+    >>> np.array([1, 2, 3]) / 0.0
+    LOG: Warning: divide by zero encountered in divide
+    array([inf, inf, inf])
+
+    >>> np.seterrcall(orig_handler)
+    <numpy.Log object at 0x...>
+    >>> np.seterr(**orig_err)
+    {'divide': 'log', 'over': 'log', 'under': 'log', 'invalid': 'log'}
+
+    """
+    old = _get_extobj_dict()["call"]
+    extobj = _make_extobj(call=func)
+    _extobj_contextvar.set(extobj)
+    return old
+
+
+@set_module('numpy')
+def geterrcall():
+    """
+    Return the current callback function used on floating-point errors.
+
+    When the error handling for a floating-point error (one of "divide",
+    "over", "under", or "invalid") is set to 'call' or 'log', the function
+    that is called or the log instance that is written to is returned by
+    `geterrcall`. This function or log instance has been set with
+    `seterrcall`.
+
+    Returns
+    -------
+    errobj : callable, log instance or None
+        The current error handler. If no handler was set through `seterrcall`,
+        ``None`` is returned.
+
+    See Also
+    --------
+    seterrcall, seterr, geterr
+
+    Notes
+    -----
+    For complete documentation of the types of floating-point exceptions and
+    treatment options, see `seterr`.
+
+    **Concurrency note:** see :ref:`fp_error_handling`
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.geterrcall()  # we did not yet set a handler, returns None
+
+    >>> orig_settings = np.seterr(all='call')
+    >>> def err_handler(type, flag):
+    ...     print("Floating point error (%s), with flag %s" % (type, flag))
+    >>> old_handler = np.seterrcall(err_handler)
+    >>> np.array([1, 2, 3]) / 0.0
+    Floating point error (divide by zero), with flag 1
+    array([inf, inf, inf])
+
+    >>> cur_handler = np.geterrcall()
+    >>> cur_handler is err_handler
+    True
+    >>> old_settings = np.seterr(**orig_settings)  # restore original
+    >>> old_handler = np.seterrcall(None)  # restore original
+
+    """
+    return _get_extobj_dict()["call"]
+
+
+class _unspecified:
+    pass
+
+
+_Unspecified = _unspecified()
+
+
+@set_module('numpy')
+class errstate:
+    """
+    errstate(**kwargs)
+
+    Context manager for floating-point error handling.
+
+    Using an instance of `errstate` as a context manager allows statements in
+    that context to execute with a known error handling behavior. Upon entering
+    the context the error handling is set with `seterr` and `seterrcall`, and
+    upon exiting it is reset to what it was before.
+
+    ..  versionchanged:: 1.17.0
+        `errstate` is also usable as a function decorator, saving
+        a level of indentation if an entire function is wrapped.
+
+    .. versionchanged:: 2.0
+        `errstate` is now fully thread and asyncio safe, but may not be
+        entered more than once.
+        It is not safe to decorate async functions using ``errstate``.
+
+    Parameters
+    ----------
+    kwargs : {divide, over, under, invalid}
+        Keyword arguments. The valid keywords are the possible floating-point
+        exceptions. Each keyword should have a string value that defines the
+        treatment for the particular error. Possible values are
+        {'ignore', 'warn', 'raise', 'call', 'print', 'log'}.
+
+    See Also
+    --------
+    seterr, geterr, seterrcall, geterrcall
+
+    Notes
+    -----
+    For complete documentation of the types of floating-point exceptions and
+    treatment options, see `seterr`.
+
+    **Concurrency note:** see :ref:`fp_error_handling`
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> olderr = np.seterr(all='ignore')  # Set error handling to known state.
+
+    >>> np.arange(3) / 0.
+    array([nan, inf, inf])
+    >>> with np.errstate(divide='ignore'):
+    ...     np.arange(3) / 0.
+    array([nan, inf, inf])
+
+    >>> np.sqrt(-1)
+    np.float64(nan)
+    >>> with np.errstate(invalid='raise'):
+    ...     np.sqrt(-1)
+    Traceback (most recent call last):
+      File "<stdin>", line 2, in <module>
+    FloatingPointError: invalid value encountered in sqrt
+
+    Outside the context the error handling behavior has not changed:
+
+    >>> np.geterr()
+    {'divide': 'ignore', 'over': 'ignore', 'under': 'ignore', 'invalid': 'ignore'}
+    >>> olderr = np.seterr(**olderr)  # restore original state
+
+    """
+    __slots__ = (
+        "_all",
+        "_call",
+        "_divide",
+        "_invalid",
+        "_over",
+        "_token",
+        "_under",
+    )
+
+    def __init__(self, *, call=_Unspecified,
+                 all=None, divide=None, over=None, under=None, invalid=None):
+        self._token = None
+        self._call = call
+        self._all = all
+        self._divide = divide
+        self._over = over
+        self._under = under
+        self._invalid = invalid
+
+    def __enter__(self):
+        # Note that __call__ duplicates much of this logic
+        if self._token is not None:
+            raise TypeError("Cannot enter `np.errstate` twice.")
+        if self._call is _Unspecified:
+            extobj = _make_extobj(
+                    all=self._all, divide=self._divide, over=self._over,
+                    under=self._under, invalid=self._invalid)
+        else:
+            extobj = _make_extobj(
+                    call=self._call,
+                    all=self._all, divide=self._divide, over=self._over,
+                    under=self._under, invalid=self._invalid)
+
+        self._token = _extobj_contextvar.set(extobj)
+
+    def __exit__(self, *exc_info):
+        _extobj_contextvar.reset(self._token)
+
+    def __call__(self, func):
+        # We need to customize `__call__` compared to `ContextDecorator`
+        # because we must store the token per-thread so cannot store it on
+        # the instance (we could create a new instance for this).
+        # This duplicates the code from `__enter__`.
+        @functools.wraps(func)
+        def inner(*args, **kwargs):
+            if self._call is _Unspecified:
+                extobj = _make_extobj(
+                        all=self._all, divide=self._divide, over=self._over,
+                        under=self._under, invalid=self._invalid)
+            else:
+                extobj = _make_extobj(
+                        call=self._call,
+                        all=self._all, divide=self._divide, over=self._over,
+                        under=self._under, invalid=self._invalid)
+
+            _token = _extobj_contextvar.set(extobj)
+            try:
+                # Call the original, decorated, function:
+                return func(*args, **kwargs)
+            finally:
+                _extobj_contextvar.reset(_token)
+
+        return inner

v12x/pylib/numpy/_core/arrayprint.py

@@ -0,0 +1,1788 @@
+"""Array printing function
+
+$Id: arrayprint.py,v 1.9 2005/09/13 13:58:44 teoliphant Exp $
+
+"""
+__all__ = ["array2string", "array_str", "array_repr",
+           "set_printoptions", "get_printoptions", "printoptions",
+           "format_float_positional", "format_float_scientific"]
+__docformat__ = 'restructuredtext'
+
+#
+# Written by Konrad Hinsen <hinsenk@ere.umontreal.ca>
+# last revision: 1996-3-13
+# modified by Jim Hugunin 1997-3-3 for repr's and str's (and other details)
+# and by Perry Greenfield 2000-4-1 for numarray
+# and by Travis Oliphant  2005-8-22 for numpy
+
+
+# Note: Both scalartypes.c.src and arrayprint.py implement strs for numpy
+# scalars but for different purposes. scalartypes.c.src has str/reprs for when
+# the scalar is printed on its own, while arrayprint.py has strs for when
+# scalars are printed inside an ndarray. Only the latter strs are currently
+# user-customizable.
+
+import functools
+import numbers
+import sys
+
+try:
+    from _thread import get_ident
+except ImportError:
+    from _dummy_thread import get_ident
+
+import contextlib
+import operator
+import warnings
+
+import numpy as np
+
+from . import numerictypes as _nt
+from .fromnumeric import any
+from .multiarray import (
+    array,
+    datetime_as_string,
+    datetime_data,
+    dragon4_positional,
+    dragon4_scientific,
+    ndarray,
+)
+from .numeric import asarray, concatenate, errstate
+from .numerictypes import complex128, flexible, float64, int_
+from .overrides import array_function_dispatch, set_module
+from .printoptions import format_options
+from .umath import absolute, isfinite, isinf, isnat
+
+
+def _make_options_dict(precision=None, threshold=None, edgeitems=None,
+                       linewidth=None, suppress=None, nanstr=None, infstr=None,
+                       sign=None, formatter=None, floatmode=None, legacy=None,
+                       override_repr=None):
+    """
+    Make a dictionary out of the non-None arguments, plus conversion of
+    *legacy* and sanity checks.
+    """
+
+    options = {k: v for k, v in list(locals().items()) if v is not None}
+
+    if suppress is not None:
+        options['suppress'] = bool(suppress)
+
+    modes = ['fixed', 'unique', 'maxprec', 'maxprec_equal']
+    if floatmode not in modes + [None]:
+        raise ValueError("floatmode option must be one of " +
+                         ", ".join(f'"{m}"' for m in modes))
+
+    if sign not in [None, '-', '+', ' ']:
+        raise ValueError("sign option must be one of ' ', '+', or '-'")
+
+    if legacy is False:
+        options['legacy'] = sys.maxsize
+    elif legacy == False:
+        warnings.warn(
+            f"Passing `legacy={legacy!r}` is deprecated.",
+            FutureWarning, stacklevel=3
+        )
+        options['legacy'] = sys.maxsize
+    elif legacy == '1.13':
+        options['legacy'] = 113
+    elif legacy == '1.21':
+        options['legacy'] = 121
+    elif legacy == '1.25':
+        options['legacy'] = 125
+    elif legacy == '2.1':
+        options['legacy'] = 201
+    elif legacy == '2.2':
+        options['legacy'] = 202
+    elif legacy is None:
+        pass  # OK, do nothing.
+    else:
+        warnings.warn(
+            "legacy printing option can currently only be '1.13', '1.21', "
+            "'1.25', '2.1', '2.2' or `False`", stacklevel=3)
+
+    if threshold is not None:
+        # forbid the bad threshold arg suggested by stack overflow, gh-12351
+        if not isinstance(threshold, numbers.Number):
+            raise TypeError("threshold must be numeric")
+        if np.isnan(threshold):
+            raise ValueError("threshold must be non-NAN, try "
+                             "sys.maxsize for untruncated representation")
+
+    if precision is not None:
+        # forbid the bad precision arg as suggested by issue #18254
+        try:
+            options['precision'] = operator.index(precision)
+        except TypeError as e:
+            raise TypeError('precision must be an integer') from e
+
+    return options
+
+
+@set_module('numpy')
+def set_printoptions(precision=None, threshold=None, edgeitems=None,
+                     linewidth=None, suppress=None, nanstr=None,
+                     infstr=None, formatter=None, sign=None, floatmode=None,
+                     *, legacy=None, override_repr=None):
+    """
+    Set printing options.
+
+    These options determine the way floating point numbers, arrays and
+    other NumPy objects are displayed.
+
+    Parameters
+    ----------
+    precision : int or None, optional
+        Number of digits of precision for floating point output (default 8).
+        May be None if `floatmode` is not `fixed`, to print as many digits as
+        necessary to uniquely specify the value.
+    threshold : int, optional
+        Total number of array elements which trigger summarization
+        rather than full repr (default 1000).
+        To always use the full repr without summarization, pass `sys.maxsize`.
+    edgeitems : int, optional
+        Number of array items in summary at beginning and end of
+        each dimension (default 3).
+    linewidth : int, optional
+        The number of characters per line for the purpose of inserting
+        line breaks (default 75).
+    suppress : bool, optional
+        If True, always print floating point numbers using fixed point
+        notation, in which case numbers equal to zero in the current precision
+        will print as zero.  If False, then scientific notation is used when
+        absolute value of the smallest number is < 1e-4 or the ratio of the
+        maximum absolute value to the minimum is > 1e3. The default is False.
+    nanstr : str, optional
+        String representation of floating point not-a-number (default nan).
+    infstr : str, optional
+        String representation of floating point infinity (default inf).
+    sign : string, either '-', '+', or ' ', optional
+        Controls printing of the sign of floating-point types. If '+', always
+        print the sign of positive values. If ' ', always prints a space
+        (whitespace character) in the sign position of positive values.  If
+        '-', omit the sign character of positive values. (default '-')
+
+        .. versionchanged:: 2.0
+             The sign parameter can now be an integer type, previously
+             types were floating-point types.
+
+    formatter : dict of callables, optional
+        If not None, the keys should indicate the type(s) that the respective
+        formatting function applies to.  Callables should return a string.
+        Types that are not specified (by their corresponding keys) are handled
+        by the default formatters.  Individual types for which a formatter
+        can be set are:
+
+        - 'bool'
+        - 'int'
+        - 'timedelta' : a `numpy.timedelta64`
+        - 'datetime' : a `numpy.datetime64`
+        - 'float'
+        - 'longfloat' : 128-bit floats
+        - 'complexfloat'
+        - 'longcomplexfloat' : composed of two 128-bit floats
+        - 'numpystr' : types `numpy.bytes_` and `numpy.str_`
+        - 'object' : `np.object_` arrays
+
+        Other keys that can be used to set a group of types at once are:
+
+        - 'all' : sets all types
+        - 'int_kind' : sets 'int'
+        - 'float_kind' : sets 'float' and 'longfloat'
+        - 'complex_kind' : sets 'complexfloat' and 'longcomplexfloat'
+        - 'str_kind' : sets 'numpystr'
+    floatmode : str, optional
+        Controls the interpretation of the `precision` option for
+        floating-point types. Can take the following values
+        (default maxprec_equal):
+
+        * 'fixed': Always print exactly `precision` fractional digits,
+                even if this would print more or fewer digits than
+                necessary to specify the value uniquely.
+        * 'unique': Print the minimum number of fractional digits necessary
+                to represent each value uniquely. Different elements may
+                have a different number of digits. The value of the
+                `precision` option is ignored.
+        * 'maxprec': Print at most `precision` fractional digits, but if
+                an element can be uniquely represented with fewer digits
+                only print it with that many.
+        * 'maxprec_equal': Print at most `precision` fractional digits,
+                but if every element in the array can be uniquely
+                represented with an equal number of fewer digits, use that
+                many digits for all elements.
+    legacy : string or `False`, optional
+        If set to the string ``'1.13'`` enables 1.13 legacy printing mode. This
+        approximates numpy 1.13 print output by including a space in the sign
+        position of floats and different behavior for 0d arrays. This also
+        enables 1.21 legacy printing mode (described below).
+
+        If set to the string ``'1.21'`` enables 1.21 legacy printing mode. This
+        approximates numpy 1.21 print output of complex structured dtypes
+        by not inserting spaces after commas that separate fields and after
+        colons.
+
+        If set to ``'1.25'`` approximates printing of 1.25 which mainly means
+        that numeric scalars are printed without their type information, e.g.
+        as ``3.0`` rather than ``np.float64(3.0)``.
+
+        If set to ``'2.1'``, shape information is not given when arrays are
+        summarized (i.e., multiple elements replaced with ``...``).
+
+        If set to ``'2.2'``, the transition to use scientific notation for
+        printing ``np.float16`` and ``np.float32`` types may happen later or
+        not at all for larger values.
+
+        If set to `False`, disables legacy mode.
+
+        Unrecognized strings will be ignored with a warning for forward
+        compatibility.
+
+        .. versionchanged:: 1.22.0
+        .. versionchanged:: 2.2
+
+    override_repr: callable, optional
+        If set a passed function will be used for generating arrays' repr.
+        Other options will be ignored.
+
+    See Also
+    --------
+    get_printoptions, printoptions, array2string
+
+
+    Notes
+    -----
+
+    * ``formatter`` is always reset with a call to `set_printoptions`.
+    * Use `printoptions` as a context manager to set the values temporarily.
+    * These print options apply only to NumPy ndarrays, not to scalars.
+
+    **Concurrency note:** see :ref:`text_formatting_options`
+
+    Examples
+    --------
+    Floating point precision can be set:
+
+    >>> import numpy as np
+    >>> np.set_printoptions(precision=4)
+    >>> np.array([1.123456789])
+    [1.1235]
+
+    Long arrays can be summarised:
+
+    >>> np.set_printoptions(threshold=5)
+    >>> np.arange(10)
+    array([0, 1, 2, ..., 7, 8, 9], shape=(10,))
+
+    Small results can be suppressed:
+
+    >>> eps = np.finfo(float).eps
+    >>> x = np.arange(4.)
+    >>> x**2 - (x + eps)**2
+    array([-4.9304e-32, -4.4409e-16,  0.0000e+00,  0.0000e+00])
+    >>> np.set_printoptions(suppress=True)
+    >>> x**2 - (x + eps)**2
+    array([-0., -0.,  0.,  0.])
+
+    A custom formatter can be used to display array elements as desired:
+
+    >>> np.set_printoptions(formatter={'all':lambda x: 'int: '+str(-x)})
+    >>> x = np.arange(3)
+    >>> x
+    array([int: 0, int: -1, int: -2])
+    >>> np.set_printoptions()  # formatter gets reset
+    >>> x
+    array([0, 1, 2])
+
+    To put back the default options, you can use:
+
+    >>> np.set_printoptions(edgeitems=3, infstr='inf',
+    ... linewidth=75, nanstr='nan', precision=8,
+    ... suppress=False, threshold=1000, formatter=None)
+
+    Also to temporarily override options, use `printoptions`
+    as a context manager:
+
+    >>> with np.printoptions(precision=2, suppress=True, threshold=5):
+    ...     np.linspace(0, 10, 10)
+    array([ 0.  ,  1.11,  2.22, ...,  7.78,  8.89, 10.  ], shape=(10,))
+
+    """
+    _set_printoptions(precision, threshold, edgeitems, linewidth, suppress,
+                      nanstr, infstr, formatter, sign, floatmode,
+                      legacy=legacy, override_repr=override_repr)
+
+
+def _set_printoptions(precision=None, threshold=None, edgeitems=None,
+                      linewidth=None, suppress=None, nanstr=None,
+                      infstr=None, formatter=None, sign=None, floatmode=None,
+                      *, legacy=None, override_repr=None):
+    new_opt = _make_options_dict(precision, threshold, edgeitems, linewidth,
+                                 suppress, nanstr, infstr, sign, formatter,
+                                 floatmode, legacy)
+    # formatter and override_repr are always reset
+    new_opt['formatter'] = formatter
+    new_opt['override_repr'] = override_repr
+
+    updated_opt = format_options.get() | new_opt
+    updated_opt.update(new_opt)
+
+    if updated_opt['legacy'] == 113:
+        updated_opt['sign'] = '-'
+
+    return format_options.set(updated_opt)
+
+
+@set_module('numpy')
+def get_printoptions():
+    """
+    Return the current print options.
+
+    Returns
+    -------
+    print_opts : dict
+        Dictionary of current print options with keys
+
+        - precision : int
+        - threshold : int
+        - edgeitems : int
+        - linewidth : int
+        - suppress : bool
+        - nanstr : str
+        - infstr : str
+        - sign : str
+        - formatter : dict of callables
+        - floatmode : str
+        - legacy : str or False
+
+        For a full description of these options, see `set_printoptions`.
+
+    Notes
+    -----
+    These print options apply only to NumPy ndarrays, not to scalars.
+
+    **Concurrency note:** see :ref:`text_formatting_options`
+
+    See Also
+    --------
+    set_printoptions, printoptions
+
+    Examples
+    --------
+    >>> import numpy as np
+
+    >>> np.get_printoptions()
+    {'edgeitems': 3, 'threshold': 1000, ..., 'override_repr': None}
+
+    >>> np.get_printoptions()['linewidth']
+    75
+    >>> np.set_printoptions(linewidth=100)
+    >>> np.get_printoptions()['linewidth']
+    100
+
+    """
+    opts = format_options.get().copy()
+    opts['legacy'] = {
+        113: '1.13', 121: '1.21', 125: '1.25', 201: '2.1',
+        202: '2.2', sys.maxsize: False,
+    }[opts['legacy']]
+    return opts
+
+
+def _get_legacy_print_mode():
+    """Return the legacy print mode as an int."""
+    return format_options.get()['legacy']
+
+
+@set_module('numpy')
+@contextlib.contextmanager
+def printoptions(*args, **kwargs):
+    """Context manager for setting print options.
+
+    Set print options for the scope of the `with` block, and restore the old
+    options at the end. See `set_printoptions` for the full description of
+    available options.
+
+    Examples
+    --------
+    >>> import numpy as np
+
+    >>> from numpy.testing import assert_equal
+    >>> with np.printoptions(precision=2):
+    ...     np.array([2.0]) / 3
+    array([0.67])
+
+    The `as`-clause of the `with`-statement gives the current print options:
+
+    >>> with np.printoptions(precision=2) as opts:
+    ...      assert_equal(opts, np.get_printoptions())
+
+    See Also
+    --------
+    set_printoptions, get_printoptions
+
+    Notes
+    -----
+    These print options apply only to NumPy ndarrays, not to scalars.
+
+    **Concurrency note:** see :ref:`text_formatting_options`
+
+    """
+    token = _set_printoptions(*args, **kwargs)
+
+    try:
+        yield get_printoptions()
+    finally:
+        format_options.reset(token)
+
+
+def _leading_trailing(a, edgeitems, index=()):
+    """
+    Keep only the N-D corners (leading and trailing edges) of an array.
+
+    Should be passed a base-class ndarray, since it makes no guarantees about
+    preserving subclasses.
+    """
+    axis = len(index)
+    if axis == a.ndim:
+        return a[index]
+
+    if a.shape[axis] > 2 * edgeitems:
+        return concatenate((
+            _leading_trailing(a, edgeitems, index + np.index_exp[:edgeitems]),
+            _leading_trailing(a, edgeitems, index + np.index_exp[-edgeitems:])
+        ), axis=axis)
+    else:
+        return _leading_trailing(a, edgeitems, index + np.index_exp[:])
+
+
+def _object_format(o):
+    """ Object arrays containing lists should be printed unambiguously """
+    if type(o) is list:
+        fmt = 'list({!r})'
+    else:
+        fmt = '{!r}'
+    return fmt.format(o)
+
+def repr_format(x):
+    if isinstance(x, (np.str_, np.bytes_)):
+        return repr(x.item())
+    return repr(x)
+
+def str_format(x):
+    if isinstance(x, (np.str_, np.bytes_)):
+        return str(x.item())
+    return str(x)
+
+def _get_formatdict(data, *, precision, floatmode, suppress, sign, legacy,
+                    formatter, **kwargs):
+    # note: extra arguments in kwargs are ignored
+
+    # wrapped in lambdas to avoid taking a code path
+    # with the wrong type of data
+    formatdict = {
+        'bool': lambda: BoolFormat(data),
+        'int': lambda: IntegerFormat(data, sign),
+        'float': lambda: FloatingFormat(
+            data, precision, floatmode, suppress, sign, legacy=legacy),
+        'longfloat': lambda: FloatingFormat(
+            data, precision, floatmode, suppress, sign, legacy=legacy),
+        'complexfloat': lambda: ComplexFloatingFormat(
+            data, precision, floatmode, suppress, sign, legacy=legacy),
+        'longcomplexfloat': lambda: ComplexFloatingFormat(
+            data, precision, floatmode, suppress, sign, legacy=legacy),
+        'datetime': lambda: DatetimeFormat(data, legacy=legacy),
+        'timedelta': lambda: TimedeltaFormat(data),
+        'object': lambda: _object_format,
+        'void': lambda: str_format,
+        'numpystr': lambda: repr_format}
+
+    # we need to wrap values in `formatter` in a lambda, so that the interface
+    # is the same as the above values.
+    def indirect(x):
+        return lambda: x
+
+    if formatter is not None:
+        fkeys = [k for k in formatter.keys() if formatter[k] is not None]
+        if 'all' in fkeys:
+            for key in formatdict.keys():
+                formatdict[key] = indirect(formatter['all'])
+        if 'int_kind' in fkeys:
+            for key in ['int']:
+                formatdict[key] = indirect(formatter['int_kind'])
+        if 'float_kind' in fkeys:
+            for key in ['float', 'longfloat']:
+                formatdict[key] = indirect(formatter['float_kind'])
+        if 'complex_kind' in fkeys:
+            for key in ['complexfloat', 'longcomplexfloat']:
+                formatdict[key] = indirect(formatter['complex_kind'])
+        if 'str_kind' in fkeys:
+            formatdict['numpystr'] = indirect(formatter['str_kind'])
+        for key in formatdict.keys():
+            if key in fkeys:
+                formatdict[key] = indirect(formatter[key])
+
+    return formatdict
+
+def _get_format_function(data, **options):
+    """
+    find the right formatting function for the dtype_
+    """
+    dtype_ = data.dtype
+    dtypeobj = dtype_.type
+    formatdict = _get_formatdict(data, **options)
+
+    if dtypeobj is None:
+        return formatdict["numpystr"]()
+    elif (getattr(dtypeobj, "__module__", None) != "numpy"
+            and not issubclass(dtypeobj, str)):
+        # Use `str()` as a default format for non-NumPy dtypes. This should be
+        # improved.  We use `str` assuming that `repr` is likely to duplicate
+        # information that is contained in the dtype.
+        # (Do this early, because e.g. quaddtype subclasses floating.)
+        return formatdict['void']()
+    elif issubclass(dtypeobj, _nt.bool):
+        return formatdict['bool']()
+    elif issubclass(dtypeobj, _nt.integer):
+        if issubclass(dtypeobj, _nt.timedelta64):
+            return formatdict['timedelta']()
+        else:
+            return formatdict['int']()
+    elif issubclass(dtypeobj, _nt.floating):
+        if issubclass(dtypeobj, _nt.longdouble):
+            return formatdict['longfloat']()
+        else:
+            return formatdict['float']()
+    elif issubclass(dtypeobj, _nt.complexfloating):
+        if issubclass(dtypeobj, _nt.clongdouble):
+            return formatdict['longcomplexfloat']()
+        else:
+            return formatdict['complexfloat']()
+    elif issubclass(dtypeobj, (_nt.str_, _nt.bytes_)):
+        return formatdict['numpystr']()
+    elif issubclass(dtypeobj, _nt.datetime64):
+        return formatdict['datetime']()
+    elif issubclass(dtypeobj, _nt.object_):
+        return formatdict['object']()
+    elif issubclass(dtypeobj, _nt.void):
+        if dtype_.names is not None:
+            return StructuredVoidFormat.from_data(data, **options)
+        else:
+            return formatdict['void']()
+    else:
+        return formatdict['numpystr']()
+
+
+def _recursive_guard(fillvalue='...'):
+    """
+    Like the python 3.2 reprlib.recursive_repr, but forwards *args and **kwargs
+
+    Decorates a function such that if it calls itself with the same first
+    argument, it returns `fillvalue` instead of recursing.
+
+    Largely copied from reprlib.recursive_repr
+    """
+
+    def decorating_function(f):
+        repr_running = set()
+
+        @functools.wraps(f)
+        def wrapper(self, *args, **kwargs):
+            key = id(self), get_ident()
+            if key in repr_running:
+                return fillvalue
+            repr_running.add(key)
+            try:
+                return f(self, *args, **kwargs)
+            finally:
+                repr_running.discard(key)
+
+        return wrapper
+
+    return decorating_function
+
+
+# gracefully handle recursive calls, when object arrays contain themselves
+@_recursive_guard()
+def _array2string(a, options, separator=' ', prefix=""):
+    # The formatter __init__s in _get_format_function cannot deal with
+    # subclasses yet, and we also need to avoid recursion issues in
+    # _formatArray with subclasses which return 0d arrays in place of scalars
+    data = asarray(a)
+    if a.shape == ():
+        a = data
+
+    if a.size > options['threshold']:
+        summary_insert = "..."
+        data = _leading_trailing(data, options['edgeitems'])
+    else:
+        summary_insert = ""
+
+    # find the right formatting function for the array
+    format_function = _get_format_function(data, **options)
+
+    # skip over "["
+    next_line_prefix = " "
+    # skip over array(
+    next_line_prefix += " " * len(prefix)
+
+    lst = _formatArray(a, format_function, options['linewidth'],
+                       next_line_prefix, separator, options['edgeitems'],
+                       summary_insert, options['legacy'])
+    return lst
+
+
+def _array2string_dispatcher(
+        a, max_line_width=None, precision=None,
+        suppress_small=None, separator=None, prefix=None,
+        *, formatter=None, threshold=None,
+        edgeitems=None, sign=None, floatmode=None, suffix=None,
+        legacy=None):
+    return (a,)
+
+
+@array_function_dispatch(_array2string_dispatcher, module='numpy')
+def array2string(a, max_line_width=None, precision=None,
+                 suppress_small=None, separator=' ', prefix="",
+                 *, formatter=None, threshold=None,
+                 edgeitems=None, sign=None, floatmode=None, suffix="",
+                 legacy=None):
+    """
+    Return a string representation of an array.
+
+    Parameters
+    ----------
+    a : ndarray
+        Input array.
+    max_line_width : int, optional
+        Inserts newlines if text is longer than `max_line_width`.
+        Defaults to ``numpy.get_printoptions()['linewidth']``.
+    precision : int or None, optional
+        Floating point precision.
+        Defaults to ``numpy.get_printoptions()['precision']``.
+    suppress_small : bool, optional
+        Represent numbers "very close" to zero as zero; default is False.
+        Very close is defined by precision: if the precision is 8, e.g.,
+        numbers smaller (in absolute value) than 5e-9 are represented as
+        zero.
+        Defaults to ``numpy.get_printoptions()['suppress']``.
+    separator : str, optional
+        Inserted between elements.
+    prefix : str, optional
+    suffix : str, optional
+        The length of the prefix and suffix strings are used to respectively
+        align and wrap the output. An array is typically printed as::
+
+          prefix + array2string(a) + suffix
+
+        The output is left-padded by the length of the prefix string, and
+        wrapping is forced at the column ``max_line_width - len(suffix)``.
+        It should be noted that the content of prefix and suffix strings are
+        not included in the output.
+    formatter : dict of callables, optional
+        If not None, the keys should indicate the type(s) that the respective
+        formatting function applies to.  Callables should return a string.
+        Types that are not specified (by their corresponding keys) are handled
+        by the default formatters.  Individual types for which a formatter
+        can be set are:
+
+        - 'bool'
+        - 'int'
+        - 'timedelta' : a `numpy.timedelta64`
+        - 'datetime' : a `numpy.datetime64`
+        - 'float'
+        - 'longfloat' : 128-bit floats
+        - 'complexfloat'
+        - 'longcomplexfloat' : composed of two 128-bit floats
+        - 'void' : type `numpy.void`
+        - 'numpystr' : types `numpy.bytes_` and `numpy.str_`
+
+        Other keys that can be used to set a group of types at once are:
+
+        - 'all' : sets all types
+        - 'int_kind' : sets 'int'
+        - 'float_kind' : sets 'float' and 'longfloat'
+        - 'complex_kind' : sets 'complexfloat' and 'longcomplexfloat'
+        - 'str_kind' : sets 'numpystr'
+    threshold : int, optional
+        Total number of array elements which trigger summarization
+        rather than full repr.
+        Defaults to ``numpy.get_printoptions()['threshold']``.
+    edgeitems : int, optional
+        Number of array items in summary at beginning and end of
+        each dimension.
+        Defaults to ``numpy.get_printoptions()['edgeitems']``.
+    sign : string, either '-', '+', or ' ', optional
+        Controls printing of the sign of floating-point types. If '+', always
+        print the sign of positive values. If ' ', always prints a space
+        (whitespace character) in the sign position of positive values.  If
+        '-', omit the sign character of positive values.
+        Defaults to ``numpy.get_printoptions()['sign']``.
+
+        .. versionchanged:: 2.0
+             The sign parameter can now be an integer type, previously
+             types were floating-point types.
+
+    floatmode : str, optional
+        Controls the interpretation of the `precision` option for
+        floating-point types.
+        Defaults to ``numpy.get_printoptions()['floatmode']``.
+        Can take the following values:
+
+        - 'fixed': Always print exactly `precision` fractional digits,
+          even if this would print more or fewer digits than
+          necessary to specify the value uniquely.
+        - 'unique': Print the minimum number of fractional digits necessary
+          to represent each value uniquely. Different elements may
+          have a different number of digits.  The value of the
+          `precision` option is ignored.
+        - 'maxprec': Print at most `precision` fractional digits, but if
+          an element can be uniquely represented with fewer digits
+          only print it with that many.
+        - 'maxprec_equal': Print at most `precision` fractional digits,
+          but if every element in the array can be uniquely
+          represented with an equal number of fewer digits, use that
+          many digits for all elements.
+    legacy : string or `False`, optional
+        If set to the string ``'1.13'`` enables 1.13 legacy printing mode. This
+        approximates numpy 1.13 print output by including a space in the sign
+        position of floats and different behavior for 0d arrays. If set to
+        `False`, disables legacy mode. Unrecognized strings will be ignored
+        with a warning for forward compatibility.
+
+    Returns
+    -------
+    array_str : str
+        String representation of the array.
+
+    Raises
+    ------
+    TypeError
+        if a callable in `formatter` does not return a string.
+
+    See Also
+    --------
+    array_str, array_repr, set_printoptions, get_printoptions
+
+    Notes
+    -----
+    If a formatter is specified for a certain type, the `precision` keyword is
+    ignored for that type.
+
+    This is a very flexible function; `array_repr` and `array_str` are using
+    `array2string` internally so keywords with the same name should work
+    identically in all three functions.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.array([1e-16,1,2,3])
+    >>> np.array2string(x, precision=2, separator=',',
+    ...                       suppress_small=True)
+    '[0.,1.,2.,3.]'
+
+    >>> x  = np.arange(3.)
+    >>> np.array2string(x, formatter={'float_kind':lambda x: "%.2f" % x})
+    '[0.00 1.00 2.00]'
+
+    >>> x  = np.arange(3)
+    >>> np.array2string(x, formatter={'int':lambda x: hex(x)})
+    '[0x0 0x1 0x2]'
+
+    """
+
+    overrides = _make_options_dict(precision, threshold, edgeitems,
+                                   max_line_width, suppress_small, None, None,
+                                   sign, formatter, floatmode, legacy)
+    options = format_options.get().copy()
+    options.update(overrides)
+
+    if options['legacy'] <= 113:
+        if a.shape == () and a.dtype.names is None:
+            return repr(a.item())
+
+    if options['legacy'] > 113:
+        options['linewidth'] -= len(suffix)
+
+    # treat as a null array if any of shape elements == 0
+    if a.size == 0:
+        return "[]"
+
+    return _array2string(a, options, separator, prefix)
+
+
+def _extendLine(s, line, word, line_width, next_line_prefix, legacy):
+    needs_wrap = len(line) + len(word) > line_width
+    if legacy > 113:
+        # don't wrap lines if it won't help
+        if len(line) <= len(next_line_prefix):
+            needs_wrap = False
+
+    if needs_wrap:
+        s += line.rstrip() + "\n"
+        line = next_line_prefix
+    line += word
+    return s, line
+
+
+def _extendLine_pretty(s, line, word, line_width, next_line_prefix, legacy):
+    """
+    Extends line with nicely formatted (possibly multi-line) string ``word``.
+    """
+    words = word.splitlines()
+    if len(words) == 1 or legacy <= 113:
+        return _extendLine(s, line, word, line_width, next_line_prefix, legacy)
+
+    max_word_length = max(len(word) for word in words)
+    if (len(line) + max_word_length > line_width and
+            len(line) > len(next_line_prefix)):
+        s += line.rstrip() + '\n'
+        line = next_line_prefix + words[0]
+        indent = next_line_prefix
+    else:
+        indent = len(line) * ' '
+        line += words[0]
+
+    for word in words[1::]:
+        s += line.rstrip() + '\n'
+        line = indent + word
+
+    suffix_length = max_word_length - len(words[-1])
+    line += suffix_length * ' '
+
+    return s, line
+
+def _formatArray(a, format_function, line_width, next_line_prefix,
+                 separator, edge_items, summary_insert, legacy):
+    """formatArray is designed for two modes of operation:
+
+    1. Full output
+
+    2. Summarized output
+
+    """
+    def recurser(index, hanging_indent, curr_width):
+        """
+        By using this local function, we don't need to recurse with all the
+        arguments. Since this function is not created recursively, the cost is
+        not significant
+        """
+        axis = len(index)
+        axes_left = a.ndim - axis
+
+        if axes_left == 0:
+            return format_function(a[index])
+
+        # when recursing, add a space to align with the [ added, and reduce the
+        # length of the line by 1
+        next_hanging_indent = hanging_indent + ' '
+        if legacy <= 113:
+            next_width = curr_width
+        else:
+            next_width = curr_width - len(']')
+
+        a_len = a.shape[axis]
+        show_summary = summary_insert and 2 * edge_items < a_len
+        if show_summary:
+            leading_items = edge_items
+            trailing_items = edge_items
+        else:
+            leading_items = 0
+            trailing_items = a_len
+
+        # stringify the array with the hanging indent on the first line too
+        s = ''
+
+        # last axis (rows) - wrap elements if they would not fit on one line
+        if axes_left == 1:
+            # the length up until the beginning of the separator / bracket
+            if legacy <= 113:
+                elem_width = curr_width - len(separator.rstrip())
+            else:
+                elem_width = curr_width - max(
+                    len(separator.rstrip()), len(']')
+                )
+
+            line = hanging_indent
+            for i in range(leading_items):
+                word = recurser(index + (i,), next_hanging_indent, next_width)
+                s, line = _extendLine_pretty(
+                    s, line, word, elem_width, hanging_indent, legacy)
+                line += separator
+
+            if show_summary:
+                s, line = _extendLine(
+                    s, line, summary_insert, elem_width, hanging_indent, legacy
+                )
+                if legacy <= 113:
+                    line += ", "
+                else:
+                    line += separator
+
+            for i in range(trailing_items, 1, -1):
+                word = recurser(index + (-i,), next_hanging_indent, next_width)
+                s, line = _extendLine_pretty(
+                    s, line, word, elem_width, hanging_indent, legacy)
+                line += separator
+
+            if legacy <= 113:
+                # width of the separator is not considered on 1.13
+                elem_width = curr_width
+            word = recurser(index + (-1,), next_hanging_indent, next_width)
+            s, line = _extendLine_pretty(
+                s, line, word, elem_width, hanging_indent, legacy)
+
+            s += line
+
+        # other axes - insert newlines between rows
+        else:
+            s = ''
+            line_sep = separator.rstrip() + '\n' * (axes_left - 1)
+
+            for i in range(leading_items):
+                nested = recurser(
+                    index + (i,), next_hanging_indent, next_width
+                )
+                s += hanging_indent + nested + line_sep
+
+            if show_summary:
+                if legacy <= 113:
+                    # trailing space, fixed nbr of newlines,
+                    # and fixed separator
+                    s += hanging_indent + summary_insert + ", \n"
+                else:
+                    s += hanging_indent + summary_insert + line_sep
+
+            for i in range(trailing_items, 1, -1):
+                nested = recurser(index + (-i,), next_hanging_indent,
+                                  next_width)
+                s += hanging_indent + nested + line_sep
+
+            nested = recurser(index + (-1,), next_hanging_indent, next_width)
+            s += hanging_indent + nested
+
+        # remove the hanging indent, and wrap in []
+        s = '[' + s[len(hanging_indent):] + ']'
+        return s
+
+    try:
+        # invoke the recursive part with an initial index and prefix
+        return recurser(index=(),
+                        hanging_indent=next_line_prefix,
+                        curr_width=line_width)
+    finally:
+        # recursive closures have a cyclic reference to themselves, which
+        # requires gc to collect (gh-10620). To avoid this problem, for
+        # performance, we break the cycle:
+        recurser = None
+
+def _none_or_positive_arg(x, name):
+    if x is None:
+        return -1
+    if x < 0:
+        raise ValueError(f"{name} must be >= 0")
+    return x
+
+class FloatingFormat:
+    """ Formatter for subtypes of np.floating """
+    def __init__(self, data, precision, floatmode, suppress_small, sign=False,
+                 *, legacy=None):
+        # for backcompatibility, accept bools
+        if isinstance(sign, bool):
+            sign = '+' if sign else '-'
+
+        self._legacy = legacy
+        if self._legacy <= 113:
+            # when not 0d, legacy does not support '-'
+            if data.shape != () and sign == '-':
+                sign = ' '
+
+        self.floatmode = floatmode
+        if floatmode == 'unique':
+            self.precision = None
+        else:
+            self.precision = precision
+
+        self.precision = _none_or_positive_arg(self.precision, 'precision')
+
+        self.suppress_small = suppress_small
+        self.sign = sign
+        self.exp_format = False
+        self.large_exponent = False
+        self.fillFormat(data)
+
+    def fillFormat(self, data):
+        # only the finite values are used to compute the number of digits
+        finite_vals = data[isfinite(data)]
+
+        # choose exponential mode based on the non-zero finite values:
+        abs_non_zero = absolute(finite_vals[finite_vals != 0])
+        if len(abs_non_zero) != 0:
+            max_val = np.max(abs_non_zero)
+            min_val = np.min(abs_non_zero)
+            if self._legacy <= 202:
+                exp_cutoff_max = 1.e8
+            else:
+                # consider data type while deciding the max cutoff for exp format
+                exp_cutoff_max = 10.**min(8, np.finfo(data.dtype).precision)
+            with errstate(over='ignore'):  # division can overflow
+                if max_val >= exp_cutoff_max or (not self.suppress_small and
+                        (min_val < 0.0001 or max_val / min_val > 1000.)):
+                    self.exp_format = True
+
+        # do a first pass of printing all the numbers, to determine sizes
+        if len(finite_vals) == 0:
+            self.pad_left = 0
+            self.pad_right = 0
+            self.trim = '.'
+            self.exp_size = -1
+            self.unique = True
+            self.min_digits = None
+        elif self.exp_format:
+            trim, unique = '.', True
+            if self.floatmode == 'fixed' or self._legacy <= 113:
+                trim, unique = 'k', False
+            strs = (dragon4_scientific(x, precision=self.precision,
+                               unique=unique, trim=trim, sign=self.sign == '+')
+                    for x in finite_vals)
+            frac_strs, _, exp_strs = zip(*(s.partition('e') for s in strs))
+            int_part, frac_part = zip(*(s.split('.') for s in frac_strs))
+            self.exp_size = max(len(s) for s in exp_strs) - 1
+
+            self.trim = 'k'
+            self.precision = max(len(s) for s in frac_part)
+            self.min_digits = self.precision
+            self.unique = unique
+
+            # for back-compat with np 1.13, use 2 spaces & sign and full prec
+            if self._legacy <= 113:
+                self.pad_left = 3
+            else:
+                # this should be only 1 or 2. Can be calculated from sign.
+                self.pad_left = max(len(s) for s in int_part)
+            # pad_right is only needed for nan length calculation
+            self.pad_right = self.exp_size + 2 + self.precision
+        else:
+            trim, unique = '.', True
+            if self.floatmode == 'fixed':
+                trim, unique = 'k', False
+            strs = (dragon4_positional(x, precision=self.precision,
+                                       fractional=True,
+                                       unique=unique, trim=trim,
+                                       sign=self.sign == '+')
+                    for x in finite_vals)
+            int_part, frac_part = zip(*(s.split('.') for s in strs))
+            if self._legacy <= 113:
+                self.pad_left = 1 + max(len(s.lstrip('-+')) for s in int_part)
+            else:
+                self.pad_left = max(len(s) for s in int_part)
+            self.pad_right = max(len(s) for s in frac_part)
+            self.exp_size = -1
+            self.unique = unique
+
+            if self.floatmode in ['fixed', 'maxprec_equal']:
+                self.precision = self.min_digits = self.pad_right
+                self.trim = 'k'
+            else:
+                self.trim = '.'
+                self.min_digits = 0
+
+        if self._legacy > 113:
+            # account for sign = ' ' by adding one to pad_left
+            if self.sign == ' ' and not any(np.signbit(finite_vals)):
+                self.pad_left += 1
+
+        # if there are non-finite values, may need to increase pad_left
+        if data.size != finite_vals.size:
+            neginf = self.sign != '-' or any(data[isinf(data)] < 0)
+            offset = self.pad_right + 1  # +1 for decimal pt
+            current_options = format_options.get()
+            self.pad_left = max(
+                self.pad_left, len(current_options['nanstr']) - offset,
+                len(current_options['infstr']) + neginf - offset
+            )
+
+    def __call__(self, x):
+        if not np.isfinite(x):
+            with errstate(invalid='ignore'):
+                current_options = format_options.get()
+                if np.isnan(x):
+                    sign = '+' if self.sign == '+' else ''
+                    ret = sign + current_options['nanstr']
+                else:  # isinf
+                    sign = '-' if x < 0 else '+' if self.sign == '+' else ''
+                    ret = sign + current_options['infstr']
+                return ' ' * (
+                    self.pad_left + self.pad_right + 1 - len(ret)
+                ) + ret
+
+        if self.exp_format:
+            return dragon4_scientific(x,
+                                      precision=self.precision,
+                                      min_digits=self.min_digits,
+                                      unique=self.unique,
+                                      trim=self.trim,
+                                      sign=self.sign == '+',
+                                      pad_left=self.pad_left,
+                                      exp_digits=self.exp_size)
+        else:
+            return dragon4_positional(x,
+                                      precision=self.precision,
+                                      min_digits=self.min_digits,
+                                      unique=self.unique,
+                                      fractional=True,
+                                      trim=self.trim,
+                                      sign=self.sign == '+',
+                                      pad_left=self.pad_left,
+                                      pad_right=self.pad_right)
+
+
+@set_module('numpy')
+def format_float_scientific(x, precision=None, unique=True, trim='k',
+                            sign=False, pad_left=None, exp_digits=None,
+                            min_digits=None):
+    """
+    Format a floating-point scalar as a decimal string in scientific notation.
+
+    Provides control over rounding, trimming and padding. Uses and assumes
+    IEEE unbiased rounding. Uses the "Dragon4" algorithm.
+
+    Parameters
+    ----------
+    x : python float or numpy floating scalar
+        Value to format.
+    precision : non-negative integer or None, optional
+        Maximum number of digits to print. May be None if `unique` is
+        `True`, but must be an integer if unique is `False`.
+    unique : boolean, optional
+        If `True`, use a digit-generation strategy which gives the shortest
+        representation which uniquely identifies the floating-point number from
+        other values of the same type, by judicious rounding. If `precision`
+        is given fewer digits than necessary can be printed. If `min_digits`
+        is given more can be printed, in which cases the last digit is rounded
+        with unbiased rounding.
+        If `False`, digits are generated as if printing an infinite-precision
+        value and stopping after `precision` digits, rounding the remaining
+        value with unbiased rounding
+    trim : one of 'k', '.', '0', '-', optional
+        Controls post-processing trimming of trailing digits, as follows:
+
+        * 'k' : keep trailing zeros, keep decimal point (no trimming)
+        * '.' : trim all trailing zeros, leave decimal point
+        * '0' : trim all but the zero before the decimal point. Insert the
+          zero if it is missing.
+        * '-' : trim trailing zeros and any trailing decimal point
+    sign : boolean, optional
+        Whether to show the sign for positive values.
+    pad_left : non-negative integer, optional
+        Pad the left side of the string with whitespace until at least that
+        many characters are to the left of the decimal point.
+    exp_digits : non-negative integer, optional
+        Pad the exponent with zeros until it contains at least this
+        many digits. If omitted, the exponent will be at least 2 digits.
+    min_digits : non-negative integer or None, optional
+        Minimum number of digits to print. This only has an effect for
+        `unique=True`. In that case more digits than necessary to uniquely
+        identify the value may be printed and rounded unbiased.
+
+        .. versionadded:: 1.21.0
+
+    Returns
+    -------
+    rep : string
+        The string representation of the floating point value
+
+    See Also
+    --------
+    format_float_positional
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.format_float_scientific(np.float32(np.pi))
+    '3.1415927e+00'
+    >>> s = np.float32(1.23e24)
+    >>> np.format_float_scientific(s, unique=False, precision=15)
+    '1.230000071797338e+24'
+    >>> np.format_float_scientific(s, exp_digits=4)
+    '1.23e+0024'
+    """
+    precision = _none_or_positive_arg(precision, 'precision')
+    pad_left = _none_or_positive_arg(pad_left, 'pad_left')
+    exp_digits = _none_or_positive_arg(exp_digits, 'exp_digits')
+    min_digits = _none_or_positive_arg(min_digits, 'min_digits')
+    if min_digits > 0 and precision > 0 and min_digits > precision:
+        raise ValueError("min_digits must be less than or equal to precision")
+    return dragon4_scientific(x, precision=precision, unique=unique,
+                              trim=trim, sign=sign, pad_left=pad_left,
+                              exp_digits=exp_digits, min_digits=min_digits)
+
+
+@set_module('numpy')
+def format_float_positional(x, precision=None, unique=True,
+                            fractional=True, trim='k', sign=False,
+                            pad_left=None, pad_right=None, min_digits=None):
+    """
+    Format a floating-point scalar as a decimal string in positional notation.
+
+    Provides control over rounding, trimming and padding. Uses and assumes
+    IEEE unbiased rounding. Uses the "Dragon4" algorithm.
+
+    Parameters
+    ----------
+    x : python float or numpy floating scalar
+        Value to format.
+    precision : non-negative integer or None, optional
+        Maximum number of digits to print. May be None if `unique` is
+        `True`, but must be an integer if unique is `False`.
+    unique : boolean, optional
+        If `True`, use a digit-generation strategy which gives the shortest
+        representation which uniquely identifies the floating-point number from
+        other values of the same type, by judicious rounding. If `precision`
+        is given fewer digits than necessary can be printed, or if `min_digits`
+        is given more can be printed, in which cases the last digit is rounded
+        with unbiased rounding.
+        If `False`, digits are generated as if printing an infinite-precision
+        value and stopping after `precision` digits, rounding the remaining
+        value with unbiased rounding
+    fractional : boolean, optional
+        If `True`, the cutoffs of `precision` and `min_digits` refer to the
+        total number of digits after the decimal point, including leading
+        zeros.
+        If `False`, `precision` and `min_digits` refer to the total number of
+        significant digits, before or after the decimal point, ignoring leading
+        zeros.
+    trim : one of 'k', '.', '0', '-', optional
+        Controls post-processing trimming of trailing digits, as follows:
+
+        * 'k' : keep trailing zeros, keep decimal point (no trimming)
+        * '.' : trim all trailing zeros, leave decimal point
+        * '0' : trim all but the zero before the decimal point. Insert the
+          zero if it is missing.
+        * '-' : trim trailing zeros and any trailing decimal point
+    sign : boolean, optional
+        Whether to show the sign for positive values.
+    pad_left : non-negative integer, optional
+        Pad the left side of the string with whitespace until at least that
+        many characters are to the left of the decimal point.
+    pad_right : non-negative integer, optional
+        Pad the right side of the string with whitespace until at least that
+        many characters are to the right of the decimal point.
+    min_digits : non-negative integer or None, optional
+        Minimum number of digits to print. Only has an effect if `unique=True`
+        in which case additional digits past those necessary to uniquely
+        identify the value may be printed, rounding the last additional digit.
+
+        .. versionadded:: 1.21.0
+
+    Returns
+    -------
+    rep : string
+        The string representation of the floating point value
+
+    See Also
+    --------
+    format_float_scientific
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.format_float_positional(np.float32(np.pi))
+    '3.1415927'
+    >>> np.format_float_positional(np.float16(np.pi))
+    '3.14'
+    >>> np.format_float_positional(np.float16(0.3))
+    '0.3'
+    >>> np.format_float_positional(np.float16(0.3), unique=False, precision=10)
+    '0.3000488281'
+    """
+    precision = _none_or_positive_arg(precision, 'precision')
+    pad_left = _none_or_positive_arg(pad_left, 'pad_left')
+    pad_right = _none_or_positive_arg(pad_right, 'pad_right')
+    min_digits = _none_or_positive_arg(min_digits, 'min_digits')
+    if not fractional and precision == 0:
+        raise ValueError("precision must be greater than 0 if "
+                         "fractional=False")
+    if min_digits > 0 and precision > 0 and min_digits > precision:
+        raise ValueError("min_digits must be less than or equal to precision")
+    return dragon4_positional(x, precision=precision, unique=unique,
+                              fractional=fractional, trim=trim,
+                              sign=sign, pad_left=pad_left,
+                              pad_right=pad_right, min_digits=min_digits)
+
+class IntegerFormat:
+    def __init__(self, data, sign='-'):
+        if data.size > 0:
+            data_max = np.max(data)
+            data_min = np.min(data)
+            data_max_str_len = len(str(data_max))
+            if sign == ' ' and data_min < 0:
+                sign = '-'
+            if data_max >= 0 and sign in "+ ":
+                data_max_str_len += 1
+            max_str_len = max(data_max_str_len,
+                              len(str(data_min)))
+        else:
+            max_str_len = 0
+        self.format = f'{{:{sign}{max_str_len}d}}'
+
+    def __call__(self, x):
+        return self.format.format(x)
+
+class BoolFormat:
+    def __init__(self, data, **kwargs):
+        # add an extra space so " True" and "False" have the same length and
+        # array elements align nicely when printed, except in 0d arrays
+        self.truestr = ' True' if data.shape != () else 'True'
+
+    def __call__(self, x):
+        return self.truestr if x else "False"
+
+
+class ComplexFloatingFormat:
+    """ Formatter for subtypes of np.complexfloating """
+    def __init__(self, x, precision, floatmode, suppress_small,
+                 sign=False, *, legacy=None):
+        # for backcompatibility, accept bools
+        if isinstance(sign, bool):
+            sign = '+' if sign else '-'
+
+        floatmode_real = floatmode_imag = floatmode
+        if legacy <= 113:
+            floatmode_real = 'maxprec_equal'
+            floatmode_imag = 'maxprec'
+
+        self.real_format = FloatingFormat(
+            x.real, precision, floatmode_real, suppress_small,
+            sign=sign, legacy=legacy
+        )
+        self.imag_format = FloatingFormat(
+            x.imag, precision, floatmode_imag, suppress_small,
+            sign='+', legacy=legacy
+        )
+
+    def __call__(self, x):
+        r = self.real_format(x.real)
+        i = self.imag_format(x.imag)
+
+        # add the 'j' before the terminal whitespace in i
+        sp = len(i.rstrip())
+        i = i[:sp] + 'j' + i[sp:]
+
+        return r + i
+
+
+class _TimelikeFormat:
+    def __init__(self, data):
+        non_nat = data[~isnat(data)]
+        if len(non_nat) > 0:
+            # Max str length of non-NaT elements
+            max_str_len = max(len(self._format_non_nat(np.max(non_nat))),
+                              len(self._format_non_nat(np.min(non_nat))))
+        else:
+            max_str_len = 0
+        if len(non_nat) < data.size:
+            # data contains a NaT
+            max_str_len = max(max_str_len, 5)
+        self._format = f'%{max_str_len}s'
+        self._nat = "'NaT'".rjust(max_str_len)
+
+    def _format_non_nat(self, x):
+        # override in subclass
+        raise NotImplementedError
+
+    def __call__(self, x):
+        if isnat(x):
+            return self._nat
+        else:
+            return self._format % self._format_non_nat(x)
+
+
+class DatetimeFormat(_TimelikeFormat):
+    def __init__(self, x, unit=None, timezone=None, casting='same_kind',
+                 legacy=False):
+        # Get the unit from the dtype
+        if unit is None:
+            if x.dtype.kind == 'M':
+                unit = datetime_data(x.dtype)[0]
+            else:
+                unit = 's'
+
+        if timezone is None:
+            timezone = 'naive'
+        self.timezone = timezone
+        self.unit = unit
+        self.casting = casting
+        self.legacy = legacy
+
+        # must be called after the above are configured
+        super().__init__(x)
+
+    def __call__(self, x):
+        if self.legacy <= 113:
+            return self._format_non_nat(x)
+        return super().__call__(x)
+
+    def _format_non_nat(self, x):
+        datetime_str = datetime_as_string(x,
+                                          unit=self.unit,
+                                          timezone=self.timezone,
+                                          casting=self.casting)
+        return f"'{datetime_str}'"
+
+
+class TimedeltaFormat(_TimelikeFormat):
+    def _format_non_nat(self, x):
+        return str(x.astype('i8'))
+
+
+class SubArrayFormat:
+    def __init__(self, format_function, **options):
+        self.format_function = format_function
+        self.threshold = options['threshold']
+        self.edge_items = options['edgeitems']
+
+    def __call__(self, a):
+        self.summary_insert = "..." if a.size > self.threshold else ""
+        return self.format_array(a)
+
+    def format_array(self, a):
+        if np.ndim(a) == 0:
+            return self.format_function(a)
+
+        if self.summary_insert and a.shape[0] > 2 * self.edge_items:
+            formatted = (
+                [self.format_array(a_) for a_ in a[:self.edge_items]]
+                + [self.summary_insert]
+                + [self.format_array(a_) for a_ in a[-self.edge_items:]]
+            )
+        else:
+            formatted = [self.format_array(a_) for a_ in a]
+
+        return "[" + ", ".join(formatted) + "]"
+
+
+class StructuredVoidFormat:
+    """
+    Formatter for structured np.void objects.
+
+    This does not work on structured alias types like
+    np.dtype(('i4', 'i2,i2')), as alias scalars lose their field information,
+    and the implementation relies upon np.void.__getitem__.
+    """
+    def __init__(self, format_functions):
+        self.format_functions = format_functions
+
+    @classmethod
+    def from_data(cls, data, **options):
+        """
+        This is a second way to initialize StructuredVoidFormat,
+        using the raw data as input. Added to avoid changing
+        the signature of __init__.
+        """
+        format_functions = []
+        for field_name in data.dtype.names:
+            format_function = _get_format_function(data[field_name], **options)
+            if data.dtype[field_name].shape != ():
+                format_function = SubArrayFormat(format_function, **options)
+            format_functions.append(format_function)
+        return cls(format_functions)
+
+    def __call__(self, x):
+        str_fields = [
+            format_function(field)
+            for field, format_function in zip(x, self.format_functions)
+        ]
+        if len(str_fields) == 1:
+            return f"({str_fields[0]},)"
+        else:
+            return f"({', '.join(str_fields)})"
+
+
+def _void_scalar_to_string(x, is_repr=True):
+    """
+    Implements the repr for structured-void scalars. It is called from the
+    scalartypes.c.src code, and is placed here because it uses the elementwise
+    formatters defined above.
+    """
+    options = format_options.get().copy()
+
+    if options["legacy"] <= 125:
+        return StructuredVoidFormat.from_data(array(x), **options)(x)
+
+    if options.get('formatter') is None:
+        options['formatter'] = {}
+    options['formatter'].setdefault('float_kind', str)
+    val_repr = StructuredVoidFormat.from_data(array(x), **options)(x)
+    if not is_repr:
+        return val_repr
+    cls = type(x)
+    cls_fqn = cls.__module__.replace("numpy", "np") + "." + cls.__name__
+    void_dtype = np.dtype((np.void, x.dtype))
+    return f"{cls_fqn}({val_repr}, dtype={void_dtype!s})"
+
+
+_typelessdata = [int_, float64, complex128, _nt.bool]
+
+
+def dtype_is_implied(dtype):
+    """
+    Determine if the given dtype is implied by the representation
+    of its values.
+
+    Parameters
+    ----------
+    dtype : dtype
+        Data type
+
+    Returns
+    -------
+    implied : bool
+        True if the dtype is implied by the representation of its values.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np._core.arrayprint.dtype_is_implied(int)
+    True
+    >>> np.array([1, 2, 3], int)
+    array([1, 2, 3])
+    >>> np._core.arrayprint.dtype_is_implied(np.int8)
+    False
+    >>> np.array([1, 2, 3], np.int8)
+    array([1, 2, 3], dtype=int8)
+    """
+    dtype = np.dtype(dtype)
+    if format_options.get()['legacy'] <= 113 and dtype.type == np.bool:
+        return False
+
+    # not just void types can be structured, and names are not part of the repr
+    if dtype.names is not None:
+        return False
+
+    # should care about endianness *unless size is 1* (e.g., int8, bool)
+    if not dtype.isnative:
+        return False
+
+    return dtype.type in _typelessdata
+
+
+def dtype_short_repr(dtype):
+    """
+    Convert a dtype to a short form which evaluates to the same dtype.
+
+    The intent is roughly that the following holds
+
+    >>> from numpy import *
+    >>> dt = np.int64([1, 2]).dtype
+    >>> assert eval(dtype_short_repr(dt)) == dt
+    """
+    if not type(dtype)._legacy:
+        # TODO: Custom repr for user DTypes, logic should likely move.
+        return repr(dtype)
+    if dtype.names is not None:
+        # structured dtypes give a list or tuple repr
+        return str(dtype)
+    elif issubclass(dtype.type, flexible):
+        # handle these separately so they don't give garbage like str256
+        return f"'{str(dtype)}'"
+
+    typename = dtype.name
+    if not dtype.isnative:
+        # deal with cases like dtype('<u2') that are identical to an
+        # established dtype (in this case uint16)
+        # except that they have a different endianness.
+        return f"'{str(dtype)}'"
+    # quote typenames which can't be represented as python variable names
+    if typename and not (typename[0].isalpha() and typename.isalnum()):
+        typename = repr(typename)
+    return typename
+
+
+def _array_repr_implementation(
+        arr, max_line_width=None, precision=None, suppress_small=None,
+        array2string=array2string):
+    """Internal version of array_repr() that allows overriding array2string."""
+    current_options = format_options.get()
+    override_repr = current_options["override_repr"]
+    if override_repr is not None:
+        return override_repr(arr)
+
+    if max_line_width is None:
+        max_line_width = current_options['linewidth']
+
+    if type(arr) is not ndarray:
+        class_name = type(arr).__name__
+    else:
+        class_name = "array"
+
+    prefix = class_name + "("
+    if (current_options['legacy'] <= 113 and
+            arr.shape == () and not arr.dtype.names):
+        lst = repr(arr.item())
+    else:
+        lst = array2string(arr, max_line_width, precision, suppress_small,
+                           ', ', prefix, suffix=")")
+
+    # Add dtype and shape information if these cannot be inferred from
+    # the array string.
+    extras = []
+    if ((arr.size == 0 and arr.shape != (0,))
+            or (current_options['legacy'] > 210
+            and arr.size > current_options['threshold'])):
+        extras.append(f"shape={arr.shape}")
+    if not dtype_is_implied(arr.dtype) or arr.size == 0:
+        extras.append(f"dtype={dtype_short_repr(arr.dtype)}")
+
+    if not extras:
+        return prefix + lst + ")"
+
+    arr_str = prefix + lst + ","
+    extra_str = ", ".join(extras) + ")"
+    # compute whether we should put extras on a new line: Do so if adding the
+    # extras would extend the last line past max_line_width.
+    # Note: This line gives the correct result even when rfind returns -1.
+    last_line_len = len(arr_str) - (arr_str.rfind('\n') + 1)
+    spacer = " "
+    if current_options['legacy'] <= 113:
+        if issubclass(arr.dtype.type, flexible):
+            spacer = '\n' + ' ' * len(prefix)
+    elif last_line_len + len(extra_str) + 1 > max_line_width:
+        spacer = '\n' + ' ' * len(prefix)
+
+    return arr_str + spacer + extra_str
+
+
+def _array_repr_dispatcher(
+        arr, max_line_width=None, precision=None, suppress_small=None):
+    return (arr,)
+
+
+@array_function_dispatch(_array_repr_dispatcher, module='numpy')
+def array_repr(arr, max_line_width=None, precision=None, suppress_small=None):
+    """
+    Return the string representation of an array.
+
+    Parameters
+    ----------
+    arr : ndarray
+        Input array.
+    max_line_width : int, optional
+        Inserts newlines if text is longer than `max_line_width`.
+        Defaults to ``numpy.get_printoptions()['linewidth']``.
+    precision : int, optional
+        Floating point precision.
+        Defaults to ``numpy.get_printoptions()['precision']``.
+    suppress_small : bool, optional
+        Represent numbers "very close" to zero as zero; default is False.
+        Very close is defined by precision: if the precision is 8, e.g.,
+        numbers smaller (in absolute value) than 5e-9 are represented as
+        zero.
+        Defaults to ``numpy.get_printoptions()['suppress']``.
+
+    Returns
+    -------
+    string : str
+      The string representation of an array.
+
+    See Also
+    --------
+    array_str, array2string, set_printoptions
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.array_repr(np.array([1,2]))
+    'array([1, 2])'
+    >>> np.array_repr(np.ma.array([0.]))
+    'MaskedArray([0.])'
+    >>> np.array_repr(np.array([], np.int32))
+    'array([], dtype=int32)'
+
+    >>> x = np.array([1e-6, 4e-7, 2, 3])
+    >>> np.array_repr(x, precision=6, suppress_small=True)
+    'array([0.000001,  0.      ,  2.      ,  3.      ])'
+
+    """
+    return _array_repr_implementation(
+        arr, max_line_width, precision, suppress_small)
+
+
+@_recursive_guard()
+def _guarded_repr_or_str(v):
+    if isinstance(v, bytes):
+        return repr(v)
+    return str(v)
+
+
+def _array_str_implementation(
+        a, max_line_width=None, precision=None, suppress_small=None,
+        array2string=array2string):
+    """Internal version of array_str() that allows overriding array2string."""
+    if (format_options.get()['legacy'] <= 113 and
+            a.shape == () and not a.dtype.names):
+        return str(a.item())
+
+    # the str of 0d arrays is a special case: It should appear like a scalar,
+    # so floats are not truncated by `precision`, and strings are not wrapped
+    # in quotes. So we return the str of the scalar value.
+    if a.shape == ():
+        # obtain a scalar and call str on it, avoiding problems for subclasses
+        # for which indexing with () returns a 0d instead of a scalar by using
+        # ndarray's getindex. Also guard against recursive 0d object arrays.
+        return _guarded_repr_or_str(np.ndarray.__getitem__(a, ()))
+
+    return array2string(a, max_line_width, precision, suppress_small, ' ', "")
+
+
+def _array_str_dispatcher(
+        a, max_line_width=None, precision=None, suppress_small=None):
+    return (a,)
+
+
+@array_function_dispatch(_array_str_dispatcher, module='numpy')
+def array_str(a, max_line_width=None, precision=None, suppress_small=None):
+    """
+    Return a string representation of the data in an array.
+
+    The data in the array is returned as a single string.  This function is
+    similar to `array_repr`, the difference being that `array_repr` also
+    returns information on the kind of array and its data type.
+
+    Parameters
+    ----------
+    a : ndarray
+        Input array.
+    max_line_width : int, optional
+        Inserts newlines if text is longer than `max_line_width`.
+        Defaults to ``numpy.get_printoptions()['linewidth']``.
+    precision : int, optional
+        Floating point precision.
+        Defaults to ``numpy.get_printoptions()['precision']``.
+    suppress_small : bool, optional
+        Represent numbers "very close" to zero as zero; default is False.
+        Very close is defined by precision: if the precision is 8, e.g.,
+        numbers smaller (in absolute value) than 5e-9 are represented as
+        zero.
+        Defaults to ``numpy.get_printoptions()['suppress']``.
+
+    See Also
+    --------
+    array2string, array_repr, set_printoptions
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.array_str(np.arange(3))
+    '[0 1 2]'
+
+    """
+    return _array_str_implementation(
+        a, max_line_width, precision, suppress_small)
+
+
+# needed if __array_function__ is disabled
+_array2string_impl = getattr(array2string, '__wrapped__', array2string)
+_default_array_str = functools.partial(_array_str_implementation,
+                                       array2string=_array2string_impl)
+_default_array_repr = functools.partial(_array_repr_implementation,
+                                        array2string=_array2string_impl)

v12x/pylib/numpy/_core/cversions.py

@@ -0,0 +1,13 @@
+"""Simple script to compute the api hash of the current API.
+
+The API has is defined by numpy_api_order and ufunc_api_order.
+
+"""
+from os.path import dirname
+
+from code_generators.genapi import fullapi_hash
+from code_generators.numpy_api import full_api
+
+if __name__ == '__main__':
+    curdir = dirname(__file__)
+    print(fullapi_hash(full_api))

v12x/pylib/numpy/_core/defchararray.py

@@ -0,0 +1,1429 @@
+"""
+This module contains a set of functions for vectorized string
+operations and methods.
+
+.. note::
+   The `chararray` class exists for backwards compatibility with
+   Numarray, it is not recommended for new development. Starting from numpy
+   1.4, if one needs arrays of strings, it is recommended to use arrays of
+   `dtype` `object_`, `bytes_` or `str_`, and use the free functions
+   in the `numpy.char` module for fast vectorized string operations.
+
+Some methods will only be available if the corresponding string method is
+available in your version of Python.
+
+The preferred alias for `defchararray` is `numpy.char`.
+
+"""
+import functools
+
+import numpy as np
+from numpy._core import overrides
+from numpy._core.multiarray import compare_chararrays
+from numpy._core.strings import (
+    _join as join,
+    _rsplit as rsplit,
+    _split as split,
+    _splitlines as splitlines,
+)
+from numpy._utils import set_module
+from numpy.strings import *
+from numpy.strings import (
+    multiply as strings_multiply,
+    partition as strings_partition,
+    rpartition as strings_rpartition,
+)
+
+from .numeric import array as narray, asarray as asnarray, ndarray
+from .numerictypes import bytes_, character, str_
+
+__all__ = [
+    'equal', 'not_equal', 'greater_equal', 'less_equal',
+    'greater', 'less', 'str_len', 'add', 'multiply', 'mod', 'capitalize',
+    'center', 'count', 'decode', 'encode', 'endswith', 'expandtabs',
+    'find', 'index', 'isalnum', 'isalpha', 'isdigit', 'islower', 'isspace',
+    'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'partition',
+    'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit',
+    'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase',
+    'title', 'translate', 'upper', 'zfill', 'isnumeric', 'isdecimal',
+    'array', 'asarray', 'compare_chararrays', 'chararray'
+    ]
+
+
+array_function_dispatch = functools.partial(
+    overrides.array_function_dispatch, module='numpy.char')
+
+
+def _binary_op_dispatcher(x1, x2):
+    return (x1, x2)
+
+
+@array_function_dispatch(_binary_op_dispatcher)
+def equal(x1, x2):
+    """
+    Return (x1 == x2) element-wise.
+
+    Unlike `numpy.equal`, this comparison is performed by first
+    stripping whitespace characters from the end of the string.  This
+    behavior is provided for backward-compatibility with numarray.
+
+    Parameters
+    ----------
+    x1, x2 : array_like of str or unicode
+        Input arrays of the same shape.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of bools.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> y = "aa "
+    >>> x = "aa"
+    >>> np.char.equal(x, y)
+    array(True)
+
+    See Also
+    --------
+    not_equal, greater_equal, less_equal, greater, less
+    """
+    return compare_chararrays(x1, x2, '==', True)
+
+
+@array_function_dispatch(_binary_op_dispatcher)
+def not_equal(x1, x2):
+    """
+    Return (x1 != x2) element-wise.
+
+    Unlike `numpy.not_equal`, this comparison is performed by first
+    stripping whitespace characters from the end of the string.  This
+    behavior is provided for backward-compatibility with numarray.
+
+    Parameters
+    ----------
+    x1, x2 : array_like of str or unicode
+        Input arrays of the same shape.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of bools.
+
+    See Also
+    --------
+    equal, greater_equal, less_equal, greater, less
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x1 = np.array(['a', 'b', 'c'])
+    >>> np.char.not_equal(x1, 'b')
+    array([ True, False,  True])
+
+    """
+    return compare_chararrays(x1, x2, '!=', True)
+
+
+@array_function_dispatch(_binary_op_dispatcher)
+def greater_equal(x1, x2):
+    """
+    Return (x1 >= x2) element-wise.
+
+    Unlike `numpy.greater_equal`, this comparison is performed by
+    first stripping whitespace characters from the end of the string.
+    This behavior is provided for backward-compatibility with
+    numarray.
+
+    Parameters
+    ----------
+    x1, x2 : array_like of str or unicode
+        Input arrays of the same shape.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of bools.
+
+    See Also
+    --------
+    equal, not_equal, less_equal, greater, less
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x1 = np.array(['a', 'b', 'c'])
+    >>> np.char.greater_equal(x1, 'b')
+    array([False,  True,  True])
+
+    """
+    return compare_chararrays(x1, x2, '>=', True)
+
+
+@array_function_dispatch(_binary_op_dispatcher)
+def less_equal(x1, x2):
+    """
+    Return (x1 <= x2) element-wise.
+
+    Unlike `numpy.less_equal`, this comparison is performed by first
+    stripping whitespace characters from the end of the string.  This
+    behavior is provided for backward-compatibility with numarray.
+
+    Parameters
+    ----------
+    x1, x2 : array_like of str or unicode
+        Input arrays of the same shape.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of bools.
+
+    See Also
+    --------
+    equal, not_equal, greater_equal, greater, less
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x1 = np.array(['a', 'b', 'c'])
+    >>> np.char.less_equal(x1, 'b')
+    array([ True,  True, False])
+
+    """
+    return compare_chararrays(x1, x2, '<=', True)
+
+
+@array_function_dispatch(_binary_op_dispatcher)
+def greater(x1, x2):
+    """
+    Return (x1 > x2) element-wise.
+
+    Unlike `numpy.greater`, this comparison is performed by first
+    stripping whitespace characters from the end of the string.  This
+    behavior is provided for backward-compatibility with numarray.
+
+    Parameters
+    ----------
+    x1, x2 : array_like of str or unicode
+        Input arrays of the same shape.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of bools.
+
+    See Also
+    --------
+    equal, not_equal, greater_equal, less_equal, less
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x1 = np.array(['a', 'b', 'c'])
+    >>> np.char.greater(x1, 'b')
+    array([False, False,  True])
+
+    """
+    return compare_chararrays(x1, x2, '>', True)
+
+
+@array_function_dispatch(_binary_op_dispatcher)
+def less(x1, x2):
+    """
+    Return (x1 < x2) element-wise.
+
+    Unlike `numpy.greater`, this comparison is performed by first
+    stripping whitespace characters from the end of the string.  This
+    behavior is provided for backward-compatibility with numarray.
+
+    Parameters
+    ----------
+    x1, x2 : array_like of str or unicode
+        Input arrays of the same shape.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of bools.
+
+    See Also
+    --------
+    equal, not_equal, greater_equal, less_equal, greater
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x1 = np.array(['a', 'b', 'c'])
+    >>> np.char.less(x1, 'b')
+    array([True, False, False])
+
+    """
+    return compare_chararrays(x1, x2, '<', True)
+
+
+@set_module("numpy.char")
+def multiply(a, i):
+    """
+    Return (a * i), that is string multiple concatenation,
+    element-wise.
+
+    Values in ``i`` of less than 0 are treated as 0 (which yields an
+    empty string).
+
+    Parameters
+    ----------
+    a : array_like, with ``bytes_`` or ``str_`` dtype
+
+    i : array_like, with any integer dtype
+
+    Returns
+    -------
+    out : ndarray
+        Output array of str or unicode, depending on input types
+
+    Notes
+    -----
+    This is a thin wrapper around np.strings.multiply that raises
+    `ValueError` when ``i`` is not an integer. It only
+    exists for backwards-compatibility.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(["a", "b", "c"])
+    >>> np.strings.multiply(a, 3)
+    array(['aaa', 'bbb', 'ccc'], dtype='<U3')
+    >>> i = np.array([1, 2, 3])
+    >>> np.strings.multiply(a, i)
+    array(['a', 'bb', 'ccc'], dtype='<U3')
+    >>> np.strings.multiply(np.array(['a']), i)
+    array(['a', 'aa', 'aaa'], dtype='<U3')
+    >>> a = np.array(['a', 'b', 'c', 'd', 'e', 'f']).reshape((2, 3))
+    >>> np.strings.multiply(a, 3)
+    array([['aaa', 'bbb', 'ccc'],
+           ['ddd', 'eee', 'fff']], dtype='<U3')
+    >>> np.strings.multiply(a, i)
+    array([['a', 'bb', 'ccc'],
+           ['d', 'ee', 'fff']], dtype='<U3')
+
+    """
+    try:
+        return strings_multiply(a, i)
+    except TypeError:
+        raise ValueError("Can only multiply by integers")
+
+
+@set_module("numpy.char")
+def partition(a, sep):
+    """
+    Partition each element in `a` around `sep`.
+
+    Calls :meth:`str.partition` element-wise.
+
+    For each element in `a`, split the element as the first
+    occurrence of `sep`, and return 3 strings containing the part
+    before the separator, the separator itself, and the part after
+    the separator. If the separator is not found, return 3 strings
+    containing the string itself, followed by two empty strings.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array
+    sep : {str, unicode}
+        Separator to split each string element in `a`.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types. The output array will have an extra
+        dimension with 3 elements per input element.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.array(["Numpy is nice!"])
+    >>> np.char.partition(x, " ")
+    array([['Numpy', ' ', 'is nice!']], dtype='<U8')
+
+    See Also
+    --------
+    str.partition
+
+    """
+    return np.stack(strings_partition(a, sep), axis=-1)
+
+
+@set_module("numpy.char")
+def rpartition(a, sep):
+    """
+    Partition (split) each element around the right-most separator.
+
+    Calls :meth:`str.rpartition` element-wise.
+
+    For each element in `a`, split the element as the last
+    occurrence of `sep`, and return 3 strings containing the part
+    before the separator, the separator itself, and the part after
+    the separator. If the separator is not found, return 3 strings
+    containing the string itself, followed by two empty strings.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array
+    sep : str or unicode
+        Right-most separator to split each element in array.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types. The output array will have an extra
+        dimension with 3 elements per input element.
+
+    See Also
+    --------
+    str.rpartition
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(['aAaAaA', '  aA  ', 'abBABba'])
+    >>> np.char.rpartition(a, 'A')
+    array([['aAaAa', 'A', ''],
+       ['  a', 'A', '  '],
+       ['abB', 'A', 'Bba']], dtype='<U5')
+
+    """
+    return np.stack(strings_rpartition(a, sep), axis=-1)
+
+
+@set_module("numpy.char")
+class chararray(ndarray):
+    """
+    chararray(shape, itemsize=1, unicode=False, buffer=None, offset=0,
+              strides=None, order=None)
+
+    Provides a convenient view on arrays of string and unicode values.
+
+    .. deprecated:: 2.5
+       ``chararray`` is deprecated. Use an ``ndarray`` with a string or
+       bytes dtype instead.
+
+    .. note::
+       The `chararray` class exists for backwards compatibility with
+       Numarray, it is not recommended for new development. Starting from numpy
+       1.4, if one needs arrays of strings, it is recommended to use arrays of
+       `dtype` `~numpy.object_`, `~numpy.bytes_` or `~numpy.str_`, and use
+       the free functions in the `numpy.char` module for fast vectorized
+       string operations.
+
+    Versus a NumPy array of dtype `~numpy.bytes_` or `~numpy.str_`, this
+    class adds the following functionality:
+
+    1) values automatically have whitespace removed from the end
+       when indexed
+
+    2) comparison operators automatically remove whitespace from the
+       end when comparing values
+
+    3) vectorized string operations are provided as methods
+       (e.g. `.endswith`) and infix operators (e.g. ``"+", "*", "%"``)
+
+    chararrays should be created using `numpy.char.array` or
+    `numpy.char.asarray`, rather than this constructor directly.
+
+    This constructor creates the array, using `buffer` (with `offset`
+    and `strides`) if it is not ``None``. If `buffer` is ``None``, then
+    constructs a new array with `strides` in "C order", unless both
+    ``len(shape) >= 2`` and ``order='F'``, in which case `strides`
+    is in "Fortran order".
+
+    Methods
+    -------
+    astype
+    argsort
+    copy
+    count
+    decode
+    dump
+    dumps
+    encode
+    endswith
+    expandtabs
+    fill
+    find
+    flatten
+    getfield
+    index
+    isalnum
+    isalpha
+    isdecimal
+    isdigit
+    islower
+    isnumeric
+    isspace
+    istitle
+    isupper
+    item
+    join
+    ljust
+    lower
+    lstrip
+    nonzero
+    put
+    ravel
+    repeat
+    replace
+    reshape
+    resize
+    rfind
+    rindex
+    rjust
+    rsplit
+    rstrip
+    searchsorted
+    setfield
+    setflags
+    sort
+    split
+    splitlines
+    squeeze
+    startswith
+    strip
+    swapaxes
+    swapcase
+    take
+    title
+    tofile
+    tolist
+    translate
+    transpose
+    upper
+    view
+    zfill
+
+    Parameters
+    ----------
+    shape : tuple
+        Shape of the array.
+    itemsize : int, optional
+        Length of each array element, in number of characters. Default is 1.
+    unicode : bool, optional
+        Are the array elements of type unicode (True) or string (False).
+        Default is False.
+    buffer : object exposing the buffer interface or str, optional
+        Memory address of the start of the array data.  Default is None,
+        in which case a new array is created.
+    offset : int, optional
+        Fixed stride displacement from the beginning of an axis?
+        Default is 0. Needs to be >=0.
+    strides : array_like of ints, optional
+        Strides for the array (see `~numpy.ndarray.strides` for
+        full description). Default is None.
+    order : {'C', 'F'}, optional
+        The order in which the array data is stored in memory: 'C' ->
+        "row major" order (the default), 'F' -> "column major"
+        (Fortran) order.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> charar = np.char.chararray((3, 3))
+    >>> charar[:] = 'a'
+    >>> charar
+    chararray([[b'a', b'a', b'a'],
+               [b'a', b'a', b'a'],
+               [b'a', b'a', b'a']], dtype='|S1')
+
+    >>> charar = np.char.chararray(charar.shape, itemsize=5)
+    >>> charar[:] = 'abc'
+    >>> charar
+    chararray([[b'abc', b'abc', b'abc'],
+               [b'abc', b'abc', b'abc'],
+               [b'abc', b'abc', b'abc']], dtype='|S5')
+
+    """
+    def __new__(cls, shape, itemsize=1, unicode=False, buffer=None,
+                offset=0, strides=None, order='C'):
+        if unicode:
+            dtype = str_
+        else:
+            dtype = bytes_
+
+        # force itemsize to be a Python int, since using NumPy integer
+        # types results in itemsize.itemsize being used as the size of
+        # strings in the new array.
+        itemsize = int(itemsize)
+
+        if isinstance(buffer, str):
+            # unicode objects do not have the buffer interface
+            filler = buffer
+            buffer = None
+        else:
+            filler = None
+
+        if buffer is None:
+            self = ndarray.__new__(cls, shape, (dtype, itemsize),
+                                   order=order)
+        else:
+            self = ndarray.__new__(cls, shape, (dtype, itemsize),
+                                   buffer=buffer,
+                                   offset=offset, strides=strides,
+                                   order=order)
+        if filler is not None:
+            self[...] = filler
+
+        return self
+
+    def __array_wrap__(self, arr, context=None, return_scalar=False):
+        # When calling a ufunc (and some other functions), we return a
+        # chararray if the ufunc output is a string-like array,
+        # or an ndarray otherwise
+        if arr.dtype.char in "SUbc":
+            return arr.view(type(self))
+        return arr
+
+    def __array_finalize__(self, obj):
+        # The b is a special case because it is used for reconstructing.
+        if self.dtype.char not in 'VSUbc':
+            raise ValueError("Can only create a chararray from string data.")
+
+    def __getitem__(self, obj):
+        val = ndarray.__getitem__(self, obj)
+        if isinstance(val, character):
+            return val.rstrip()
+        return val
+
+    # IMPLEMENTATION NOTE: Most of the methods of this class are
+    # direct delegations to the free functions in this module.
+    # However, those that return an array of strings should instead
+    # return a chararray, so some extra wrapping is required.
+
+    def __eq__(self, other):
+        """
+        Return (self == other) element-wise.
+
+        See Also
+        --------
+        equal
+        """
+        return equal(self, other)
+
+    def __ne__(self, other):
+        """
+        Return (self != other) element-wise.
+
+        See Also
+        --------
+        not_equal
+        """
+        return not_equal(self, other)
+
+    def __ge__(self, other):
+        """
+        Return (self >= other) element-wise.
+
+        See Also
+        --------
+        greater_equal
+        """
+        return greater_equal(self, other)
+
+    def __le__(self, other):
+        """
+        Return (self <= other) element-wise.
+
+        See Also
+        --------
+        less_equal
+        """
+        return less_equal(self, other)
+
+    def __gt__(self, other):
+        """
+        Return (self > other) element-wise.
+
+        See Also
+        --------
+        greater
+        """
+        return greater(self, other)
+
+    def __lt__(self, other):
+        """
+        Return (self < other) element-wise.
+
+        See Also
+        --------
+        less
+        """
+        return less(self, other)
+
+    def __add__(self, other):
+        """
+        Return (self + other), that is string concatenation,
+        element-wise for a pair of array_likes of str or unicode.
+
+        See Also
+        --------
+        add
+        """
+        return add(self, other)
+
+    def __radd__(self, other):
+        """
+        Return (other + self), that is string concatenation,
+        element-wise for a pair of array_likes of `bytes_` or `str_`.
+
+        See Also
+        --------
+        add
+        """
+        return add(other, self)
+
+    def __mul__(self, i):
+        """
+        Return (self * i), that is string multiple concatenation,
+        element-wise.
+
+        See Also
+        --------
+        multiply
+        """
+        return asarray(multiply(self, i))
+
+    def __rmul__(self, i):
+        """
+        Return (self * i), that is string multiple concatenation,
+        element-wise.
+
+        See Also
+        --------
+        multiply
+        """
+        return asarray(multiply(self, i))
+
+    def __mod__(self, i):
+        """
+        Return (self % i), that is pre-Python 2.6 string formatting
+        (interpolation), element-wise for a pair of array_likes of `bytes_`
+        or `str_`.
+
+        See Also
+        --------
+        mod
+        """
+        return asarray(mod(self, i))
+
+    def __rmod__(self, other):
+        return NotImplemented
+
+    def argsort(self, axis=-1, kind=None, order=None, *, stable=None, descending=None):
+        """
+        Return the indices that sort the array lexicographically.
+
+        For full documentation see `numpy.argsort`, for which this method is
+        in fact merely a "thin wrapper."
+
+        Examples
+        --------
+        >>> c = np.array(['a1b c', '1b ca', 'b ca1', 'Ca1b'], 'S5')
+        >>> c = c.view(np.char.chararray); c
+        chararray(['a1b c', '1b ca', 'b ca1', 'Ca1b'],
+              dtype='|S5')
+        >>> c[c.argsort()]
+        chararray(['1b ca', 'Ca1b', 'a1b c', 'b ca1'],
+              dtype='|S5')
+
+        """
+        return self.__array__().argsort(
+            axis, kind, order, stable=stable, descending=descending
+        )
+
+    argsort.__doc__ = ndarray.argsort.__doc__
+
+    def capitalize(self):
+        """
+        Return a copy of `self` with only the first character of each element
+        capitalized.
+
+        See Also
+        --------
+        char.capitalize
+
+        """
+        return asarray(capitalize(self))
+
+    def center(self, width, fillchar=' '):
+        """
+        Return a copy of `self` with its elements centered in a
+        string of length `width`.
+
+        See Also
+        --------
+        center
+        """
+        return asarray(center(self, width, fillchar))
+
+    def count(self, sub, start=0, end=None):
+        """
+        Returns an array with the number of non-overlapping occurrences of
+        substring `sub` in the range [`start`, `end`].
+
+        See Also
+        --------
+        char.count
+
+        """
+        return count(self, sub, start, end)
+
+    def decode(self, encoding=None, errors=None):
+        """
+        Calls ``bytes.decode`` element-wise.
+
+        See Also
+        --------
+        char.decode
+
+        """
+        return decode(self, encoding, errors)
+
+    def encode(self, encoding=None, errors=None):
+        """
+        Calls :meth:`str.encode` element-wise.
+
+        See Also
+        --------
+        char.encode
+
+        """
+        return encode(self, encoding, errors)
+
+    def endswith(self, suffix, start=0, end=None):
+        """
+        Returns a boolean array which is `True` where the string element
+        in `self` ends with `suffix`, otherwise `False`.
+
+        See Also
+        --------
+        char.endswith
+
+        """
+        return endswith(self, suffix, start, end)
+
+    def expandtabs(self, tabsize=8):
+        """
+        Return a copy of each string element where all tab characters are
+        replaced by one or more spaces.
+
+        See Also
+        --------
+        char.expandtabs
+
+        """
+        return asarray(expandtabs(self, tabsize))
+
+    def find(self, sub, start=0, end=None):
+        """
+        For each element, return the lowest index in the string where
+        substring `sub` is found.
+
+        See Also
+        --------
+        char.find
+
+        """
+        return find(self, sub, start, end)
+
+    def index(self, sub, start=0, end=None):
+        """
+        Like `find`, but raises :exc:`ValueError` when the substring is not
+        found.
+
+        See Also
+        --------
+        char.index
+
+        """
+        return index(self, sub, start, end)
+
+    def isalnum(self):
+        """
+        Returns true for each element if all characters in the string
+        are alphanumeric and there is at least one character, false
+        otherwise.
+
+        See Also
+        --------
+        char.isalnum
+
+        """
+        return isalnum(self)
+
+    def isalpha(self):
+        """
+        Returns true for each element if all characters in the string
+        are alphabetic and there is at least one character, false
+        otherwise.
+
+        See Also
+        --------
+        char.isalpha
+
+        """
+        return isalpha(self)
+
+    def isdigit(self):
+        """
+        Returns true for each element if all characters in the string are
+        digits and there is at least one character, false otherwise.
+
+        See Also
+        --------
+        char.isdigit
+
+        """
+        return isdigit(self)
+
+    def islower(self):
+        """
+        Returns true for each element if all cased characters in the
+        string are lowercase and there is at least one cased character,
+        false otherwise.
+
+        See Also
+        --------
+        char.islower
+
+        """
+        return islower(self)
+
+    def isspace(self):
+        """
+        Returns true for each element if there are only whitespace
+        characters in the string and there is at least one character,
+        false otherwise.
+
+        See Also
+        --------
+        char.isspace
+
+        """
+        return isspace(self)
+
+    def istitle(self):
+        """
+        Returns true for each element if the element is a titlecased
+        string and there is at least one character, false otherwise.
+
+        See Also
+        --------
+        char.istitle
+
+        """
+        return istitle(self)
+
+    def isupper(self):
+        """
+        Returns true for each element if all cased characters in the
+        string are uppercase and there is at least one character, false
+        otherwise.
+
+        See Also
+        --------
+        char.isupper
+
+        """
+        return isupper(self)
+
+    def join(self, seq):
+        """
+        Return a string which is the concatenation of the strings in the
+        sequence `seq`.
+
+        See Also
+        --------
+        char.join
+
+        """
+        return join(self, seq)
+
+    def ljust(self, width, fillchar=' '):
+        """
+        Return an array with the elements of `self` left-justified in a
+        string of length `width`.
+
+        See Also
+        --------
+        char.ljust
+
+        """
+        return asarray(ljust(self, width, fillchar))
+
+    def lower(self):
+        """
+        Return an array with the elements of `self` converted to
+        lowercase.
+
+        See Also
+        --------
+        char.lower
+
+        """
+        return asarray(lower(self))
+
+    def lstrip(self, chars=None):
+        """
+        For each element in `self`, return a copy with the leading characters
+        removed.
+
+        See Also
+        --------
+        char.lstrip
+
+        """
+        return lstrip(self, chars)
+
+    def partition(self, sep):
+        """
+        Partition each element in `self` around `sep`.
+
+        See Also
+        --------
+        partition
+        """
+        return asarray(partition(self, sep))
+
+    def replace(self, old, new, count=None):
+        """
+        For each element in `self`, return a copy of the string with all
+        occurrences of substring `old` replaced by `new`.
+
+        See Also
+        --------
+        char.replace
+
+        """
+        return replace(self, old, new, count if count is not None else -1)
+
+    def rfind(self, sub, start=0, end=None):
+        """
+        For each element in `self`, return the highest index in the string
+        where substring `sub` is found, such that `sub` is contained
+        within [`start`, `end`].
+
+        See Also
+        --------
+        char.rfind
+
+        """
+        return rfind(self, sub, start, end)
+
+    def rindex(self, sub, start=0, end=None):
+        """
+        Like `rfind`, but raises :exc:`ValueError` when the substring `sub` is
+        not found.
+
+        See Also
+        --------
+        char.rindex
+
+        """
+        return rindex(self, sub, start, end)
+
+    def rjust(self, width, fillchar=' '):
+        """
+        Return an array with the elements of `self`
+        right-justified in a string of length `width`.
+
+        See Also
+        --------
+        char.rjust
+
+        """
+        return asarray(rjust(self, width, fillchar))
+
+    def rpartition(self, sep):
+        """
+        Partition each element in `self` around `sep`.
+
+        See Also
+        --------
+        rpartition
+        """
+        return asarray(rpartition(self, sep))
+
+    def rsplit(self, sep=None, maxsplit=None):
+        """
+        For each element in `self`, return a list of the words in
+        the string, using `sep` as the delimiter string.
+
+        See Also
+        --------
+        char.rsplit
+
+        """
+        return rsplit(self, sep, maxsplit)
+
+    def rstrip(self, chars=None):
+        """
+        For each element in `self`, return a copy with the trailing
+        characters removed.
+
+        See Also
+        --------
+        char.rstrip
+
+        """
+        return rstrip(self, chars)
+
+    def split(self, sep=None, maxsplit=None):
+        """
+        For each element in `self`, return a list of the words in the
+        string, using `sep` as the delimiter string.
+
+        See Also
+        --------
+        char.split
+
+        """
+        return split(self, sep, maxsplit)
+
+    def splitlines(self, keepends=None):
+        """
+        For each element in `self`, return a list of the lines in the
+        element, breaking at line boundaries.
+
+        See Also
+        --------
+        char.splitlines
+
+        """
+        return splitlines(self, keepends)
+
+    def startswith(self, prefix, start=0, end=None):
+        """
+        Returns a boolean array which is `True` where the string element
+        in `self` starts with `prefix`, otherwise `False`.
+
+        See Also
+        --------
+        char.startswith
+
+        """
+        return startswith(self, prefix, start, end)
+
+    def strip(self, chars=None):
+        """
+        For each element in `self`, return a copy with the leading and
+        trailing characters removed.
+
+        See Also
+        --------
+        char.strip
+
+        """
+        return strip(self, chars)
+
+    def swapcase(self):
+        """
+        For each element in `self`, return a copy of the string with
+        uppercase characters converted to lowercase and vice versa.
+
+        See Also
+        --------
+        char.swapcase
+
+        """
+        return asarray(swapcase(self))
+
+    def title(self):
+        """
+        For each element in `self`, return a titlecased version of the
+        string: words start with uppercase characters, all remaining cased
+        characters are lowercase.
+
+        See Also
+        --------
+        char.title
+
+        """
+        return asarray(title(self))
+
+    def translate(self, table, deletechars=None):
+        """
+        For each element in `self`, return a copy of the string where
+        all characters occurring in the optional argument
+        `deletechars` are removed, and the remaining characters have
+        been mapped through the given translation table.
+
+        See Also
+        --------
+        char.translate
+
+        """
+        return asarray(translate(self, table, deletechars))
+
+    def upper(self):
+        """
+        Return an array with the elements of `self` converted to
+        uppercase.
+
+        See Also
+        --------
+        char.upper
+
+        """
+        return asarray(upper(self))
+
+    def zfill(self, width):
+        """
+        Return the numeric string left-filled with zeros in a string of
+        length `width`.
+
+        See Also
+        --------
+        char.zfill
+
+        """
+        return asarray(zfill(self, width))
+
+    def isnumeric(self):
+        """
+        For each element in `self`, return True if there are only
+        numeric characters in the element.
+
+        See Also
+        --------
+        char.isnumeric
+
+        """
+        return isnumeric(self)
+
+    def isdecimal(self):
+        """
+        For each element in `self`, return True if there are only
+        decimal characters in the element.
+
+        See Also
+        --------
+        char.isdecimal
+
+        """
+        return isdecimal(self)
+
+
+@set_module("numpy.char")
+def array(obj, itemsize=None, copy=True, unicode=None, order=None):
+    """
+    Create a `~numpy.char.chararray`.
+
+    .. deprecated:: 2.5
+       ``chararray`` is deprecated. Use an ``ndarray`` with a string or
+       bytes dtype instead.
+
+    .. note::
+       This class is provided for numarray backward-compatibility.
+       New code (not concerned with numarray compatibility) should use
+       arrays of type `bytes_` or `str_` and use the free functions
+       in :mod:`numpy.char` for fast vectorized string operations instead.
+
+    Versus a NumPy array of dtype `bytes_` or `str_`, this
+    class adds the following functionality:
+
+    1) values automatically have whitespace removed from the end
+       when indexed
+
+    2) comparison operators automatically remove whitespace from the
+       end when comparing values
+
+    3) vectorized string operations are provided as methods
+       (e.g. `chararray.endswith <numpy.char.chararray.endswith>`)
+       and infix operators (e.g. ``+, *, %``)
+
+    Parameters
+    ----------
+    obj : array of str or unicode-like
+
+    itemsize : int, optional
+        `itemsize` is the number of characters per scalar in the
+        resulting array.  If `itemsize` is None, and `obj` is an
+        object array or a Python list, the `itemsize` will be
+        automatically determined.  If `itemsize` is provided and `obj`
+        is of type str or unicode, then the `obj` string will be
+        chunked into `itemsize` pieces.
+
+    copy : bool, optional
+        If true (default), then the object is copied.  Otherwise, a copy
+        will only be made if ``__array__`` returns a copy, if obj is a
+        nested sequence, or if a copy is needed to satisfy any of the other
+        requirements (`itemsize`, unicode, `order`, etc.).
+
+    unicode : bool, optional
+        When true, the resulting `~numpy.char.chararray` can contain Unicode
+        characters, when false only 8-bit characters.  If unicode is
+        None and `obj` is one of the following:
+
+        - a `~numpy.char.chararray`,
+        - an ndarray of type :class:`str_` or :class:`bytes_`
+        - a Python :class:`str` or :class:`bytes` object,
+
+        then the unicode setting of the output array will be
+        automatically determined.
+
+    order : {'C', 'F', 'A'}, optional
+        Specify the order of the array.  If order is 'C' (default), then the
+        array will be in C-contiguous order (last-index varies the
+        fastest).  If order is 'F', then the returned array
+        will be in Fortran-contiguous order (first-index varies the
+        fastest).  If order is 'A', then the returned array may
+        be in any order (either C-, Fortran-contiguous, or even
+        discontiguous).
+
+    Examples
+    --------
+
+    >>> import numpy as np
+    >>> char_array = np.char.array(['hello', 'world', 'numpy','array'])
+    >>> char_array
+    chararray(['hello', 'world', 'numpy', 'array'], dtype='<U5')
+
+    """
+    if isinstance(obj, (bytes, str)):
+        if unicode is None:
+            if isinstance(obj, str):
+                unicode = True
+            else:
+                unicode = False
+
+        if itemsize is None:
+            itemsize = len(obj)
+        shape = len(obj) // itemsize
+
+        return chararray(shape, itemsize=itemsize, unicode=unicode,
+                         buffer=obj, order=order)
+
+    if isinstance(obj, (list, tuple)):
+        obj = asnarray(obj)
+
+    if isinstance(obj, ndarray) and issubclass(obj.dtype.type, character):
+        # If we just have a vanilla chararray, create a chararray
+        # view around it.
+        if not isinstance(obj, chararray):
+            obj = obj.view(chararray)
+
+        if itemsize is None:
+            itemsize = obj.itemsize
+            # itemsize is in 8-bit chars, so for Unicode, we need
+            # to divide by the size of a single Unicode character,
+            # which for NumPy is always 4
+            if issubclass(obj.dtype.type, str_):
+                itemsize //= 4
+
+        if unicode is None:
+            if issubclass(obj.dtype.type, str_):
+                unicode = True
+            else:
+                unicode = False
+
+        if unicode:
+            dtype = str_
+        else:
+            dtype = bytes_
+
+        if order is not None:
+            obj = asnarray(obj, order=order)
+        if (copy or
+                (itemsize != obj.itemsize) or
+                (not unicode and isinstance(obj, str_)) or
+                (unicode and isinstance(obj, bytes_))):
+            obj = obj.astype((dtype, int(itemsize)))
+        return obj
+
+    if isinstance(obj, ndarray) and issubclass(obj.dtype.type, object):
+        if itemsize is None:
+            # Since no itemsize was specified, convert the input array to
+            # a list so the ndarray constructor will automatically
+            # determine the itemsize for us.
+            obj = obj.tolist()
+            # Fall through to the default case
+
+    if unicode:
+        dtype = str_
+    else:
+        dtype = bytes_
+
+    if itemsize is None:
+        val = narray(obj, dtype=dtype, order=order, subok=True)
+    else:
+        val = narray(obj, dtype=(dtype, itemsize), order=order, subok=True)
+    return val.view(chararray)
+
+
+@set_module("numpy.char")
+def asarray(obj, itemsize=None, unicode=None, order=None):
+    """
+    Convert the input to a `~numpy.char.chararray`, copying the data only if
+    necessary.
+
+    .. deprecated:: 2.5
+       ``chararray`` is deprecated. Use an ``ndarray`` with a string or
+       bytes dtype instead.
+
+    Versus a NumPy array of dtype `bytes_` or `str_`, this
+    class adds the following functionality:
+
+    1) values automatically have whitespace removed from the end
+       when indexed
+
+    2) comparison operators automatically remove whitespace from the
+       end when comparing values
+
+    3) vectorized string operations are provided as methods
+       (e.g. `chararray.endswith <numpy.char.chararray.endswith>`)
+       and infix operators (e.g. ``+``, ``*``, ``%``)
+
+    Parameters
+    ----------
+    obj : array of str or unicode-like
+
+    itemsize : int, optional
+        `itemsize` is the number of characters per scalar in the
+        resulting array.  If `itemsize` is None, and `obj` is an
+        object array or a Python list, the `itemsize` will be
+        automatically determined.  If `itemsize` is provided and `obj`
+        is of type str or unicode, then the `obj` string will be
+        chunked into `itemsize` pieces.
+
+    unicode : bool, optional
+        When true, the resulting `~numpy.char.chararray` can contain Unicode
+        characters, when false only 8-bit characters.  If unicode is
+        None and `obj` is one of the following:
+
+        - a `~numpy.char.chararray`,
+        - an ndarray of type `str_` or `unicode_`
+        - a Python str or unicode object,
+
+        then the unicode setting of the output array will be
+        automatically determined.
+
+    order : {'C', 'F'}, optional
+        Specify the order of the array.  If order is 'C' (default), then the
+        array will be in C-contiguous order (last-index varies the
+        fastest).  If order is 'F', then the returned array
+        will be in Fortran-contiguous order (first-index varies the
+        fastest).
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.char.asarray(['hello', 'world'])
+    chararray(['hello', 'world'], dtype='<U5')
+
+    """
+    return array(obj, itemsize, copy=False,
+                 unicode=unicode, order=order)

v12x/pylib/numpy/_core/einsumfunc.py

@@ -0,0 +1,1647 @@
+"""
+Implementation of optimized einsum.
+
+"""
+import functools
+import itertools
+import operator
+
+from numpy._core.multiarray import c_einsum, matmul
+from numpy._core.numeric import asanyarray, reshape
+from numpy._core.overrides import array_function_dispatch
+from numpy._core.umath import multiply
+
+__all__ = ['einsum', 'einsum_path']
+
+# importing string for string.ascii_letters would be too slow
+# the first import before caching has been measured to take 800 µs (#23777)
+# imports begin with uppercase to mimic ASCII values to avoid sorting issues
+einsum_symbols = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+einsum_symbols_set = set(einsum_symbols)
+
+
+def _flop_count(idx_contraction, inner, num_terms, size_dictionary):
+    """
+    Computes the number of FLOPS in the contraction.
+
+    Parameters
+    ----------
+    idx_contraction : iterable
+        The indices involved in the contraction
+    inner : bool
+        Does this contraction require an inner product?
+    num_terms : int
+        The number of terms in a contraction
+    size_dictionary : dict
+        The size of each of the indices in idx_contraction
+
+    Returns
+    -------
+    flop_count : int
+        The total number of FLOPS required for the contraction.
+
+    Examples
+    --------
+
+    >>> _flop_count('abc', False, 1, {'a': 2, 'b':3, 'c':5})
+    30
+
+    >>> _flop_count('abc', True, 2, {'a': 2, 'b':3, 'c':5})
+    60
+
+    """
+
+    overall_size = _compute_size_by_dict(idx_contraction, size_dictionary)
+    op_factor = max(1, num_terms - 1)
+    if inner:
+        op_factor += 1
+
+    return overall_size * op_factor
+
+def _compute_size_by_dict(indices, idx_dict):
+    """
+    Computes the product of the elements in indices based on the dictionary
+    idx_dict.
+
+    Parameters
+    ----------
+    indices : iterable
+        Indices to base the product on.
+    idx_dict : dictionary
+        Dictionary of index sizes
+
+    Returns
+    -------
+    ret : int
+        The resulting product.
+
+    Examples
+    --------
+    >>> _compute_size_by_dict('abbc', {'a': 2, 'b':3, 'c':5})
+    90
+
+    """
+    ret = 1
+    for i in indices:
+        ret *= idx_dict[i]
+    return ret
+
+
+def _find_contraction(positions, input_sets, output_set):
+    """
+    Finds the contraction for a given set of input and output sets.
+
+    Parameters
+    ----------
+    positions : iterable
+        Integer positions of terms used in the contraction.
+    input_sets : list
+        List of sets that represent the lhs side of the einsum subscript
+    output_set : set
+        Set that represents the rhs side of the overall einsum subscript
+
+    Returns
+    -------
+    new_result : set
+        The indices of the resulting contraction
+    remaining : list
+        List of sets that have not been contracted, the new set is appended to
+        the end of this list
+    idx_removed : set
+        Indices removed from the entire contraction
+    idx_contraction : set
+        The indices used in the current contraction
+
+    Examples
+    --------
+
+    # A simple dot product test case
+    >>> pos = (0, 1)
+    >>> isets = [set('ab'), set('bc')]
+    >>> oset = set('ac')
+    >>> _find_contraction(pos, isets, oset)
+    ({'a', 'c'}, [{'a', 'c'}], {'b'}, {'a', 'b', 'c'})
+
+    # A more complex case with additional terms in the contraction
+    >>> pos = (0, 2)
+    >>> isets = [set('abd'), set('ac'), set('bdc')]
+    >>> oset = set('ac')
+    >>> _find_contraction(pos, isets, oset)
+    ({'a', 'c'}, [{'a', 'c'}, {'a', 'c'}], {'b', 'd'}, {'a', 'b', 'c', 'd'})
+    """
+
+    idx_contract = set()
+    idx_remain = output_set.copy()
+    remaining = []
+    for ind, value in enumerate(input_sets):
+        if ind in positions:
+            idx_contract |= value
+        else:
+            remaining.append(value)
+            idx_remain |= value
+
+    new_result = idx_remain & idx_contract
+    idx_removed = (idx_contract - new_result)
+    remaining.append(new_result)
+
+    return (new_result, remaining, idx_removed, idx_contract)
+
+
+def _optimal_path(input_sets, output_set, idx_dict, memory_limit):
+    """
+    Computes all possible pair contractions, sieves the results based
+    on ``memory_limit`` and returns the lowest cost path. This algorithm
+    scales factorial with respect to the elements in the list ``input_sets``.
+
+    Parameters
+    ----------
+    input_sets : list
+        List of sets that represent the lhs side of the einsum subscript
+    output_set : set
+        Set that represents the rhs side of the overall einsum subscript
+    idx_dict : dictionary
+        Dictionary of index sizes
+    memory_limit : int
+        The maximum number of elements in a temporary array
+
+    Returns
+    -------
+    path : list
+        The optimal contraction order within the memory limit constraint.
+
+    Examples
+    --------
+    >>> isets = [set('abd'), set('ac'), set('bdc')]
+    >>> oset = set()
+    >>> idx_sizes = {'a': 1, 'b':2, 'c':3, 'd':4}
+    >>> _optimal_path(isets, oset, idx_sizes, 5000)
+    [(0, 2), (0, 1)]
+    """
+
+    full_results = [(0, [], input_sets)]
+    for iteration in range(len(input_sets) - 1):
+        iter_results = []
+
+        # Compute all unique pairs
+        for curr in full_results:
+            cost, positions, remaining = curr
+            for con in itertools.combinations(
+                range(len(input_sets) - iteration), 2
+            ):
+
+                # Find the contraction
+                cont = _find_contraction(con, remaining, output_set)
+                new_result, new_input_sets, idx_removed, idx_contract = cont
+
+                # Sieve the results based on memory_limit
+                new_size = _compute_size_by_dict(new_result, idx_dict)
+                if new_size > memory_limit:
+                    continue
+
+                # Build (total_cost, positions, indices_remaining)
+                total_cost = cost + _flop_count(
+                    idx_contract, idx_removed, len(con), idx_dict
+                )
+                new_pos = positions + [con]
+                iter_results.append((total_cost, new_pos, new_input_sets))
+
+        # Update combinatorial list, if we did not find anything return best
+        # path + remaining contractions
+        if iter_results:
+            full_results = iter_results
+        else:
+            path = min(full_results, key=lambda x: x[0])[1]
+            path += [tuple(range(len(input_sets) - iteration))]
+            return path
+
+    # If we have not found anything return single einsum contraction
+    if len(full_results) == 0:
+        return [tuple(range(len(input_sets)))]
+
+    path = min(full_results, key=lambda x: x[0])[1]
+    return path
+
+def _parse_possible_contraction(
+        positions, input_sets, output_set, idx_dict,
+        memory_limit, path_cost, naive_cost
+    ):
+    """Compute the cost (removed size + flops) and resultant indices for
+    performing the contraction specified by ``positions``.
+
+    Parameters
+    ----------
+    positions : tuple of int
+        The locations of the proposed tensors to contract.
+    input_sets : list of sets
+        The indices found on each tensors.
+    output_set : set
+        The output indices of the expression.
+    idx_dict : dict
+        Mapping of each index to its size.
+    memory_limit : int
+        The total allowed size for an intermediary tensor.
+    path_cost : int
+        The contraction cost so far.
+    naive_cost : int
+        The cost of the unoptimized expression.
+
+    Returns
+    -------
+    cost : (int, int)
+        A tuple containing the size of any indices removed, and the flop cost.
+    positions : tuple of int
+        The locations of the proposed tensors to contract.
+    new_input_sets : list of sets
+        The resulting new list of indices if this proposed contraction
+        is performed.
+
+    """
+
+    # Find the contraction
+    contract = _find_contraction(positions, input_sets, output_set)
+    idx_result, new_input_sets, idx_removed, idx_contract = contract
+
+    # Sieve the results based on memory_limit
+    new_size = _compute_size_by_dict(idx_result, idx_dict)
+    if new_size > memory_limit:
+        return None
+
+    # Build sort tuple
+    old_sizes = (
+        _compute_size_by_dict(input_sets[p], idx_dict) for p in positions
+    )
+    removed_size = sum(old_sizes) - new_size
+
+    # NB: removed_size used to be just the size of any removed indices i.e.:
+    #     helpers.compute_size_by_dict(idx_removed, idx_dict)
+    cost = _flop_count(idx_contract, idx_removed, len(positions), idx_dict)
+    sort = (-removed_size, cost)
+
+    # Sieve based on total cost as well
+    if (path_cost + cost) > naive_cost:
+        return None
+
+    # Add contraction to possible choices
+    return [sort, positions, new_input_sets]
+
+
+def _update_other_results(results, best):
+    """Update the positions and provisional input_sets of ``results``
+    based on performing the contraction result ``best``. Remove any
+    involving the tensors contracted.
+
+    Parameters
+    ----------
+    results : list
+        List of contraction results produced by
+        ``_parse_possible_contraction``.
+    best : list
+        The best contraction of ``results`` i.e. the one that
+        will be performed.
+
+    Returns
+    -------
+    mod_results : list
+        The list of modified results, updated with outcome of
+        ``best`` contraction.
+    """
+
+    best_con = best[1]
+    bx, by = best_con
+    mod_results = []
+
+    for cost, (x, y), con_sets in results:
+
+        # Ignore results involving tensors just contracted
+        if x in best_con or y in best_con:
+            continue
+
+        # Update the input_sets
+        del con_sets[by - int(by > x) - int(by > y)]
+        del con_sets[bx - int(bx > x) - int(bx > y)]
+        con_sets.insert(-1, best[2][-1])
+
+        # Update the position indices
+        mod_con = x - int(x > bx) - int(x > by), y - int(y > bx) - int(y > by)
+        mod_results.append((cost, mod_con, con_sets))
+
+    return mod_results
+
+def _greedy_path(input_sets, output_set, idx_dict, memory_limit):
+    """
+    Finds the path by contracting the best pair until the input list is
+    exhausted. The best pair is found by minimizing the tuple
+    ``(-prod(indices_removed), cost)``.  What this amounts to is prioritizing
+    matrix multiplication or inner product operations, then Hadamard like
+    operations, and finally outer operations. Outer products are limited by
+    ``memory_limit``. This algorithm scales cubically with respect to the
+    number of elements in the list ``input_sets``.
+
+    Parameters
+    ----------
+    input_sets : list
+        List of sets that represent the lhs side of the einsum subscript
+    output_set : set
+        Set that represents the rhs side of the overall einsum subscript
+    idx_dict : dictionary
+        Dictionary of index sizes
+    memory_limit : int
+        The maximum number of elements in a temporary array
+
+    Returns
+    -------
+    path : list
+        The greedy contraction order within the memory limit constraint.
+
+    Examples
+    --------
+    >>> isets = [set('abd'), set('ac'), set('bdc')]
+    >>> oset = set()
+    >>> idx_sizes = {'a': 1, 'b':2, 'c':3, 'd':4}
+    >>> _greedy_path(isets, oset, idx_sizes, 5000)
+    [(0, 2), (0, 1)]
+    """
+
+    # Handle trivial cases that leaked through
+    if len(input_sets) == 1:
+        return [(0,)]
+    elif len(input_sets) == 2:
+        return [(0, 1)]
+
+    # Build up a naive cost
+    contract = _find_contraction(
+        range(len(input_sets)), input_sets, output_set
+    )
+    idx_result, new_input_sets, idx_removed, idx_contract = contract
+    naive_cost = _flop_count(
+        idx_contract, idx_removed, len(input_sets), idx_dict
+    )
+
+    # Initially iterate over all pairs
+    comb_iter = itertools.combinations(range(len(input_sets)), 2)
+    known_contractions = []
+
+    path_cost = 0
+    path = []
+
+    for iteration in range(len(input_sets) - 1):
+
+        # Iterate over all pairs on the first step, only previously
+        # found pairs on subsequent steps
+        for positions in comb_iter:
+
+            # Always initially ignore outer products
+            if input_sets[positions[0]].isdisjoint(input_sets[positions[1]]):
+                continue
+
+            result = _parse_possible_contraction(
+                positions, input_sets, output_set, idx_dict,
+                memory_limit, path_cost, naive_cost
+            )
+            if result is not None:
+                known_contractions.append(result)
+
+        # If we do not have an inner contraction, rescan pairs
+        # including outer products
+        if len(known_contractions) == 0:
+
+            # Then check the outer products
+            for positions in itertools.combinations(
+                range(len(input_sets)), 2
+            ):
+                result = _parse_possible_contraction(
+                    positions, input_sets, output_set, idx_dict,
+                    memory_limit, path_cost, naive_cost
+                )
+                if result is not None:
+                    known_contractions.append(result)
+
+            # If we still did not find any remaining contractions,
+            # default back to einsum like behavior
+            if len(known_contractions) == 0:
+                path.append(tuple(range(len(input_sets))))
+                break
+
+        # Sort based on first index
+        best = min(known_contractions, key=lambda x: x[0])
+
+        # Now propagate as many unused contractions as possible
+        # to the next iteration
+        known_contractions = _update_other_results(known_contractions, best)
+
+        # Next iteration only compute contractions with the new tensor
+        # All other contractions have been accounted for
+        input_sets = best[2]
+        new_tensor_pos = len(input_sets) - 1
+        comb_iter = ((i, new_tensor_pos) for i in range(new_tensor_pos))
+
+        # Update path and total cost
+        path.append(best[1])
+        path_cost += best[0][1]
+
+    return path
+
+
+def _parse_einsum_input(operands):
+    """
+    A reproduction of einsum c side einsum parsing in python.
+
+    Returns
+    -------
+    input_strings : str
+        Parsed input strings
+    output_string : str
+        Parsed output string
+    operands : list of array_like
+        The operands to use in the numpy contraction
+
+    Examples
+    --------
+    The operand list is simplified to reduce printing:
+
+    >>> np.random.seed(123)
+    >>> a = np.random.rand(4, 4)
+    >>> b = np.random.rand(4, 4, 4)
+    >>> _parse_einsum_input(('...a,...a->...', a, b))
+    ('za,xza', 'xz', [a, b]) # may vary
+
+    >>> _parse_einsum_input((a, [Ellipsis, 0], b, [Ellipsis, 0]))
+    ('za,xza', 'xz', [a, b]) # may vary
+    """
+
+    if len(operands) == 0:
+        raise ValueError("No input operands")
+
+    if isinstance(operands[0], str):
+        subscripts = operands[0].replace(" ", "")
+        operands = [asanyarray(v) for v in operands[1:]]
+
+        # Ensure all characters are valid
+        for s in subscripts:
+            if s in '.,->':
+                continue
+            if s not in einsum_symbols:
+                raise ValueError(f"Character {s} is not a valid symbol.")
+
+    else:
+        tmp_operands = list(operands)
+        operand_list = []
+        subscript_list = []
+        for p in range(len(operands) // 2):
+            operand_list.append(tmp_operands.pop(0))
+            subscript_list.append(tmp_operands.pop(0))
+
+        output_list = tmp_operands[-1] if len(tmp_operands) else None
+        operands = [asanyarray(v) for v in operand_list]
+        subscripts = ""
+        last = len(subscript_list) - 1
+        for num, sub in enumerate(subscript_list):
+            for s in sub:
+                if s is Ellipsis:
+                    subscripts += "..."
+                else:
+                    try:
+                        s = operator.index(s)
+                    except TypeError as e:
+                        raise TypeError(
+                            "For this input type lists must contain "
+                            "either int or Ellipsis"
+                        ) from e
+                    subscripts += einsum_symbols[s]
+            if num != last:
+                subscripts += ","
+
+        if output_list is not None:
+            subscripts += "->"
+            for s in output_list:
+                if s is Ellipsis:
+                    subscripts += "..."
+                else:
+                    try:
+                        s = operator.index(s)
+                    except TypeError as e:
+                        raise TypeError(
+                            "For this input type lists must contain "
+                            "either int or Ellipsis"
+                        ) from e
+                    subscripts += einsum_symbols[s]
+    # Check for proper "->"
+    if ("-" in subscripts) or (">" in subscripts):
+        invalid = (subscripts.count("-") > 1) or (subscripts.count(">") > 1)
+        if invalid or (subscripts.count("->") != 1):
+            raise ValueError("Subscripts can only contain one '->'.")
+
+    # Parse ellipses
+    if "." in subscripts:
+        used = subscripts.replace(".", "").replace(",", "").replace("->", "")
+        unused = list(einsum_symbols_set - set(used))
+        ellipse_inds = "".join(unused)
+        longest = 0
+
+        if "->" in subscripts:
+            input_tmp, output_sub = subscripts.split("->")
+            split_subscripts = input_tmp.split(",")
+            out_sub = True
+        else:
+            split_subscripts = subscripts.split(',')
+            out_sub = False
+
+        for num, sub in enumerate(split_subscripts):
+            if "." in sub:
+                if (sub.count(".") != 3) or (sub.count("...") != 1):
+                    raise ValueError("Invalid Ellipses.")
+
+                # Take into account numerical values
+                if operands[num].shape == ():
+                    ellipse_count = 0
+                else:
+                    ellipse_count = max(operands[num].ndim, 1)
+                    ellipse_count -= (len(sub) - 3)
+
+                if ellipse_count > longest:
+                    longest = ellipse_count
+
+                if ellipse_count < 0:
+                    raise ValueError("Ellipses lengths do not match.")
+                elif ellipse_count == 0:
+                    split_subscripts[num] = sub.replace('...', '')
+                else:
+                    rep_inds = ellipse_inds[-ellipse_count:]
+                    split_subscripts[num] = sub.replace('...', rep_inds)
+
+        subscripts = ",".join(split_subscripts)
+        if longest == 0:
+            out_ellipse = ""
+        else:
+            out_ellipse = ellipse_inds[-longest:]
+
+        if out_sub:
+            subscripts += "->" + output_sub.replace("...", out_ellipse)
+        else:
+            # Special care for outputless ellipses
+            output_subscript = ""
+            tmp_subscripts = subscripts.replace(",", "")
+            for s in sorted(set(tmp_subscripts)):
+                if s not in (einsum_symbols):
+                    raise ValueError(f"Character {s} is not a valid symbol.")
+                if tmp_subscripts.count(s) == 1:
+                    output_subscript += s
+            normal_inds = ''.join(sorted(set(output_subscript) -
+                                         set(out_ellipse)))
+
+            subscripts += "->" + out_ellipse + normal_inds
+
+    # Build output string if does not exist
+    if "->" in subscripts:
+        input_subscripts, output_subscript = subscripts.split("->")
+    else:
+        input_subscripts = subscripts
+        # Build output subscripts
+        tmp_subscripts = subscripts.replace(",", "")
+        output_subscript = ""
+        for s in sorted(set(tmp_subscripts)):
+            if s not in einsum_symbols:
+                raise ValueError(f"Character {s} is not a valid symbol.")
+            if tmp_subscripts.count(s) == 1:
+                output_subscript += s
+
+    # Make sure output subscripts are in the input
+    for char in output_subscript:
+        if output_subscript.count(char) != 1:
+            raise ValueError(f"Output character {char} appeared more than once in "
+                             "the output.")
+        if char not in input_subscripts:
+            raise ValueError(f"Output character {char} did not appear in the input")
+
+    # Make sure number operands is equivalent to the number of terms
+    if len(input_subscripts.split(',')) != len(operands):
+        raise ValueError("Number of einsum subscripts must be equal to the "
+                         "number of operands.")
+
+    return (input_subscripts, output_subscript, operands)
+
+
+def _einsum_path_dispatcher(*operands, optimize=None, einsum_call=None):
+    # NOTE: technically, we should only dispatch on array-like arguments, not
+    # subscripts (given as strings). But separating operands into
+    # arrays/subscripts is a little tricky/slow (given einsum's two supported
+    # signatures), so as a practical shortcut we dispatch on everything.
+    # Strings will be ignored for dispatching since they don't define
+    # __array_function__.
+    return operands
+
+
+@array_function_dispatch(_einsum_path_dispatcher, module='numpy')
+def einsum_path(*operands, optimize='greedy', einsum_call=False):
+    """
+    einsum_path(subscripts, *operands, optimize='greedy')
+
+    Evaluates the lowest cost contraction order for an einsum expression by
+    considering the creation of intermediate arrays.
+
+    Parameters
+    ----------
+    subscripts : str
+        Specifies the subscripts for summation.
+    *operands : list of array_like
+        These are the arrays for the operation.
+    optimize : {bool, list, tuple, 'greedy', 'optimal'}
+        Choose the type of path. If a tuple is provided, the second argument is
+        assumed to be the maximum intermediate size created. If only a single
+        argument is provided the largest input or output array size is used
+        as a maximum intermediate size.
+
+        * if a list is given that starts with ``einsum_path``, uses this as the
+          contraction path
+        * if False no optimization is taken
+        * if True defaults to the 'greedy' algorithm
+        * 'optimal' An algorithm that combinatorially explores all possible
+          ways of contracting the listed tensors and chooses the least costly
+          path. Scales exponentially with the number of terms in the
+          contraction.
+        * 'greedy' An algorithm that chooses the best pair contraction
+          at each step. Effectively, this algorithm searches the largest inner,
+          Hadamard, and then outer products at each step. Scales cubically with
+          the number of terms in the contraction. Equivalent to the 'optimal'
+          path for most contractions.
+
+        Default is 'greedy'.
+
+    Returns
+    -------
+    path : list of tuples
+        A list representation of the einsum path.
+    string_repr : str
+        A printable representation of the einsum path.
+
+    Notes
+    -----
+    The resulting path indicates which terms of the input contraction should be
+    contracted first, the result of this contraction is then appended to the
+    end of the contraction list. This list can then be iterated over until all
+    intermediate contractions are complete.
+
+    See Also
+    --------
+    einsum, linalg.multi_dot
+
+    Examples
+    --------
+
+    We can begin with a chain dot example. In this case, it is optimal to
+    contract the ``b`` and ``c`` tensors first as represented by the first
+    element of the path ``(1, 2)``. The resulting tensor is added to the end
+    of the contraction and the remaining contraction ``(0, 1)`` is then
+    completed.
+
+    >>> np.random.seed(123)
+    >>> a = np.random.rand(2, 2)
+    >>> b = np.random.rand(2, 5)
+    >>> c = np.random.rand(5, 2)
+    >>> path_info = np.einsum_path('ij,jk,kl->il', a, b, c, optimize='greedy')
+    >>> print(path_info[0])
+    ['einsum_path', (1, 2), (0, 1)]
+    >>> print(path_info[1])
+      Complete contraction:  ij,jk,kl->il # may vary
+             Naive scaling:  4
+         Optimized scaling:  3
+          Naive FLOP count:  1.600e+02
+      Optimized FLOP count:  5.600e+01
+       Theoretical speedup:  2.857
+      Largest intermediate:  4.000e+00 elements
+    -------------------------------------------------------------------------
+    scaling                  current                                remaining
+    -------------------------------------------------------------------------
+       3                   kl,jk->jl                                ij,jl->il
+       3                   jl,ij->il                                   il->il
+
+
+    A more complex index transformation example.
+
+    >>> I = np.random.rand(10, 10, 10, 10)
+    >>> C = np.random.rand(10, 10)
+    >>> path_info = np.einsum_path('ea,fb,abcd,gc,hd->efgh', C, C, I, C, C,
+    ...                            optimize='greedy')
+
+    >>> print(path_info[0])
+    ['einsum_path', (0, 2), (0, 3), (0, 2), (0, 1)]
+    >>> print(path_info[1])
+      Complete contraction:  ea,fb,abcd,gc,hd->efgh # may vary
+             Naive scaling:  8
+         Optimized scaling:  5
+          Naive FLOP count:  8.000e+08
+      Optimized FLOP count:  8.000e+05
+       Theoretical speedup:  1000.000
+      Largest intermediate:  1.000e+04 elements
+    --------------------------------------------------------------------------
+    scaling                  current                                remaining
+    --------------------------------------------------------------------------
+       5               abcd,ea->bcde                      fb,gc,hd,bcde->efgh
+       5               bcde,fb->cdef                         gc,hd,cdef->efgh
+       5               cdef,gc->defg                            hd,defg->efgh
+       5               defg,hd->efgh                               efgh->efgh
+    """
+
+    # Figure out what the path really is
+    path_type = optimize
+    if path_type is True:
+        path_type = 'greedy'
+    if path_type is None:
+        path_type = False
+
+    explicit_einsum_path = False
+    memory_limit = None
+
+    # No optimization or a named path algorithm
+    if (path_type is False) or isinstance(path_type, str):
+        pass
+
+    # Given an explicit path
+    elif len(path_type) and (path_type[0] == 'einsum_path'):
+        explicit_einsum_path = True
+
+    # Path tuple with memory limit
+    elif ((len(path_type) == 2) and isinstance(path_type[0], str) and
+            isinstance(path_type[1], (int, float))):
+        memory_limit = int(path_type[1])
+        path_type = path_type[0]
+
+    else:
+        raise TypeError(f"Did not understand the path: {str(path_type)}")
+
+    # Hidden option, only einsum should call this
+    einsum_call_arg = einsum_call
+
+    # Python side parsing
+    input_subscripts, output_subscript, operands = (
+        _parse_einsum_input(operands)
+    )
+
+    # Build a few useful list and sets
+    input_list = input_subscripts.split(',')
+    num_inputs = len(input_list)
+    input_sets = [set(x) for x in input_list]
+    output_set = set(output_subscript)
+    indices = set(input_subscripts.replace(',', ''))
+    num_indices = len(indices)
+
+    # Get length of each unique dimension and ensure all dimensions are correct
+    dimension_dict = {}
+    for tnum, term in enumerate(input_list):
+        sh = operands[tnum].shape
+        if len(sh) != len(term):
+            raise ValueError(f"Einstein sum subscript {input_subscripts[tnum]} "
+                             "does not contain the "
+                             f"correct number of indices for operand {tnum}.")
+        for cnum, char in enumerate(term):
+            dim = sh[cnum]
+
+            if char in dimension_dict.keys():
+                # For broadcasting cases we always want the largest dim size
+                if dimension_dict[char] == 1:
+                    dimension_dict[char] = dim
+                elif dim not in (1, dimension_dict[char]):
+                    raise ValueError(f"Size of label {char!r} for "
+                                     f"operand {tnum} ({dimension_dict[char]}) "
+                                     f"does not match previous terms ({dim}).")
+            else:
+                dimension_dict[char] = dim
+
+    # Compute size of each input array plus the output array
+    size_list = [_compute_size_by_dict(term, dimension_dict)
+                 for term in input_list + [output_subscript]]
+    max_size = max(size_list)
+
+    if memory_limit is None:
+        memory_arg = max_size
+    else:
+        memory_arg = memory_limit
+
+    # Compute the path
+    if explicit_einsum_path:
+        path = path_type[1:]
+    elif (
+        (path_type is False)
+        or (num_inputs in [1, 2])
+        or (indices == output_set)
+    ):
+        # Nothing to be optimized, leave it to einsum
+        path = [tuple(range(num_inputs))]
+    elif path_type == "greedy":
+        path = _greedy_path(
+            input_sets, output_set, dimension_dict, memory_arg
+        )
+    elif path_type == "optimal":
+        path = _optimal_path(
+            input_sets, output_set, dimension_dict, memory_arg
+        )
+    else:
+        raise KeyError("Path name %s not found", path_type)
+
+    cost_list, scale_list, size_list, contraction_list = [], [], [], []
+
+    # Build contraction tuple (positions, gemm, einsum_str, remaining)
+    for cnum, contract_inds in enumerate(path):
+        # Make sure we remove inds from right to left
+        contract_inds = tuple(sorted(contract_inds, reverse=True))
+
+        contract = _find_contraction(contract_inds, input_sets, output_set)
+        out_inds, input_sets, idx_removed, idx_contract = contract
+
+        if not einsum_call_arg:
+            # these are only needed for printing info
+            cost = _flop_count(
+                idx_contract, idx_removed, len(contract_inds), dimension_dict
+            )
+            cost_list.append(cost)
+            scale_list.append(len(idx_contract))
+            size_list.append(_compute_size_by_dict(out_inds, dimension_dict))
+
+        tmp_inputs = []
+        for x in contract_inds:
+            tmp_inputs.append(input_list.pop(x))
+
+        # Last contraction
+        if (cnum - len(path)) == -1:
+            idx_result = output_subscript
+        else:
+            sort_result = [(dimension_dict[ind], ind) for ind in out_inds]
+            idx_result = "".join([x[1] for x in sorted(sort_result)])
+
+        input_list.append(idx_result)
+        einsum_str = ",".join(tmp_inputs) + "->" + idx_result
+
+        contraction = (contract_inds, einsum_str, input_list[:])
+        contraction_list.append(contraction)
+
+    if len(input_list) != 1:
+        # Explicit "einsum_path" is usually trusted, but we detect this kind of
+        # mistake in order to prevent from returning an intermediate value.
+        raise RuntimeError(
+            f"Invalid einsum_path is specified: {len(input_list) - 1} more "
+            "operands has to be contracted.")
+
+    if einsum_call_arg:
+        return (operands, contraction_list)
+
+    # Return the path along with a nice string representation
+    overall_contraction = input_subscripts + "->" + output_subscript
+
+    # Compute naive cost
+    # This isn't quite right, need to look into exactly how einsum does this
+    inner_product = (
+        sum(len(set(x)) for x in input_subscripts.split(',')) - num_indices
+    ) > 0
+    naive_cost = _flop_count(
+        indices, inner_product, num_inputs, dimension_dict
+    )
+
+    opt_cost = sum(cost_list) + 1
+    speedup = naive_cost / opt_cost
+    max_i = max(size_list)
+
+    path_print = f"  Complete contraction:  {overall_contraction}\n"
+    path_print += f"         Naive scaling:  {num_indices}\n"
+    path_print += f"     Optimized scaling:  {max(scale_list)}\n"
+    path_print += f"      Naive FLOP count:  {naive_cost:.3e}\n"
+    path_print += f"  Optimized FLOP count:  {opt_cost:.3e}\n"
+    path_print += f"   Theoretical speedup:  {speedup:3.3f}\n"
+    path_print += f"  Largest intermediate:  {max_i:.3e} elements\n"
+    path_print += "-" * 74 + "\n"
+    path_print += f"{'scaling':>6} {'current':>24} {'remaining':>40}\n"
+    path_print += "-" * 74
+
+    for n, contraction in enumerate(contraction_list):
+        _, einsum_str, remaining = contraction
+        remaining_str = ",".join(remaining) + "->" + output_subscript
+        path_print += f"\n{scale_list[n]:4d}    {einsum_str:>24} {remaining_str:>40}"
+
+    path = ['einsum_path'] + path
+    return (path, path_print)
+
+
+def _parse_eq_to_pure_multiplication(a_term, shape_a, b_term, shape_b, out):
+    """If there are no contracted indices, then we can directly transpose and
+    insert singleton dimensions into ``a`` and ``b`` such that (broadcast)
+    elementwise multiplication performs the einsum.
+
+    No need to cache this as it is within the cached
+    ``_parse_eq_to_batch_matmul``.
+
+    """
+    desired_a = ""
+    desired_b = ""
+    new_shape_a = []
+    new_shape_b = []
+    for ix in out:
+        if ix in a_term:
+            desired_a += ix
+            new_shape_a.append(shape_a[a_term.index(ix)])
+        else:
+            new_shape_a.append(1)
+        if ix in b_term:
+            desired_b += ix
+            new_shape_b.append(shape_b[b_term.index(ix)])
+        else:
+            new_shape_b.append(1)
+
+    if desired_a != a_term:
+        eq_a = f"{a_term}->{desired_a}"
+    else:
+        eq_a = None
+    if desired_b != b_term:
+        eq_b = f"{b_term}->{desired_b}"
+    else:
+        eq_b = None
+
+    return (
+        eq_a,
+        eq_b,
+        new_shape_a,
+        new_shape_b,
+        None,  # new_shape_ab, not needed since not fusing
+        None,  # perm_ab, not needed as we transpose a and b first
+        True,  # pure_multiplication=True
+    )
+
+
+@functools.lru_cache(2**12)
+def _parse_eq_to_batch_matmul(eq, shape_a, shape_b):
+    """Cached parsing of a two term einsum equation into the necessary
+    sequence of arguments for contraction via batched matrix multiplication.
+    The steps we need to specify are:
+
+        1. Remove repeated and trivial indices from the left and right terms,
+           and transpose them, done as a single einsum.
+        2. Fuse the remaining indices so we have two 3D tensors.
+        3. Perform the batched matrix multiplication.
+        4. Unfuse the output to get the desired final index order.
+
+    """
+    lhs, out = eq.split("->")
+    a_term, b_term = lhs.split(",")
+
+    if len(a_term) != len(shape_a):
+        raise ValueError(f"Term '{a_term}' does not match shape {shape_a}.")
+    if len(b_term) != len(shape_b):
+        raise ValueError(f"Term '{b_term}' does not match shape {shape_b}.")
+
+    sizes = {}
+    singletons = set()
+
+    # parse left term to unique indices with size > 1
+    left = {}
+    for ix, d in zip(a_term, shape_a):
+        if d == 1:
+            # everything (including broadcasting) works nicely if simply ignore
+            # such dimensions, but we do need to track if they appear in output
+            # and thus should be reintroduced later
+            singletons.add(ix)
+            continue
+        if sizes.setdefault(ix, d) != d:
+            # set and check size
+            raise ValueError(
+                f"Index {ix} has mismatched sizes {sizes[ix]} and {d}."
+            )
+        left[ix] = True
+
+    # parse right term to unique indices with size > 1
+    right = {}
+    for ix, d in zip(b_term, shape_b):
+        # broadcast indices (size 1 on one input and size != 1
+        # on the other) should not be treated as singletons
+        if d == 1:
+            if ix not in left:
+                singletons.add(ix)
+            continue
+        singletons.discard(ix)
+
+        if sizes.setdefault(ix, d) != d:
+            # set and check size
+            raise ValueError(
+                f"Index {ix} has mismatched sizes {sizes[ix]} and {d}."
+            )
+        right[ix] = True
+
+    # now we classify the unique size > 1 indices only
+    bat_inds = []  # appears on A, B, O
+    con_inds = []  # appears on A, B, .
+    a_keep = []  # appears on A, ., O
+    b_keep = []  # appears on ., B, O
+    # other indices (appearing on A or B only) will
+    # be summed or traced out prior to the matmul
+    for ix in left:
+        if right.pop(ix, False):
+            if ix in out:
+                bat_inds.append(ix)
+            else:
+                con_inds.append(ix)
+        elif ix in out:
+            a_keep.append(ix)
+    # now only indices unique to right remain
+    for ix in right:
+        if ix in out:
+            b_keep.append(ix)
+
+    if not con_inds:
+        # contraction is pure multiplication, prepare inputs differently
+        return _parse_eq_to_pure_multiplication(
+            a_term, shape_a, b_term, shape_b, out
+        )
+
+    # only need the size one indices that appear in the output
+    singletons = [ix for ix in out if ix in singletons]
+
+    # take diagonal, remove any trivial axes and transpose left
+    desired_a = "".join((*bat_inds, *a_keep, *con_inds))
+    if a_term != desired_a:
+        eq_a = f"{a_term}->{desired_a}"
+    else:
+        eq_a = None
+
+    # take diagonal, remove any trivial axes and transpose right
+    desired_b = "".join((*bat_inds, *con_inds, *b_keep))
+    if b_term != desired_b:
+        eq_b = f"{b_term}->{desired_b}"
+    else:
+        eq_b = None
+
+    # then we want to reshape
+    if bat_inds:
+        lgroups = (bat_inds, a_keep, con_inds)
+        rgroups = (bat_inds, con_inds, b_keep)
+        ogroups = (bat_inds, a_keep, b_keep)
+    else:
+        # avoid size 1 batch dimension if no batch indices
+        lgroups = (a_keep, con_inds)
+        rgroups = (con_inds, b_keep)
+        ogroups = (a_keep, b_keep)
+
+    if any(len(group) != 1 for group in lgroups):
+        # need to fuse 'kept' and contracted indices
+        # (though could allow batch indices to be broadcast)
+        new_shape_a = tuple(
+            functools.reduce(operator.mul, (sizes[ix] for ix in ix_group), 1)
+            for ix_group in lgroups
+        )
+    else:
+        new_shape_a = None
+
+    if any(len(group) != 1 for group in rgroups):
+        # need to fuse 'kept' and contracted indices
+        # (though could allow batch indices to be broadcast)
+        new_shape_b = tuple(
+            functools.reduce(operator.mul, (sizes[ix] for ix in ix_group), 1)
+            for ix_group in rgroups
+        )
+    else:
+        new_shape_b = None
+
+    if any(len(group) != 1 for group in ogroups) or singletons:
+        new_shape_ab = (1,) * len(singletons) + tuple(
+            sizes[ix] for ix_group in ogroups for ix in ix_group
+        )
+    else:
+        new_shape_ab = None
+
+    # then we might need to permute the matmul produced output:
+    out_produced = "".join((*singletons, *bat_inds, *a_keep, *b_keep))
+    if out_produced != out:
+        perm_ab = tuple(out_produced.index(ix) for ix in out)
+    else:
+        perm_ab = None
+
+    return (
+        eq_a,
+        eq_b,
+        new_shape_a,
+        new_shape_b,
+        new_shape_ab,
+        perm_ab,
+        False,  # pure_multiplication=False
+    )
+
+
+@functools.lru_cache(maxsize=64)
+def _parse_output_order(order, a_is_fcontig, b_is_fcontig):
+    order = order.upper()
+    if order == "K":
+        return None
+    elif order in "CF":
+        return order
+    elif order == "A":
+        if a_is_fcontig and b_is_fcontig:
+            return "F"
+        else:
+            return "C"
+    else:
+        raise ValueError(
+            "ValueError: order must be one of "
+            f"'C', 'F', 'A', or 'K' (got '{order}')"
+        )
+
+
+def bmm_einsum(eq, a, b, out=None, **kwargs):
+    """Perform arbitrary pairwise einsums using only ``matmul``, or
+    ``multiply`` if no contracted indices are involved (plus maybe single term
+    ``einsum`` to prepare the terms individually). The logic for each is cached
+    based on the equation and array shape, and each step is only performed if
+    necessary.
+
+    Parameters
+    ----------
+    eq : str
+        The einsum equation.
+    a : array_like
+        The first array to contract.
+    b : array_like
+        The second array to contract.
+
+    Returns
+    -------
+    array_like
+
+    Notes
+    -----
+    A fuller description of this algorithm, and original source for this
+    implementation, can be found at https://github.com/jcmgray/einsum_bmm.
+    """
+    (
+        eq_a,
+        eq_b,
+        new_shape_a,
+        new_shape_b,
+        new_shape_ab,
+        perm_ab,
+        pure_multiplication,
+    ) = _parse_eq_to_batch_matmul(eq, a.shape, b.shape)
+
+    # n.b. one could special case various cases to call c_einsum directly here
+
+    # need to handle `order` a little manually, since we do transpose
+    # operations before and potentially after the ufunc calls
+    output_order = _parse_output_order(
+        kwargs.pop("order", "K"), a.flags.f_contiguous, b.flags.f_contiguous
+    )
+
+    # prepare left
+    if eq_a is not None:
+        # diagonals, sums, and transpose
+        a = c_einsum(eq_a, a)
+    if new_shape_a is not None:
+        a = reshape(a, new_shape_a)
+
+    # prepare right
+    if eq_b is not None:
+        # diagonals, sums, and transpose
+        b = c_einsum(eq_b, b)
+    if new_shape_b is not None:
+        b = reshape(b, new_shape_b)
+
+    if pure_multiplication:
+        # no contracted indices
+        if output_order is not None:
+            kwargs["order"] = output_order
+
+        # do the 'contraction' via multiplication!
+        return multiply(a, b, out=out, **kwargs)
+
+    # can only supply out here if no other reshaping / transposing
+    matmul_out_compatible = (new_shape_ab is None) and (perm_ab is None)
+    if matmul_out_compatible:
+        kwargs["out"] = out
+
+    # do the contraction!
+    ab = matmul(a, b, **kwargs)
+
+    # prepare the output
+    if new_shape_ab is not None:
+        ab = reshape(ab, new_shape_ab)
+    if perm_ab is not None:
+        ab = ab.transpose(perm_ab)
+
+    if (out is not None) and (not matmul_out_compatible):
+        # handle case where out is specified, but we also needed
+        # to reshape / transpose ``ab`` after the matmul
+        out[...] = ab
+        ab = out
+    elif output_order is not None:
+        ab = asanyarray(ab, order=output_order)
+
+    return ab
+
+
+def _einsum_dispatcher(*operands, out=None, optimize=None, **kwargs):
+    # Arguably we dispatch on more arguments than we really should; see note in
+    # _einsum_path_dispatcher for why.
+    yield from operands
+    yield out
+
+
+# Rewrite einsum to handle different cases
+@array_function_dispatch(_einsum_dispatcher, module='numpy')
+def einsum(*operands, out=None, optimize=False, **kwargs):
+    """
+    einsum(subscripts, *operands, out=None, dtype=None, order='K',
+           casting='safe', optimize=False)
+
+    Evaluates the Einstein summation convention on the operands.
+
+    Using the Einstein summation convention, many common multi-dimensional,
+    linear algebraic array operations can be represented in a simple fashion.
+    In *implicit* mode `einsum` computes these values.
+
+    In *explicit* mode, `einsum` provides further flexibility to compute
+    other array operations that might not be considered classical Einstein
+    summation operations, by disabling, or forcing summation over specified
+    subscript labels.
+
+    See the notes and examples for clarification.
+
+    Parameters
+    ----------
+    subscripts : str
+        Specifies the subscripts for summation as comma separated list of
+        subscript labels. An implicit (classical Einstein summation)
+        calculation is performed unless the explicit indicator '->' is
+        included as well as subscript labels of the precise output form.
+    operands : list of array_like
+        These are the arrays for the operation.
+    out : ndarray, optional
+        If provided, the calculation is done into this array.
+    dtype : {data-type, None}, optional
+        If provided, forces the calculation to use the data type specified.
+        Note that you may have to also give a more liberal `casting`
+        parameter to allow the conversions. Default is None.
+    order : {'C', 'F', 'A', 'K'}, optional
+        Controls the memory layout of the output. 'C' means it should
+        be C contiguous. 'F' means it should be Fortran contiguous,
+        'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise.
+        'K' means it should be as close to the layout as the inputs as
+        is possible, including arbitrarily permuted axes.
+        Default is 'K'.
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+        Controls what kind of data casting may occur.  Setting this to
+        'unsafe' is not recommended, as it can adversely affect accumulations.
+
+        * 'no' means the data types should not be cast at all.
+        * 'equiv' means only byte-order changes are allowed.
+        * 'safe' means only casts which can preserve values are allowed.
+        * 'same_kind' means only safe casts or casts within a kind,
+          like float64 to float32, are allowed.
+        * 'unsafe' means any data conversions may be done.
+
+        Default is 'safe'.
+    optimize : {False, True, 'greedy', 'optimal'}, optional
+        Controls if intermediate optimization should occur. No optimization
+        will occur if False and True will default to the 'greedy' algorithm.
+        Also accepts an explicit contraction list from the ``np.einsum_path``
+        function. See ``np.einsum_path`` for more details. Defaults to False.
+
+    Returns
+    -------
+    output : ndarray
+        The calculation based on the Einstein summation convention.
+
+    See Also
+    --------
+    einsum_path, dot, inner, outer, tensordot, linalg.multi_dot
+    einsum:
+        Similar verbose interface is provided by the
+        `einops <https://github.com/arogozhnikov/einops>`_ package to cover
+        additional operations: transpose, reshape/flatten, repeat/tile,
+        squeeze/unsqueeze and reductions.
+        The `opt_einsum <https://optimized-einsum.readthedocs.io/en/stable/>`_
+        optimizes contraction order for einsum-like expressions
+        in backend-agnostic manner.
+
+    Notes
+    -----
+    The Einstein summation convention can be used to compute
+    many multi-dimensional, linear algebraic array operations. `einsum`
+    provides a succinct way of representing these.
+
+    A non-exhaustive list of these operations,
+    which can be computed by `einsum`, is shown below along with examples:
+
+    * Trace of an array, :py:func:`numpy.trace`.
+    * Return a diagonal, :py:func:`numpy.diag`.
+    * Array axis summations, :py:func:`numpy.sum`.
+    * Transpositions and permutations, :py:func:`numpy.transpose`.
+    * Matrix multiplication and dot product, :py:func:`numpy.matmul`
+        :py:func:`numpy.dot`.
+    * Vector inner and outer products, :py:func:`numpy.inner`
+        :py:func:`numpy.outer`.
+    * Broadcasting, element-wise and scalar multiplication,
+        :py:func:`numpy.multiply`.
+    * Tensor contractions, :py:func:`numpy.tensordot`.
+    * Chained array operations, in efficient calculation order,
+        :py:func:`numpy.einsum_path`.
+
+    The subscripts string is a comma-separated list of subscript labels,
+    where each label refers to a dimension of the corresponding operand.
+    Whenever a label is repeated it is summed, so ``np.einsum('i,i', a, b)``
+    is equivalent to :py:func:`np.inner(a,b) <numpy.inner>`. If a label
+    appears only once, it is not summed, so ``np.einsum('i', a)``
+    produces a view of ``a`` with no changes. A further example
+    ``np.einsum('ij,jk', a, b)`` describes traditional matrix multiplication
+    and is equivalent to :py:func:`np.matmul(a,b) <numpy.matmul>`.
+    Repeated subscript labels in one operand take the diagonal.
+    For example, ``np.einsum('ii', a)`` is equivalent to
+    :py:func:`np.trace(a) <numpy.trace>`.
+
+    In *implicit mode*, the chosen subscripts are important
+    since the axes of the output are reordered alphabetically.  This
+    means that ``np.einsum('ij', a)`` doesn't affect a 2D array, while
+    ``np.einsum('ji', a)`` takes its transpose. Additionally,
+    ``np.einsum('ij,jk', a, b)`` returns a matrix multiplication, while,
+    ``np.einsum('ij,jh', a, b)`` returns the transpose of the
+    multiplication since subscript 'h' precedes subscript 'i'.
+
+    In *explicit mode* the output can be directly controlled by
+    specifying output subscript labels.  This requires the
+    identifier '->' as well as the list of output subscript labels.
+    This feature increases the flexibility of the function since
+    summing can be disabled or forced when required. The call
+    ``np.einsum('i->', a)`` is like :py:func:`np.sum(a) <numpy.sum>`
+    if ``a`` is a 1-D array, and ``np.einsum('ii->i', a)``
+    is like :py:func:`np.diag(a) <numpy.diag>` if ``a`` is a square 2-D array.
+    The difference is that `einsum` does not allow broadcasting by default.
+    Additionally ``np.einsum('ij,jh->ih', a, b)`` directly specifies the
+    order of the output subscript labels and therefore returns matrix
+    multiplication, unlike the example above in implicit mode.
+
+    To enable and control broadcasting, use an ellipsis.  Default
+    NumPy-style broadcasting is done by adding an ellipsis
+    to the left of each term, like ``np.einsum('...ii->...i', a)``.
+    ``np.einsum('...i->...', a)`` is like
+    :py:func:`np.sum(a, axis=-1) <numpy.sum>` for array ``a`` of any shape.
+    To take the trace along the first and last axes,
+    you can do ``np.einsum('i...i', a)``, or to do a matrix-matrix
+    product with the left-most indices instead of rightmost, one can do
+    ``np.einsum('ij...,jk...->ik...', a, b)``.
+
+    When there is only one operand, no axes are summed, and no output
+    parameter is provided, a view into the operand is returned instead
+    of a new array.  Thus, taking the diagonal as ``np.einsum('ii->i', a)``
+    produces a view (changed in version 1.10.0).
+
+    `einsum` also provides an alternative way to provide the subscripts and
+    operands as ``einsum(op0, sublist0, op1, sublist1, ..., [sublistout])``.
+    If the output shape is not provided in this format `einsum` will be
+    calculated in implicit mode, otherwise it will be performed explicitly.
+    The examples below have corresponding `einsum` calls with the two
+    parameter methods.
+
+    Views returned from einsum are now writeable whenever the input array
+    is writeable. For example, ``np.einsum('ijk...->kji...', a)`` will now
+    have the same effect as :py:func:`np.swapaxes(a, 0, 2) <numpy.swapaxes>`
+    and ``np.einsum('ii->i', a)`` will return a writeable view of the diagonal
+    of a 2D array.
+
+    Added the ``optimize`` argument which will optimize the contraction order
+    of an einsum expression. For a contraction with three or more operands
+    this can greatly increase the computational efficiency at the cost of
+    a larger memory footprint during computation.
+
+    Typically a 'greedy' algorithm is applied which empirical tests have shown
+    returns the optimal path in the majority of cases. In some cases 'optimal'
+    will return the superlative path through a more expensive, exhaustive
+    search. For iterative calculations it may be advisable to calculate
+    the optimal path once and reuse that path by supplying it as an argument.
+    An example is given below.
+
+    See :py:func:`numpy.einsum_path` for more details.
+
+    Examples
+    --------
+    >>> a = np.arange(25).reshape(5,5)
+    >>> b = np.arange(5)
+    >>> c = np.arange(6).reshape(2,3)
+
+    Trace of a matrix:
+
+    >>> np.einsum('ii', a)
+    60
+    >>> np.einsum(a, [0,0])
+    60
+    >>> np.trace(a)
+    60
+
+    Extract the diagonal (requires explicit form):
+
+    >>> np.einsum('ii->i', a)
+    array([ 0,  6, 12, 18, 24])
+    >>> np.einsum(a, [0,0], [0])
+    array([ 0,  6, 12, 18, 24])
+    >>> np.diag(a)
+    array([ 0,  6, 12, 18, 24])
+
+    Sum over an axis (requires explicit form):
+
+    >>> np.einsum('ij->i', a)
+    array([ 10,  35,  60,  85, 110])
+    >>> np.einsum(a, [0,1], [0])
+    array([ 10,  35,  60,  85, 110])
+    >>> np.sum(a, axis=1)
+    array([ 10,  35,  60,  85, 110])
+
+    For higher dimensional arrays summing a single axis can be done
+    with ellipsis:
+
+    >>> np.einsum('...j->...', a)
+    array([ 10,  35,  60,  85, 110])
+    >>> np.einsum(a, [Ellipsis,1], [Ellipsis])
+    array([ 10,  35,  60,  85, 110])
+
+    Compute a matrix transpose, or reorder any number of axes:
+
+    >>> np.einsum('ji', c)
+    array([[0, 3],
+           [1, 4],
+           [2, 5]])
+    >>> np.einsum('ij->ji', c)
+    array([[0, 3],
+           [1, 4],
+           [2, 5]])
+    >>> np.einsum(c, [1,0])
+    array([[0, 3],
+           [1, 4],
+           [2, 5]])
+    >>> np.transpose(c)
+    array([[0, 3],
+           [1, 4],
+           [2, 5]])
+
+    Vector inner products:
+
+    >>> np.einsum('i,i', b, b)
+    30
+    >>> np.einsum(b, [0], b, [0])
+    30
+    >>> np.inner(b,b)
+    30
+
+    Matrix vector multiplication:
+
+    >>> np.einsum('ij,j', a, b)
+    array([ 30,  80, 130, 180, 230])
+    >>> np.einsum(a, [0,1], b, [1])
+    array([ 30,  80, 130, 180, 230])
+    >>> np.dot(a, b)
+    array([ 30,  80, 130, 180, 230])
+    >>> np.einsum('...j,j', a, b)
+    array([ 30,  80, 130, 180, 230])
+
+    Broadcasting and scalar multiplication:
+
+    >>> np.einsum('..., ...', 3, c)
+    array([[ 0,  3,  6],
+           [ 9, 12, 15]])
+    >>> np.einsum(',ij', 3, c)
+    array([[ 0,  3,  6],
+           [ 9, 12, 15]])
+    >>> np.einsum(3, [Ellipsis], c, [Ellipsis])
+    array([[ 0,  3,  6],
+           [ 9, 12, 15]])
+    >>> np.multiply(3, c)
+    array([[ 0,  3,  6],
+           [ 9, 12, 15]])
+
+    Vector outer product:
+
+    >>> np.einsum('i,j', np.arange(2)+1, b)
+    array([[0, 1, 2, 3, 4],
+           [0, 2, 4, 6, 8]])
+    >>> np.einsum(np.arange(2)+1, [0], b, [1])
+    array([[0, 1, 2, 3, 4],
+           [0, 2, 4, 6, 8]])
+    >>> np.outer(np.arange(2)+1, b)
+    array([[0, 1, 2, 3, 4],
+           [0, 2, 4, 6, 8]])
+
+    Tensor contraction:
+
+    >>> a = np.arange(60.).reshape(3,4,5)
+    >>> b = np.arange(24.).reshape(4,3,2)
+    >>> np.einsum('ijk,jil->kl', a, b)
+    array([[4400., 4730.],
+           [4532., 4874.],
+           [4664., 5018.],
+           [4796., 5162.],
+           [4928., 5306.]])
+    >>> np.einsum(a, [0,1,2], b, [1,0,3], [2,3])
+    array([[4400., 4730.],
+           [4532., 4874.],
+           [4664., 5018.],
+           [4796., 5162.],
+           [4928., 5306.]])
+    >>> np.tensordot(a,b, axes=([1,0],[0,1]))
+    array([[4400., 4730.],
+           [4532., 4874.],
+           [4664., 5018.],
+           [4796., 5162.],
+           [4928., 5306.]])
+
+    Writeable returned arrays (since version 1.10.0):
+
+    >>> a = np.zeros((3, 3))
+    >>> np.einsum('ii->i', a)[:] = 1
+    >>> a
+    array([[1., 0., 0.],
+           [0., 1., 0.],
+           [0., 0., 1.]])
+
+    Example of ellipsis use:
+
+    >>> a = np.arange(6).reshape((3,2))
+    >>> b = np.arange(12).reshape((4,3))
+    >>> np.einsum('ki,jk->ij', a, b)
+    array([[10, 28, 46, 64],
+           [13, 40, 67, 94]])
+    >>> np.einsum('ki,...k->i...', a, b)
+    array([[10, 28, 46, 64],
+           [13, 40, 67, 94]])
+    >>> np.einsum('k...,jk', a, b)
+    array([[10, 28, 46, 64],
+           [13, 40, 67, 94]])
+
+    Chained array operations. For more complicated contractions, speed ups
+    might be achieved by repeatedly computing a 'greedy' path or pre-computing
+    the 'optimal' path and repeatedly applying it, using an `einsum_path`
+    insertion (since version 1.12.0). Performance improvements can be
+    particularly significant with larger arrays:
+
+    >>> a = np.ones(64).reshape(2,4,8)
+
+    Basic `einsum`: ~1520ms  (benchmarked on 3.1GHz Intel i5.)
+
+    >>> for iteration in range(500):
+    ...     _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a)
+
+    Sub-optimal `einsum` (due to repeated path calculation time): ~330ms
+
+    >>> for iteration in range(500):
+    ...     _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a,
+    ...         optimize='optimal')
+
+    Greedy `einsum` (faster optimal path approximation): ~160ms
+
+    >>> for iteration in range(500):
+    ...     _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize='greedy')
+
+    Optimal `einsum` (best usage pattern in some use cases): ~110ms
+
+    >>> path = np.einsum_path('ijk,ilm,njm,nlk,abc->',a,a,a,a,a,
+    ...     optimize='optimal')[0]
+    >>> for iteration in range(500):
+    ...     _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize=path)
+
+    """
+    # Special handling if out is specified
+    specified_out = out is not None
+
+    # If no optimization, run pure einsum
+    if optimize is False:
+        if specified_out:
+            kwargs['out'] = out
+        return c_einsum(*operands, **kwargs)
+
+    # Check the kwargs to avoid a more cryptic error later, without having to
+    # repeat default values here
+    valid_einsum_kwargs = ['dtype', 'order', 'casting']
+    unknown_kwargs = [k for k in kwargs if k not in valid_einsum_kwargs]
+    if len(unknown_kwargs):
+        raise TypeError(f"Did not understand the following kwargs: {unknown_kwargs}")
+
+    # Build the contraction list and operand
+    operands, contraction_list = einsum_path(*operands, optimize=optimize,
+                                             einsum_call=True)
+
+    # Start contraction loop
+    for num, contraction in enumerate(contraction_list):
+        inds, einsum_str, _ = contraction
+        tmp_operands = [operands.pop(x) for x in inds]
+
+        # Do we need to deal with the output?
+        handle_out = specified_out and ((num + 1) == len(contraction_list))
+
+        # If out was specified
+        if handle_out:
+            kwargs["out"] = out
+
+        if len(tmp_operands) == 2:
+            # Call (batched) matrix multiplication if possible
+            new_view = bmm_einsum(einsum_str, *tmp_operands, **kwargs)
+        else:
+            # Call einsum
+            new_view = c_einsum(einsum_str, *tmp_operands, **kwargs)
+
+        # Append new items and dereference what we can
+        operands.append(new_view)
+        del tmp_operands, new_view
+
+    if specified_out:
+        return out
+    else:
+        return operands[0]

v12x/pylib/numpy/_core/function_base.py

@@ -0,0 +1,547 @@
+import functools
+import inspect
+import operator
+import types
+import warnings
+
+import numpy as np
+from numpy._core import overrides
+from numpy._core._multiarray_umath import _array_converter
+from numpy._core.multiarray import add_docstring
+
+from . import numeric as _nx
+from .numeric import asanyarray, nan, ndim, result_type
+
+__all__ = ['logspace', 'linspace', 'geomspace']
+
+
+array_function_dispatch = functools.partial(
+    overrides.array_function_dispatch, module='numpy')
+
+
+def _linspace_dispatcher(start, stop, num=None, endpoint=None, retstep=None,
+                         dtype=None, axis=None, *, device=None):
+    return (start, stop)
+
+
+@array_function_dispatch(_linspace_dispatcher)
+def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None,
+             axis=0, *, device=None):
+    """
+    Return evenly spaced numbers over a specified interval.
+
+    Returns `num` evenly spaced samples, calculated over the
+    interval [`start`, `stop`].
+
+    The endpoint of the interval can optionally be excluded.
+
+    .. versionchanged:: 1.20.0
+        Values are rounded towards ``-inf`` instead of ``0`` when an
+        integer ``dtype`` is specified. The old behavior can
+        still be obtained with ``np.linspace(start, stop, num).astype(np.int_)``
+
+    Parameters
+    ----------
+    start : array_like
+        The starting value of the sequence.
+    stop : array_like
+        The end value of the sequence, unless `endpoint` is set to False.
+        In that case, the sequence consists of all but the last of ``num + 1``
+        evenly spaced samples, so that `stop` is excluded.  Note that the step
+        size changes when `endpoint` is False.
+    num : int, optional
+        Number of samples to generate. Default is 50. Must be non-negative.
+    endpoint : bool, optional
+        If True, `stop` is the last sample. Otherwise, it is not included.
+        Default is True.
+    retstep : bool, optional
+        If True, return (`samples`, `step`), where `step` is the spacing
+        between samples.
+    dtype : dtype, optional
+        The type of the output array.  If `dtype` is not given, the data type
+        is inferred from `start` and `stop`. The inferred dtype will never be
+        an integer; `float` is chosen even if the arguments would produce an
+        array of integers.
+    axis : int, optional
+        The axis in the result to store the samples.  Relevant only if start
+        or stop are array-like.  By default (0), the samples will be along a
+        new axis inserted at the beginning. Use -1 to get an axis at the end.
+    device : str, optional
+        The device on which to place the created array. Default: None.
+        For Array-API interoperability only, so must be ``"cpu"`` if passed.
+
+        .. versionadded:: 2.0.0
+
+    Returns
+    -------
+    samples : ndarray
+        There are `num` equally spaced samples in the closed interval
+        ``[start, stop]`` or the half-open interval ``[start, stop)``
+        (depending on whether `endpoint` is True or False).
+    step : float, optional
+        Only returned if `retstep` is True
+
+        Size of spacing between samples.
+
+
+    See Also
+    --------
+    arange : Similar to `linspace`, but uses a step size (instead of the
+             number of samples).
+    geomspace : Similar to `linspace`, but with numbers spaced evenly on a log
+                scale (a geometric progression).
+    logspace : Similar to `geomspace`, but with the end points specified as
+               logarithms.
+    :ref:`how-to-partition`
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.linspace(2.0, 3.0, num=5)
+    array([2.  , 2.25, 2.5 , 2.75, 3.  ])
+    >>> np.linspace(2.0, 3.0, num=5, endpoint=False)
+    array([2. ,  2.2,  2.4,  2.6,  2.8])
+    >>> np.linspace(2.0, 3.0, num=5, retstep=True)
+    (array([2.  ,  2.25,  2.5 ,  2.75,  3.  ]), 0.25)
+
+    Graphical illustration:
+
+    >>> import matplotlib.pyplot as plt
+    >>> N = 8
+    >>> y = np.zeros(N)
+    >>> x1 = np.linspace(0, 10, N, endpoint=True)
+    >>> x2 = np.linspace(0, 10, N, endpoint=False)
+    >>> plt.plot(x1, y, 'o')
+    [<matplotlib.lines.Line2D object at 0x...>]
+    >>> plt.plot(x2, y + 0.5, 'o')
+    [<matplotlib.lines.Line2D object at 0x...>]
+    >>> plt.ylim([-0.5, 1])
+    (-0.5, 1)
+    >>> plt.show()
+
+    """
+    num = operator.index(num)
+    if num < 0:
+        raise ValueError(
+            f"Number of samples, {num}, must be non-negative."
+        )
+    div = (num - 1) if endpoint else num
+
+    conv = _array_converter(start, stop)
+    start, stop = conv.as_arrays()
+    dt = conv.result_type(ensure_inexact=True)
+
+    if dtype is None:
+        dtype = dt
+        integer_dtype = False
+    else:
+        integer_dtype = _nx.issubdtype(dtype, _nx.integer)
+
+    # Use `dtype=type(dt)` to enforce a floating point evaluation:
+    delta = np.subtract(stop, start, dtype=type(dt))
+    y = _nx.arange(
+        0, num, dtype=dt, device=device
+    ).reshape((-1,) + (1,) * ndim(delta))
+
+    # In-place multiplication y *= delta/div is faster, but prevents
+    # the multiplicant from overriding what class is produced, and thus
+    # prevents, e.g. use of Quantities, see gh-7142. Hence, we multiply
+    # in place only for standard scalar types.
+    if div > 0:
+        _mult_inplace = _nx.isscalar(delta)
+        step = delta / div
+        any_step_zero = (
+            step == 0 if _mult_inplace else _nx.asanyarray(step == 0).any())
+        if any_step_zero:
+            # Special handling for denormal numbers, gh-5437
+            y /= div
+            if _mult_inplace:
+                y *= delta
+            else:
+                y = y * delta
+        elif _mult_inplace:
+            y *= step
+        else:
+            y = y * step
+    else:
+        # sequences with 0 items or 1 item with endpoint=True (i.e. div <= 0)
+        # have an undefined step
+        step = nan
+        # Multiply with delta to allow possible override of output class.
+        y = y * delta
+
+    y += start
+
+    if endpoint and num > 1:
+        y[-1, ...] = stop
+
+    if axis != 0:
+        y = _nx.moveaxis(y, 0, axis)
+
+    if integer_dtype:
+        _nx.floor(y, out=y)
+
+    y = conv.wrap(y.astype(dtype, copy=False))
+    if retstep:
+        return y, step
+    else:
+        return y
+
+
+def _logspace_dispatcher(start, stop, num=None, endpoint=None, base=None,
+                         dtype=None, axis=None):
+    return (start, stop, base)
+
+
+@array_function_dispatch(_logspace_dispatcher)
+def logspace(start, stop, num=50, endpoint=True, base=10.0, dtype=None,
+             axis=0):
+    """
+    Return numbers spaced evenly on a log scale.
+
+    In linear space, the sequence starts at ``base ** start``
+    (`base` to the power of `start`) and ends with ``base ** stop``
+    (see `endpoint` below).
+
+    .. versionchanged:: 1.25.0
+        Non-scalar 'base` is now supported
+
+    Parameters
+    ----------
+    start : array_like
+        ``base ** start`` is the starting value of the sequence.
+    stop : array_like
+        ``base ** stop`` is the final value of the sequence, unless `endpoint`
+        is False.  In that case, ``num + 1`` values are spaced over the
+        interval in log-space, of which all but the last (a sequence of
+        length `num`) are returned.
+    num : integer, optional
+        Number of samples to generate.  Default is 50.
+    endpoint : boolean, optional
+        If true, `stop` is the last sample. Otherwise, it is not included.
+        Default is True.
+    base : array_like, optional
+        The base of the log space. The step size between the elements in
+        ``ln(samples) / ln(base)`` (or ``log_base(samples)``) is uniform.
+        Default is 10.0.
+    dtype : dtype
+        The type of the output array.  If `dtype` is not given, the data type
+        is inferred from `start` and `stop`. The inferred type will never be
+        an integer; `float` is chosen even if the arguments would produce an
+        array of integers.
+    axis : int, optional
+        The axis in the result to store the samples.  Relevant only if start,
+        stop, or base are array-like.  By default (0), the samples will be
+        along a new axis inserted at the beginning. Use -1 to get an axis at
+        the end.
+
+    Returns
+    -------
+    samples : ndarray
+        `num` samples, equally spaced on a log scale.
+
+    See Also
+    --------
+    arange : Similar to linspace, with the step size specified instead of the
+             number of samples. Note that, when used with a float endpoint, the
+             endpoint may or may not be included.
+    linspace : Similar to logspace, but with the samples uniformly distributed
+               in linear space, instead of log space.
+    geomspace : Similar to logspace, but with endpoints specified directly.
+    :ref:`how-to-partition`
+
+    Notes
+    -----
+    If base is a scalar, logspace is equivalent to the code
+
+    >>> y = np.linspace(start, stop, num=num, endpoint=endpoint)
+    ... # doctest: +SKIP
+    >>> power(base, y).astype(dtype)
+    ... # doctest: +SKIP
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.logspace(2.0, 3.0, num=4)
+    array([ 100.        ,  215.443469  ,  464.15888336, 1000.        ])
+    >>> np.logspace(2.0, 3.0, num=4, endpoint=False)
+    array([100.        ,  177.827941  ,  316.22776602,  562.34132519])
+    >>> np.logspace(2.0, 3.0, num=4, base=2.0)
+    array([4.        ,  5.0396842 ,  6.34960421,  8.        ])
+    >>> np.logspace(2.0, 3.0, num=4, base=[2.0, 3.0], axis=-1)
+    array([[ 4.        ,  5.0396842 ,  6.34960421,  8.        ],
+           [ 9.        , 12.98024613, 18.72075441, 27.        ]])
+
+    Graphical illustration:
+
+    >>> import matplotlib.pyplot as plt
+    >>> N = 10
+    >>> x1 = np.logspace(0.1, 1, N, endpoint=True)
+    >>> x2 = np.logspace(0.1, 1, N, endpoint=False)
+    >>> y = np.zeros(N)
+    >>> plt.plot(x1, y, 'o')
+    [<matplotlib.lines.Line2D object at 0x...>]
+    >>> plt.plot(x2, y + 0.5, 'o')
+    [<matplotlib.lines.Line2D object at 0x...>]
+    >>> plt.ylim([-0.5, 1])
+    (-0.5, 1)
+    >>> plt.show()
+
+    """
+    if not isinstance(base, (float, int)) and np.ndim(base):
+        # If base is non-scalar, broadcast it with the others, since it
+        # may influence how axis is interpreted.
+        ndmax = np.broadcast(start, stop, base).ndim
+        start, stop, base = (
+            np.array(a, copy=None, subok=True, ndmin=ndmax)
+            for a in (start, stop, base)
+        )
+        base = np.expand_dims(base, axis=axis)
+    y = linspace(start, stop, num=num, endpoint=endpoint, axis=axis)
+    if dtype is None:
+        return _nx.power(base, y)
+    return _nx.power(base, y).astype(dtype, copy=False)
+
+
+def _geomspace_dispatcher(start, stop, num=None, endpoint=None, dtype=None,
+                          axis=None):
+    return (start, stop)
+
+
+@array_function_dispatch(_geomspace_dispatcher)
+def geomspace(start, stop, num=50, endpoint=True, dtype=None, axis=0):
+    """
+    Return numbers spaced evenly on a log scale (a geometric progression).
+
+    This is similar to `logspace`, but with endpoints specified directly.
+    Each output sample is a constant multiple of the previous.
+
+    Parameters
+    ----------
+    start : array_like
+        The starting value of the sequence.
+    stop : array_like
+        The final value of the sequence, unless `endpoint` is False.
+        In that case, ``num + 1`` values are spaced over the
+        interval in log-space, of which all but the last (a sequence of
+        length `num`) are returned.
+    num : integer, optional
+        Number of samples to generate.  Default is 50.
+    endpoint : boolean, optional
+        If true, `stop` is the last sample. Otherwise, it is not included.
+        Default is True.
+    dtype : dtype
+        The type of the output array.  If `dtype` is not given, the data type
+        is inferred from `start` and `stop`. The inferred dtype will never be
+        an integer; `float` is chosen even if the arguments would produce an
+        array of integers.
+    axis : int, optional
+        The axis in the result to store the samples.  Relevant only if start
+        or stop are array-like.  By default (0), the samples will be along a
+        new axis inserted at the beginning. Use -1 to get an axis at the end.
+
+    Returns
+    -------
+    samples : ndarray
+        `num` samples, equally spaced on a log scale.
+
+    See Also
+    --------
+    logspace : Similar to geomspace, but with endpoints specified using log
+               and base.
+    linspace : Similar to geomspace, but with arithmetic instead of geometric
+               progression.
+    arange : Similar to linspace, with the step size specified instead of the
+             number of samples.
+    :ref:`how-to-partition`
+
+    Notes
+    -----
+    If the inputs or dtype are complex, the output will follow a logarithmic
+    spiral in the complex plane.  (There are an infinite number of spirals
+    passing through two points; the output will follow the shortest such path.)
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.geomspace(1, 1000, num=4)
+    array([    1.,    10.,   100.,  1000.])
+    >>> np.geomspace(1, 1000, num=3, endpoint=False)
+    array([   1.,   10.,  100.])
+    >>> np.geomspace(1, 1000, num=4, endpoint=False)
+    array([   1.        ,    5.62341325,   31.6227766 ,  177.827941  ])
+    >>> np.geomspace(1, 256, num=9)
+    array([   1.,    2.,    4.,    8.,   16.,   32.,   64.,  128.,  256.])
+
+    Note that the above may not produce exact integers:
+
+    >>> np.geomspace(1, 256, num=9, dtype=np.int_)
+    array([  1,   2,   4,   7,  16,  32,  63, 127, 256])
+    >>> np.around(np.geomspace(1, 256, num=9)).astype(np.int_)
+    array([  1,   2,   4,   8,  16,  32,  64, 128, 256])
+
+    Negative, decreasing, and complex inputs are allowed:
+
+    >>> np.geomspace(1000, 1, num=4)
+    array([1000.,  100.,   10.,    1.])
+    >>> np.geomspace(-1000, -1, num=4)
+    array([-1000.,  -100.,   -10.,    -1.])
+    >>> np.geomspace(1j, 1000j, num=4)  # Straight line
+    array([0.   +1.j, 0.  +10.j, 0. +100.j, 0.+1000.j])
+    >>> np.geomspace(-1+0j, 1+0j, num=5)  # Circle
+    array([-1.00000000e+00+1.22464680e-16j, -7.07106781e-01+7.07106781e-01j,
+            6.12323400e-17+1.00000000e+00j,  7.07106781e-01+7.07106781e-01j,
+            1.00000000e+00+0.00000000e+00j])
+
+    Graphical illustration of `endpoint` parameter:
+
+    >>> import matplotlib.pyplot as plt
+    >>> N = 10
+    >>> y = np.zeros(N)
+    >>> plt.semilogx(np.geomspace(1, 1000, N, endpoint=True), y + 1, 'o')
+    [<matplotlib.lines.Line2D object at 0x...>]
+    >>> plt.semilogx(np.geomspace(1, 1000, N, endpoint=False), y + 2, 'o')
+    [<matplotlib.lines.Line2D object at 0x...>]
+    >>> plt.axis([0.5, 2000, 0, 3])
+    [0.5, 2000, 0, 3]
+    >>> plt.grid(True, color='0.7', linestyle='-', which='both', axis='both')
+    >>> plt.show()
+
+    """
+    start = asanyarray(start)
+    stop = asanyarray(stop)
+    if _nx.any(start == 0) or _nx.any(stop == 0):
+        raise ValueError('Geometric sequence cannot include zero')
+
+    dt = result_type(start, stop, float(num), _nx.zeros((), dtype))
+    if dtype is None:
+        dtype = dt
+    else:
+        # complex to dtype('complex128'), for instance
+        dtype = _nx.dtype(dtype)
+
+    # Promote both arguments to the same dtype in case, for instance, one is
+    # complex and another is negative and log would produce NaN otherwise.
+    # Copy since we may change things in-place further down.
+    start = start.astype(dt, copy=True)
+    stop = stop.astype(dt, copy=True)
+
+    # Allow negative real values and ensure a consistent result for complex
+    # (including avoiding negligible real or imaginary parts in output) by
+    # rotating start to positive real, calculating, then undoing rotation.
+    out_sign = _nx.sign(start)
+    start /= out_sign
+    stop = stop / out_sign
+
+    log_start = _nx.log10(start)
+    log_stop = _nx.log10(stop)
+    result = logspace(log_start, log_stop, num=num,
+                      endpoint=endpoint, base=10.0, dtype=dt)
+
+    # Make sure the endpoints match the start and stop arguments. This is
+    # necessary because np.exp(np.log(x)) is not necessarily equal to x.
+    if num > 0:
+        result[0] = start
+        if num > 1 and endpoint:
+            result[-1] = stop
+
+    result *= out_sign
+
+    if axis != 0:
+        result = _nx.moveaxis(result, 0, axis)
+
+    return result.astype(dtype, copy=False)
+
+
+def _needs_add_docstring(obj):
+    """
+    Returns true if the only way to set the docstring of `obj` from python is
+    via add_docstring.
+
+    This function errs on the side of being overly conservative.
+    """
+    Py_TPFLAGS_HEAPTYPE = 1 << 9
+
+    if isinstance(obj, (types.FunctionType, types.MethodType, property)):
+        return False
+
+    if isinstance(obj, type) and obj.__flags__ & Py_TPFLAGS_HEAPTYPE:
+        return False
+
+    return True
+
+
+def _add_docstring(obj, doc, warn_on_python):
+    if warn_on_python and not _needs_add_docstring(obj):
+        warnings.warn(
+            f"add_newdoc was used on a pure-python object {obj}. "
+            "Prefer to attach it directly to the source.",
+            UserWarning,
+            stacklevel=3)
+
+    doc = inspect.cleandoc(doc)
+
+    try:
+        add_docstring(obj, doc)
+    except Exception:
+        pass
+
+
+def add_newdoc(place, obj, doc, warn_on_python=True):
+    """
+    Add documentation to an existing object, typically one defined in C
+
+    The purpose is to allow easier editing of the docstrings without requiring
+    a re-compile. This exists primarily for internal use within numpy itself.
+
+    Parameters
+    ----------
+    place : str
+        The absolute name of the module to import from
+    obj : str | None
+        The name of the object to add documentation to, typically a class or
+        function name.
+    doc : str | tuple[str, str] | list[tuple[str, str]]
+        If a string, the documentation to apply to `obj`
+
+        If a tuple, then the first element is interpreted as an attribute
+        of `obj` and the second as the docstring to apply -
+        ``(method, docstring)``
+
+        If a list, then each element of the list should be a tuple of length
+        two - ``[(method1, docstring1), (method2, docstring2), ...]``
+    warn_on_python : bool
+        If True, the default, emit `UserWarning` if this is used to attach
+        documentation to a pure-python object.
+
+    Notes
+    -----
+    This routine never raises an error if the docstring can't be written, but
+    will raise an error if the object being documented does not exist.
+
+    This routine cannot modify read-only docstrings, as appear
+    in new-style classes or built-in functions. Because this
+    routine never raises an error the caller must check manually
+    that the docstrings were changed.
+
+    Since this function grabs the ``char *`` from a c-level str object and puts
+    it into the ``tp_doc`` slot of the type of `obj`, it violates a number of
+    C-API best-practices, by:
+
+    - modifying a `PyTypeObject` after calling `PyType_Ready`
+    - calling `Py_INCREF` on the str and losing the reference, so the str
+      will never be released
+
+    If possible it should be avoided.
+    """
+    new = getattr(__import__(place, globals(), {}, [obj]), obj)
+    if isinstance(doc, str):
+        if "${ARRAY_FUNCTION_LIKE}" in doc:
+            doc = overrides.get_array_function_like_doc(new, doc)
+        _add_docstring(new, doc, warn_on_python)
+    elif isinstance(doc, tuple):
+        attr, docstring = doc
+        _add_docstring(getattr(new, attr), docstring, warn_on_python)
+    elif isinstance(doc, list):
+        for attr, docstring in doc:
+            _add_docstring(getattr(new, attr), docstring, warn_on_python)

v12x/pylib/numpy/_core/getlimits.py

@@ -0,0 +1,449 @@
+"""Machine limits for Float32 and Float64 and (long double) if available...
+
+"""
+__all__ = ['finfo', 'iinfo']
+
+import math
+import types
+from functools import cached_property
+
+from numpy._utils import set_module
+
+from . import numeric, numerictypes as ntypes
+from ._multiarray_umath import _finfo_get_realdtype, _populate_finfo_constants
+
+
+def _fr0(a):
+    """fix rank-0 --> rank-1"""
+    if a.ndim == 0:
+        a = a.reshape((1,))
+    return a
+
+
+def _fr1(a):
+    """fix rank > 0 --> rank-0"""
+    if a.size == 1:
+        a = a.reshape(())
+    return a
+
+
+# Parameters for creating MachAr / MachAr-like objects
+_title_fmt = 'numpy {} precision floating point number'
+_MACHAR_PARAMS = {
+    ntypes.double: {
+        'itype': ntypes.int64,
+        'fmt': '%24.16e',
+        'title': _title_fmt.format('double')},
+    ntypes.single: {
+        'itype': ntypes.int32,
+        'fmt': '%15.7e',
+        'title': _title_fmt.format('single')},
+    ntypes.longdouble: {
+        'itype': ntypes.longlong,
+        'fmt': '%s',
+        'title': _title_fmt.format('long double')},
+    ntypes.half: {
+        'itype': ntypes.int16,
+        'fmt': '%12.5e',
+        'title': _title_fmt.format('half')}}
+
+
+@set_module('numpy')
+class finfo:
+    """
+    finfo(dtype)
+
+    Machine limits for floating point types.
+
+    Attributes
+    ----------
+    bits : int
+        The number of bits occupied by the type.
+    dtype : dtype
+        Returns the dtype for which `finfo` returns information. For complex
+        input, the returned dtype is the associated ``float*`` dtype for its
+        real and complex components.
+    eps : float
+        The difference between 1.0 and the next smallest representable float
+        larger than 1.0. For example, for 64-bit binary floats in the IEEE-754
+        standard, ``eps = 2**-52``, approximately 2.22e-16.
+    epsneg : float
+        The difference between 1.0 and the next smallest representable float
+        less than 1.0. For example, for 64-bit binary floats in the IEEE-754
+        standard, ``epsneg = 2**-53``, approximately 1.11e-16.
+    iexp : int
+        The number of bits in the exponent portion of the floating point
+        representation.
+    machep : int
+        The exponent that yields `eps`.
+    max : floating point number of the appropriate type
+        The largest representable number.
+    maxexp : int
+        The smallest positive power of the base (2) that causes overflow.
+        Corresponds to the C standard MAX_EXP.
+    min : floating point number of the appropriate type
+        The smallest representable number, typically ``-max``.
+    minexp : int
+        The most negative power of the base (2) consistent with there
+        being no leading 0's in the mantissa. Corresponds to the C
+        standard MIN_EXP - 1.
+    negep : int
+        The exponent that yields `epsneg`.
+    nexp : int
+        The number of bits in the exponent including its sign and bias.
+    nmant : int
+        The number of explicit bits in the mantissa (excluding the implicit
+        leading bit for normalized numbers).
+    precision : int
+        The approximate number of decimal digits to which this kind of
+        float is precise.
+    resolution : floating point number of the appropriate type
+        The approximate decimal resolution of this type, i.e.,
+        ``10**-precision``.
+    tiny : float
+        An alias for `smallest_normal`, kept for backwards compatibility.
+    smallest_normal : float
+        The smallest positive floating point number with 1 as leading bit in
+        the mantissa following IEEE-754 (see Notes).
+    smallest_subnormal : float
+        The smallest positive floating point number with 0 as leading bit in
+        the mantissa following IEEE-754.
+
+    Parameters
+    ----------
+    dtype : float, dtype, or instance
+        Kind of floating point or complex floating point
+        data-type about which to get information.
+
+    See Also
+    --------
+    iinfo : The equivalent for integer data types.
+    spacing : The distance between a value and the nearest adjacent number
+    nextafter : The next floating point value after x1 towards x2
+
+    Notes
+    -----
+    For developers of NumPy: do not instantiate this at the module level.
+    The initial calculation of these parameters is expensive and negatively
+    impacts import times.  These objects are cached, so calling ``finfo()``
+    repeatedly inside your functions is not a problem.
+
+    Note that ``smallest_normal`` is not actually the smallest positive
+    representable value in a NumPy floating point type. As in the IEEE-754
+    standard [1]_, NumPy floating point types make use of subnormal numbers to
+    fill the gap between 0 and ``smallest_normal``. However, subnormal numbers
+    may have significantly reduced precision [2]_.
+
+    For ``longdouble``, the representation varies across platforms. On most
+    platforms it is IEEE 754 binary128 (quad precision) or binary64-extended
+    (80-bit extended precision). On PowerPC systems, it may use the IBM
+    double-double format (a pair of float64 values), which has special
+    characteristics for precision and range.
+
+    This function can also be used for complex data types as well. If used,
+    the output will be the same as the corresponding real float type
+    (e.g. numpy.finfo(numpy.csingle) is the same as numpy.finfo(numpy.single)).
+    However, the output is true for the real and imaginary components.
+
+    References
+    ----------
+    .. [1] IEEE Standard for Floating-Point Arithmetic, IEEE Std 754-2008,
+           pp.1-70, 2008, https://doi.org/10.1109/IEEESTD.2008.4610935
+    .. [2] Wikipedia, "Denormal Numbers",
+           https://en.wikipedia.org/wiki/Denormal_number
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.finfo(np.float64).dtype
+    dtype('float64')
+    >>> np.finfo(np.complex64).dtype
+    dtype('float32')
+
+    """
+
+    _finfo_cache = {}  # noqa: RUF012
+
+    __class_getitem__ = classmethod(types.GenericAlias)
+
+    def __new__(cls, dtype):
+        if dtype is None:
+            raise TypeError("dtype must not be None")
+
+        try:
+            obj = cls._finfo_cache.get(dtype)  # most common path
+            if obj is not None:
+                return obj
+        except TypeError:
+            pass
+
+        try:
+            dtype = numeric.dtype(dtype)
+        except TypeError:
+            # In case a float instance was given
+            dtype = numeric.dtype(type(dtype))
+
+        obj = cls._finfo_cache.get(dtype)
+        if obj is not None:
+            return obj
+        dtypes = [dtype]
+        # Call result_type to normalize to e.g. native byte-order:
+        newdtype = numeric.result_type(dtype)
+        if newdtype is not dtype:
+            dtypes.append(newdtype)
+            dtype = newdtype
+
+        obj = cls._finfo_cache.get(dtype)
+        if obj is not None:
+            return obj
+
+        sctype = newdtype.type
+        if sctype is not None and not issubclass(sctype, numeric.floating):
+            newdtype = _finfo_get_realdtype(dtype)
+            if newdtype is not dtype:
+                # dtype changed, for example from complex128 to float64
+                dtypes.append(newdtype)
+                dtype = newdtype
+
+                obj = cls._finfo_cache.get(dtype, None)
+                if obj is not None:
+                    # the original dtype was not in the cache, but the new
+                    # dtype is in the cache. we add the original dtypes to
+                    # the cache and return the result
+                    for dt in dtypes:
+                        cls._finfo_cache[dt] = obj
+                    return obj
+        obj = object.__new__(cls)._init(dtype)
+        for dt in dtypes:
+            cls._finfo_cache[dt] = obj
+        return obj
+
+    def _init(self, dtype):
+        self.dtype = numeric.dtype(dtype)
+        self.bits = self.dtype.itemsize * 8
+        self._fmt = None
+        self._repr = None
+        _populate_finfo_constants(self, self.dtype)
+        return self
+
+    @cached_property
+    def epsneg(self):
+        # Assume typical floating point logic.  Could also use nextafter.
+        return self.eps / self._radix
+
+    @cached_property
+    def resolution(self):
+        return self.dtype.type(10)**-self.precision
+
+    @cached_property
+    def machep(self):
+        return int(math.log2(self.eps))
+
+    @cached_property
+    def negep(self):
+        return int(math.log2(self.epsneg))
+
+    @cached_property
+    def nexp(self):
+        # considering all ones (inf/nan) and all zeros (subnormal/zero)
+        return math.ceil(math.log2(self.maxexp - self.minexp + 2))
+
+    @cached_property
+    def iexp(self):
+        # Calculate exponent bits from it's range:
+        return math.ceil(math.log2(self.maxexp - self.minexp))
+
+    def __str__(self):
+        if (fmt := getattr(self, "_fmt", None)) is not None:
+            return fmt
+
+        def get_str(name, pad=None):
+            if (val := getattr(self, name, None)) is None:
+                return "<undefined>"
+            if pad is not None:
+                s = str(val).ljust(pad)
+            return str(val)
+
+        precision = get_str("precision", 3)
+        machep = get_str("machep", 6)
+        negep = get_str("negep", 6)
+        minexp = get_str("minexp", 6)
+        maxexp = get_str("maxexp", 6)
+        resolution = get_str("resolution")
+        eps = get_str("eps")
+        epsneg = get_str("epsneg")
+        tiny = get_str("tiny")
+        smallest_normal = get_str("smallest_normal")
+        smallest_subnormal = get_str("smallest_subnormal")
+        nexp = get_str("nexp", 6)
+        max_ = get_str("max")
+        if hasattr(self, "min") and hasattr(self, "max") and -self.min == self.max:
+            min_ = "-max"
+        else:
+            min_ = get_str("min")
+
+        fmt = (
+            f'Machine parameters for {self.dtype}\n'
+            f'---------------------------------------------------------------\n'
+            f'precision = {precision}   resolution = {resolution}\n'
+            f'machep = {machep}   eps =        {eps}\n'
+            f'negep =  {negep}   epsneg =     {epsneg}\n'
+            f'minexp = {minexp}   tiny =       {tiny}\n'
+            f'maxexp = {maxexp}   max =        {max_}\n'
+            f'nexp =   {nexp}   min =        {min_}\n'
+            f'smallest_normal = {smallest_normal}   '
+            f'smallest_subnormal = {smallest_subnormal}\n'
+            f'---------------------------------------------------------------\n'
+        )
+        self._fmt = fmt
+        return fmt
+
+    def __repr__(self):
+        if (repr_str := getattr(self, "_repr", None)) is not None:
+            return repr_str
+
+        c = self.__class__.__name__
+
+        # Use precision+1 digits in exponential notation
+        fmt_str = _MACHAR_PARAMS.get(self.dtype.type, {}).get('fmt', '%s')
+        if fmt_str != '%s' and hasattr(self, 'max') and hasattr(self, 'min'):
+            max_str = (fmt_str % self.max).strip()
+            min_str = (fmt_str % self.min).strip()
+        else:
+            max_str = str(self.max)
+            min_str = str(self.min)
+
+        resolution_str = str(self.resolution)
+
+        repr_str = (f"{c}(resolution={resolution_str}, min={min_str},"
+                    f" max={max_str}, dtype={self.dtype})")
+        self._repr = repr_str
+        return repr_str
+
+    @cached_property
+    def tiny(self):
+        """Return the value for tiny, alias of smallest_normal.
+
+        Returns
+        -------
+        tiny : float
+            Value for the smallest normal, alias of smallest_normal.
+
+        Warns
+        -----
+        UserWarning
+            If the calculated value for the smallest normal is requested for
+            double-double.
+        """
+        return self.smallest_normal
+
+
+@set_module('numpy')
+class iinfo:
+    """
+    iinfo(type)
+
+    Machine limits for integer types.
+
+    Attributes
+    ----------
+    bits : int
+        The number of bits occupied by the type.
+    dtype : dtype
+        Returns the dtype for which `iinfo` returns information.
+    min : int
+        The smallest integer expressible by the type.
+    max : int
+        The largest integer expressible by the type.
+
+    Parameters
+    ----------
+    int_type : integer type, dtype, or instance
+        The kind of integer data type to get information about.
+
+    See Also
+    --------
+    finfo : The equivalent for floating point data types.
+
+    Examples
+    --------
+    With types:
+
+    >>> import numpy as np
+    >>> ii16 = np.iinfo(np.int16)
+    >>> ii16.min
+    -32768
+    >>> ii16.max
+    32767
+    >>> ii32 = np.iinfo(np.int32)
+    >>> ii32.min
+    -2147483648
+    >>> ii32.max
+    2147483647
+
+    With instances:
+
+    >>> ii32 = np.iinfo(np.int32(10))
+    >>> ii32.min
+    -2147483648
+    >>> ii32.max
+    2147483647
+
+    """
+
+    _min_vals = {}  # noqa: RUF012
+    _max_vals = {}  # noqa: RUF012
+
+    __class_getitem__ = classmethod(types.GenericAlias)
+
+    def __init__(self, int_type):
+        try:
+            self.dtype = numeric.dtype(int_type)
+        except TypeError:
+            self.dtype = numeric.dtype(type(int_type))
+        self.kind = self.dtype.kind
+        self.bits = self.dtype.itemsize * 8
+        self.key = f"{self.kind}{self.bits}"
+        if self.kind not in 'iu':
+            raise ValueError(f"Invalid integer data type {self.kind!r}.")
+
+    @property
+    def min(self):
+        """Minimum value of given dtype."""
+        if self.kind == 'u':
+            return 0
+        else:
+            try:
+                val = iinfo._min_vals[self.key]
+            except KeyError:
+                val = int(-(1 << (self.bits - 1)))
+                iinfo._min_vals[self.key] = val
+            return val
+
+    @property
+    def max(self):
+        """Maximum value of given dtype."""
+        try:
+            val = iinfo._max_vals[self.key]
+        except KeyError:
+            if self.kind == 'u':
+                val = int((1 << self.bits) - 1)
+            else:
+                val = int((1 << (self.bits - 1)) - 1)
+            iinfo._max_vals[self.key] = val
+        return val
+
+    def __str__(self):
+        """String representation."""
+        fmt = (
+            'Machine parameters for %(dtype)s\n'
+            '---------------------------------------------------------------\n'
+            'min = %(min)s\n'
+            'max = %(max)s\n'
+            '---------------------------------------------------------------\n'
+            )
+        return fmt % {'dtype': self.dtype, 'min': self.min, 'max': self.max}
+
+    def __repr__(self):
+        name = self.__class__.__name__
+        return f'{name}(min={self.min}, max={self.max}, dtype={self.dtype})'

v12x/pylib/numpy/_core/memmap.py

@@ -0,0 +1,362 @@
+import operator
+from contextlib import nullcontext
+
+import numpy as np
+from numpy._utils import set_module
+
+from .numeric import dtype, ndarray, uint8
+
+__all__ = ['memmap']
+
+dtypedescr = dtype
+valid_filemodes = ["r", "c", "r+", "w+"]
+writeable_filemodes = ["r+", "w+"]
+
+mode_equivalents = {
+    "readonly": "r",
+    "copyonwrite": "c",
+    "readwrite": "r+",
+    "write": "w+"
+    }
+
+
+@set_module('numpy')
+class memmap(ndarray):
+    """Create a memory-map to an array stored in a *binary* file on disk.
+
+    Memory-mapped files are used for accessing small segments of large files
+    on disk, without reading the entire file into memory.  NumPy's
+    memmap's are array-like objects.  This differs from Python's ``mmap``
+    module, which uses file-like objects.
+
+    This subclass of ndarray has some unpleasant interactions with
+    some operations, because it doesn't quite fit properly as a subclass.
+    An alternative to using this subclass is to create the ``mmap``
+    object yourself, then create an ndarray with ndarray.__new__ directly,
+    passing the object created in its 'buffer=' parameter.
+
+    This class may at some point be turned into a factory function
+    which returns a view into an mmap buffer.
+
+    Flush the memmap instance to write the changes to the file. Currently there
+    is no API to close the underlying ``mmap``. It is tricky to ensure the
+    resource is actually closed, since it may be shared between different
+    memmap instances.
+
+
+    Parameters
+    ----------
+    filename : str, file-like object, or pathlib.Path instance
+        The file name or file object to be used as the array data buffer.
+    dtype : data-type, optional
+        The data-type used to interpret the file contents.
+        Default is `uint8`.
+    mode : {'r+', 'r', 'w+', 'c'}, optional
+        The file is opened in this mode:
+
+        +------+-------------------------------------------------------------+
+        | 'r'  | Open existing file for reading only.                        |
+        +------+-------------------------------------------------------------+
+        | 'r+' | Open existing file for reading and writing.                 |
+        +------+-------------------------------------------------------------+
+        | 'w+' | Create or overwrite existing file for reading and writing.  |
+        |      | If ``mode == 'w+'`` then `shape` must also be specified.    |
+        +------+-------------------------------------------------------------+
+        | 'c'  | Copy-on-write: assignments affect data in memory, but       |
+        |      | changes are not saved to disk.  The file on disk is         |
+        |      | read-only.                                                  |
+        +------+-------------------------------------------------------------+
+
+        Default is 'r+'.
+    offset : int, optional
+        In the file, array data starts at this offset. Since `offset` is
+        measured in bytes, it should normally be a multiple of the byte-size
+        of `dtype`. When ``mode != 'r'``, even positive offsets beyond end of
+        file are valid; The file will be extended to accommodate the
+        additional data. By default, ``memmap`` will start at the beginning of
+        the file, even if ``filename`` is a file pointer ``fp`` and
+        ``fp.tell() != 0``.
+    shape : int or sequence of ints, optional
+        The desired shape of the array. If ``mode == 'r'`` and the number
+        of remaining bytes after `offset` is not a multiple of the byte-size
+        of `dtype`, you must specify `shape`. By default, the returned array
+        will be 1-D with the number of elements determined by file size
+        and data-type.
+
+        .. versionchanged:: 2.0
+         The shape parameter can now be any integer sequence type, previously
+         types were limited to tuple and int.
+
+    order : {'C', 'F'}, optional
+        Specify the order of the ndarray memory layout:
+        :term:`row-major`, C-style or :term:`column-major`,
+        Fortran-style.  This only has an effect if the shape is
+        greater than 1-D.  The default order is 'C'.
+
+    Attributes
+    ----------
+    filename : str or pathlib.Path instance
+        Path to the mapped file.
+    offset : int
+        Offset position in the file.
+    mode : str
+        File mode.
+
+    Methods
+    -------
+    flush
+        Flush any changes in memory to file on disk.
+        When you delete a memmap object, flush is called first to write
+        changes to disk.
+
+
+    See also
+    --------
+    lib.format.open_memmap : Create or load a memory-mapped ``.npy`` file.
+
+    Notes
+    -----
+    The memmap object can be used anywhere an ndarray is accepted.
+    Given a memmap ``fp``, ``isinstance(fp, numpy.ndarray)`` returns
+    ``True``.
+
+    Memory-mapped files cannot be larger than 2GB on 32-bit systems.
+
+    When a memmap causes a file to be created or extended beyond its
+    current size in the filesystem, the contents of the new part are
+    unspecified. On systems with POSIX filesystem semantics, the extended
+    part will be filled with zero bytes.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> data = np.arange(12, dtype=np.float32).reshape((3, 4))
+
+    This example uses a temporary file so that doctest doesn't write
+    files to your directory. You would use a 'normal' filename.
+
+    >>> from tempfile import mkdtemp
+    >>> import os.path as path
+    >>> filename = path.join(mkdtemp(), 'newfile.dat')
+
+    Create a memmap with dtype and shape that matches our data:
+
+    >>> fp = np.memmap(filename, dtype=np.float32, mode='w+', shape=(3,4))
+    >>> fp
+    memmap([[0., 0., 0., 0.],
+            [0., 0., 0., 0.],
+            [0., 0., 0., 0.]], dtype=float32)
+
+    Write data to memmap array:
+
+    >>> fp[:] = data[:]
+    >>> fp
+    memmap([[  0.,   1.,   2.,   3.],
+            [  4.,   5.,   6.,   7.],
+            [  8.,   9.,  10.,  11.]], dtype=float32)
+
+    >>> fp.filename == path.abspath(filename)
+    True
+
+    Flushes memory changes to disk in order to read them back
+
+    >>> fp.flush()
+
+    Load the memmap and verify data was stored:
+
+    >>> newfp = np.memmap(filename, dtype=np.float32, mode='r', shape=(3,4))
+    >>> newfp
+    memmap([[  0.,   1.,   2.,   3.],
+            [  4.,   5.,   6.,   7.],
+            [  8.,   9.,  10.,  11.]], dtype=float32)
+
+    Read-only memmap:
+
+    >>> fpr = np.memmap(filename, dtype=np.float32, mode='r', shape=(3,4))
+    >>> fpr.flags.writeable
+    False
+
+    Copy-on-write memmap:
+
+    >>> fpc = np.memmap(filename, dtype=np.float32, mode='c', shape=(3,4))
+    >>> fpc.flags.writeable
+    True
+
+    It's possible to assign to copy-on-write array, but values are only
+    written into the memory copy of the array, and not written to disk:
+
+    >>> fpc
+    memmap([[  0.,   1.,   2.,   3.],
+            [  4.,   5.,   6.,   7.],
+            [  8.,   9.,  10.,  11.]], dtype=float32)
+    >>> fpc[0,:] = 0
+    >>> fpc
+    memmap([[  0.,   0.,   0.,   0.],
+            [  4.,   5.,   6.,   7.],
+            [  8.,   9.,  10.,  11.]], dtype=float32)
+
+    File on disk is unchanged:
+
+    >>> fpr
+    memmap([[  0.,   1.,   2.,   3.],
+            [  4.,   5.,   6.,   7.],
+            [  8.,   9.,  10.,  11.]], dtype=float32)
+
+    Offset into a memmap:
+
+    >>> fpo = np.memmap(filename, dtype=np.float32, mode='r', offset=16)
+    >>> fpo
+    memmap([  4.,   5.,   6.,   7.,   8.,   9.,  10.,  11.], dtype=float32)
+
+    """
+
+    __array_priority__ = -100.0
+
+    def __new__(cls, filename, dtype=uint8, mode='r+', offset=0,
+                shape=None, order='C'):
+        # Import here to minimize 'import numpy' overhead
+        import mmap
+        import os.path
+        try:
+            mode = mode_equivalents[mode]
+        except KeyError as e:
+            if mode not in valid_filemodes:
+                all_modes = valid_filemodes + list(mode_equivalents.keys())
+                raise ValueError(
+                    f"mode must be one of {all_modes!r} (got {mode!r})"
+                ) from None
+
+        if mode == 'w+' and shape is None:
+            raise ValueError("shape must be given if mode == 'w+'")
+
+        if hasattr(filename, 'read'):
+            f_ctx = nullcontext(filename)
+        else:
+            f_ctx = open(
+                os.fspath(filename),
+                ('r' if mode == 'c' else mode) + 'b'
+            )
+
+        with f_ctx as fid:
+            fid.seek(0, 2)
+            flen = fid.tell()
+            descr = dtypedescr(dtype)
+            _dbytes = descr.itemsize
+
+            if shape is None:
+                bytes = flen - offset
+                if bytes % _dbytes:
+                    raise ValueError("Size of available data is not a "
+                            "multiple of the data-type size.")
+                size = bytes // _dbytes
+                shape = (size,)
+            else:
+                if not isinstance(shape, (tuple, list)):
+                    try:
+                        shape = [operator.index(shape)]
+                    except TypeError:
+                        pass
+                shape = tuple(shape)
+                size = np.intp(1)  # avoid overflows
+                for k in shape:
+                    size *= k
+
+            bytes = int(offset + size * _dbytes)
+
+            if mode in ('w+', 'r+'):
+                # gh-27723
+                # if bytes == 0, we write out 1 byte to allow empty memmap.
+                bytes = max(bytes, 1)
+                if flen < bytes:
+                    fid.seek(bytes - 1, 0)
+                    fid.write(b'\0')
+                    fid.flush()
+
+            if mode == 'c':
+                acc = mmap.ACCESS_COPY
+            elif mode == 'r':
+                acc = mmap.ACCESS_READ
+            else:
+                acc = mmap.ACCESS_WRITE
+
+            start = offset - offset % mmap.ALLOCATIONGRANULARITY
+            bytes -= start
+            # bytes == 0 is problematic as in mmap length=0 maps the full file.
+            # See PR gh-27723 for a more detailed explanation.
+            if bytes == 0 and start > 0:
+                bytes += mmap.ALLOCATIONGRANULARITY
+                start -= mmap.ALLOCATIONGRANULARITY
+            array_offset = offset - start
+            mm = mmap.mmap(fid.fileno(), bytes, access=acc, offset=start)
+
+            self = ndarray.__new__(cls, shape, dtype=descr, buffer=mm,
+                                   offset=array_offset, order=order)
+            self._mmap = mm
+            self.offset = offset
+            self.mode = mode
+
+            if isinstance(filename, os.PathLike):
+                # special case - if we were constructed with a pathlib.path,
+                # then filename is a path object, not a string
+                self.filename = filename.resolve()
+            elif hasattr(fid, "name") and isinstance(fid.name, str):
+                # py3 returns int for TemporaryFile().name
+                self.filename = os.path.abspath(fid.name)
+            # same as memmap copies (e.g. memmap + 1)
+            else:
+                self.filename = None
+
+        return self
+
+    def __array_finalize__(self, obj):
+        if hasattr(obj, '_mmap') and np.may_share_memory(self, obj):
+            self._mmap = obj._mmap
+            self.filename = obj.filename
+            self.offset = obj.offset
+            self.mode = obj.mode
+        else:
+            self._mmap = None
+            self.filename = None
+            self.offset = None
+            self.mode = None
+
+    def flush(self):
+        """
+        Write any changes in the array to the file on disk.
+
+        For further information, see `memmap`.
+
+        Parameters
+        ----------
+        None
+
+        See Also
+        --------
+        memmap
+
+        """
+        if self.base is not None and hasattr(self.base, 'flush'):
+            self.base.flush()
+
+    def __array_wrap__(self, arr, context=None, return_scalar=False):
+        arr = super().__array_wrap__(arr, context)
+
+        # Return a memmap if a memmap was given as the output of the
+        # ufunc. Leave the arr class unchanged if self is not a memmap
+        # to keep original memmap subclasses behavior
+        if self is arr or type(self) is not memmap:
+            return arr
+
+        # Return scalar instead of 0d memmap, e.g. for np.sum with
+        # axis=None (note that subclasses will not reach here)
+        if return_scalar:
+            return arr[()]
+
+        # Return ndarray otherwise
+        return arr.view(np.ndarray)
+
+    def __getitem__(self, index):
+        res = super().__getitem__(index)
+        if type(res) is memmap and res._mmap is None:
+            return res.view(type=ndarray)
+        return res

v12x/pylib/numpy/_core/multiarray.py

@@ -0,0 +1,1743 @@
+"""
+Create the numpy._core.multiarray namespace for backward compatibility.
+In v1.16 the multiarray and umath c-extension modules were merged into
+a single _multiarray_umath extension module. So we replicate the old
+namespace by importing from the extension module.
+
+"""
+
+import functools
+
+from . import _multiarray_umath, overrides
+from ._multiarray_umath import *
+
+# These imports are needed for backward compatibility,
+# do not change them. issue gh-15518
+# _get_ndarray_c_version is semi-public, on purpose not added to __all__
+from ._multiarray_umath import (  # noqa: F401
+    _ARRAY_API,
+    _flagdict,
+    _get_madvise_hugepage,
+    _get_ndarray_c_version,
+    _monotonicity,
+    _place,
+    _reconstruct,
+    _set_madvise_hugepage,
+    _vec_string,
+    from_dlpack,
+)
+
+__all__ = [
+    '_ARRAY_API', 'ALLOW_THREADS', 'BUFSIZE', 'CLIP', 'DATETIMEUNITS',
+    'ITEM_HASOBJECT', 'ITEM_IS_POINTER', 'LIST_PICKLE', 'MAXDIMS',
+    'MAY_SHARE_BOUNDS', 'MAY_SHARE_EXACT', 'NEEDS_INIT', 'NEEDS_PYAPI',
+    'RAISE', 'USE_GETITEM', 'USE_SETITEM', 'WRAP',
+    '_flagdict', 'from_dlpack', '_place', '_reconstruct', '_vec_string',
+    '_monotonicity', 'add_docstring', 'arange', 'array', 'asarray',
+    'asanyarray', 'ascontiguousarray', 'asfortranarray', 'bincount',
+    'broadcast', 'busday_count', 'busday_offset', 'busdaycalendar', 'can_cast',
+    'compare_chararrays', 'concatenate', 'copyto', 'correlate', 'correlate2',
+    'count_nonzero', 'c_einsum', 'datetime_as_string', 'datetime_data',
+    'dot', 'dragon4_positional', 'dragon4_scientific', 'dtype',
+    'empty', 'empty_like', 'error', 'flagsobj', 'flatiter', 'format_longfloat',
+    'frombuffer', 'fromfile', 'fromiter', 'fromstring',
+    'get_handler_name', 'get_handler_version', 'inner', 'interp',
+    'interp_complex', 'is_busday', 'lexsort', 'matmul', 'vecdot',
+    'may_share_memory', 'min_scalar_type', 'ndarray', 'nditer', 'nested_iters',
+    'normalize_axis_index', 'packbits', 'promote_types', 'putmask',
+    'ravel_multi_index', 'result_type', 'scalar', 'set_datetimeparse_function',
+    'set_typeDict', 'shares_memory', 'typeinfo',
+    'unpackbits', 'unravel_index', 'vdot', 'where', 'zeros']
+
+# For backward compatibility, make sure pickle imports
+# these functions from here
+_reconstruct.__module__ = 'numpy._core.multiarray'
+scalar.__module__ = 'numpy._core.multiarray'
+
+
+from_dlpack.__module__ = 'numpy'
+arange.__module__ = 'numpy'
+array.__module__ = 'numpy'
+asarray.__module__ = 'numpy'
+asanyarray.__module__ = 'numpy'
+ascontiguousarray.__module__ = 'numpy'
+asfortranarray.__module__ = 'numpy'
+datetime_data.__module__ = 'numpy'
+empty.__module__ = 'numpy'
+frombuffer.__module__ = 'numpy'
+fromfile.__module__ = 'numpy'
+fromiter.__module__ = 'numpy'
+frompyfunc.__module__ = 'numpy'
+fromstring.__module__ = 'numpy'
+may_share_memory.__module__ = 'numpy'
+nested_iters.__module__ = 'numpy'
+promote_types.__module__ = 'numpy'
+zeros.__module__ = 'numpy'
+normalize_axis_index.__module__ = 'numpy.lib.array_utils'
+add_docstring.__module__ = 'numpy.lib'
+compare_chararrays.__module__ = 'numpy.char'
+
+
+def _override___module__():
+    namespace_names = globals()
+    for ufunc_name in [
+        'absolute', 'arccos', 'arccosh', 'add', 'arcsin', 'arcsinh', 'arctan',
+        'arctan2', 'arctanh', 'bitwise_and', 'bitwise_count', 'invert',
+        'left_shift', 'bitwise_or', 'right_shift', 'bitwise_xor', 'cbrt',
+        'ceil', 'conjugate', 'copysign', 'cos', 'cosh', 'deg2rad', 'degrees',
+        'divide', 'divmod', 'equal', 'exp', 'exp2', 'expm1', 'fabs',
+        'float_power', 'floor', 'floor_divide', 'fmax', 'fmin', 'fmod',
+        'frexp', 'gcd', 'greater', 'greater_equal', 'heaviside', 'hypot',
+        'isfinite', 'isinf', 'isnan', 'isnat', 'lcm', 'ldexp', 'less',
+        'less_equal', 'log', 'log10', 'log1p', 'log2', 'logaddexp',
+        'logaddexp2', 'logical_and', 'logical_not', 'logical_or',
+        'logical_xor', 'matmul', 'matvec', 'maximum', 'minimum', 'remainder',
+        'modf', 'multiply', 'negative', 'nextafter', 'not_equal', 'positive',
+        'power', 'rad2deg', 'radians', 'reciprocal', 'rint', 'sign', 'signbit',
+        'sin', 'sinh', 'spacing', 'sqrt', 'square', 'subtract', 'tan', 'tanh',
+        'trunc', 'vecdot', 'vecmat',
+    ]:
+        ufunc = namespace_names[ufunc_name]
+        ufunc.__module__ = "numpy"
+        ufunc.__qualname__ = ufunc_name
+
+
+_override___module__()
+
+
+# We can't verify dispatcher signatures because NumPy's C functions don't
+# support introspection.
+array_function_from_c_func_and_dispatcher = functools.partial(
+    overrides.array_function_from_dispatcher,
+    module='numpy', docs_from_dispatcher=True, verify=False)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.empty_like)
+def empty_like(
+    prototype, dtype=None, order="K", subok=True, shape=None, *, device=None
+):
+    """
+    empty_like(
+        prototype,
+        /,
+        dtype=None,
+        order='K',
+        subok=True,
+        shape=None,
+        *,
+        device=None,
+    )
+    --
+
+    Return a new array with the same shape and type as a given array.
+
+    Parameters
+    ----------
+    prototype : array_like
+        The shape and data-type of `prototype` define these same attributes
+        of the returned array.
+    dtype : data-type, optional
+        Overrides the data type of the result.
+    order : {'C', 'F', 'A', or 'K'}, optional
+        Overrides the memory layout of the result. 'C' means C-order,
+        'F' means F-order, 'A' means 'F' if `prototype` is Fortran
+        contiguous, 'C' otherwise. 'K' means match the layout of `prototype`
+        as closely as possible.
+    subok : bool, optional.
+        If True, then the newly created array will use the sub-class
+        type of `prototype`, otherwise it will be a base-class array. Defaults
+        to True.
+    shape : int or sequence of ints, optional.
+        Overrides the shape of the result. If order='K' and the number of
+        dimensions is unchanged, will try to keep order, otherwise,
+        order='C' is implied.
+    device : str, optional
+        The device on which to place the created array. Default: None.
+        For Array-API interoperability only, so must be ``"cpu"`` if passed.
+
+        .. versionadded:: 2.0.0
+
+    Returns
+    -------
+    out : ndarray
+        Array of uninitialized (arbitrary) data with the same
+        shape and type as `prototype`.
+
+    See Also
+    --------
+    ones_like : Return an array of ones with shape and type of input.
+    zeros_like : Return an array of zeros with shape and type of input.
+    full_like : Return a new array with shape of input filled with value.
+    empty : Return a new uninitialized array.
+
+    Notes
+    -----
+    Unlike other array creation functions (e.g. `zeros_like`, `ones_like`,
+    `full_like`), `empty_like` does not initialize the values of the array,
+    and may therefore be marginally faster. However, the values stored in the
+    newly allocated array are arbitrary. For reproducible behavior, be sure
+    to set each element of the array before reading.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = ([1,2,3], [4,5,6])                         # a is array-like
+    >>> np.empty_like(a)
+    array([[-1073741821, -1073741821,           3],    # uninitialized
+           [          0,           0, -1073741821]])
+    >>> a = np.array([[1., 2., 3.],[4.,5.,6.]])
+    >>> np.empty_like(a)
+    array([[ -2.00000715e+000,   1.48219694e-323,  -2.00000572e+000], # uninitialized
+           [  4.38791518e-305,  -2.00000715e+000,   4.17269252e-309]])
+
+    """
+    return (prototype,)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.concatenate)
+def concatenate(arrays, axis=0, out=None, *, dtype=None, casting="same_kind"):
+    """
+    concatenate(
+        arrays,
+        /,
+        axis=0,
+        out=None,
+        *,
+        dtype=None,
+        casting="same_kind",
+    )
+    --
+
+    Join a sequence of arrays along an existing axis.
+
+    .. versionadded:: 2.0
+        ``numpy.concat`` added as a shorthand for ``numpy.concatenate``.
+
+    Parameters
+    ----------
+    a1, a2, ... : sequence of array_like
+        The arrays must have the same shape, except in the dimension
+        corresponding to `axis` (the first, by default).
+    axis : int, optional
+        The axis along which the arrays will be joined.  If axis is None,
+        arrays are flattened before use.  Default is 0.
+    out : ndarray, optional
+        If provided, the destination to place the result. The shape must be
+        correct, matching that of what concatenate would have returned if no
+        out argument were specified.
+    dtype : str or dtype
+        If provided, the destination array will have this dtype. Cannot be
+        provided together with `out`.
+
+        .. versionadded:: 1.20.0
+
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+        Controls what kind of data casting may occur. Defaults to 'same_kind'.
+        For a description of the options, please see :term:`casting`.
+
+        .. versionadded:: 1.20.0
+
+    Returns
+    -------
+    res : ndarray
+        The concatenated array.
+
+    See Also
+    --------
+    ma.concatenate : Concatenate function that preserves input masks.
+    array_split : Split an array into multiple sub-arrays of equal or
+                  near-equal size.
+    split : Split array into a list of multiple sub-arrays of equal size.
+    hsplit : Split array into multiple sub-arrays horizontally (column wise).
+    vsplit : Split array into multiple sub-arrays vertically (row wise).
+    dsplit : Split array into multiple sub-arrays along the 3rd axis (depth).
+    stack : Stack a sequence of arrays along a new axis.
+    block : Assemble arrays from blocks.
+    hstack : Stack arrays in sequence horizontally (column wise).
+    vstack : Stack arrays in sequence vertically (row wise).
+    dstack : Stack arrays in sequence depth wise (along third dimension).
+    column_stack : Stack 1-D arrays as columns into a 2-D array.
+
+    Notes
+    -----
+    When one or more of the arrays to be concatenated is a MaskedArray,
+    this function will return a MaskedArray object instead of an ndarray,
+    but the input masks are *not* preserved. In cases where a MaskedArray
+    is expected as input, use the ma.concatenate function from the masked
+    array module instead.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array([[1, 2], [3, 4]])
+    >>> b = np.array([[5, 6]])
+    >>> np.concatenate((a, b), axis=0)
+    array([[1, 2],
+           [3, 4],
+           [5, 6]])
+    >>> np.concatenate((a, b.T), axis=1)
+    array([[1, 2, 5],
+           [3, 4, 6]])
+    >>> np.concatenate((a, b), axis=None)
+    array([1, 2, 3, 4, 5, 6])
+
+    This function will not preserve masking of MaskedArray inputs.
+
+    >>> a = np.ma.arange(3)
+    >>> a[1] = np.ma.masked
+    >>> b = np.arange(2, 5)
+    >>> a
+    masked_array(data=[0, --, 2],
+                 mask=[False,  True, False],
+           fill_value=999999)
+    >>> b
+    array([2, 3, 4])
+    >>> np.concatenate([a, b])
+    masked_array(data=[0, 1, 2, 2, 3, 4],
+                 mask=False,
+           fill_value=999999)
+    >>> np.ma.concatenate([a, b])
+    masked_array(data=[0, --, 2, 2, 3, 4],
+                 mask=[False,  True, False, False, False, False],
+           fill_value=999999)
+
+    """
+    if out is not None:
+        # optimize for the typical case where only arrays is provided
+        arrays = list(arrays)
+        arrays.append(out)
+    return arrays
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.inner)
+def inner(a, b, /):
+    """
+    inner(a, b, /)
+
+    Inner product of two arrays.
+
+    Ordinary inner product of vectors for 1-D arrays (without complex
+    conjugation), in higher dimensions a sum product over the last axes.
+
+    Parameters
+    ----------
+    a, b : array_like
+        If `a` and `b` are nonscalar, their last dimensions must match.
+
+    Returns
+    -------
+    out : ndarray
+        If `a` and `b` are both
+        scalars or both 1-D arrays then a scalar is returned; otherwise
+        an array is returned.
+        ``out.shape = (*a.shape[:-1], *b.shape[:-1])``
+
+    Raises
+    ------
+    ValueError
+        If both `a` and `b` are nonscalar and their last dimensions have
+        different sizes.
+
+    See Also
+    --------
+    tensordot : Sum products over arbitrary axes.
+    dot : Generalised matrix product, using second last dimension of `b`.
+    vecdot : Vector dot product of two arrays.
+    einsum : Einstein summation convention.
+
+    Notes
+    -----
+    For vectors (1-D arrays) it computes the ordinary inner-product::
+
+        np.inner(a, b) = sum(a[:]*b[:])
+
+    More generally, if ``ndim(a) = r > 0`` and ``ndim(b) = s > 0``::
+
+        np.inner(a, b) = np.tensordot(a, b, axes=(-1,-1))
+
+    or explicitly::
+
+        np.inner(a, b)[i0,...,ir-2,j0,...,js-2]
+             = sum(a[i0,...,ir-2,:]*b[j0,...,js-2,:])
+
+    In addition `a` or `b` may be scalars, in which case::
+
+       np.inner(a,b) = a*b
+
+    Examples
+    --------
+    Ordinary inner product for vectors:
+
+    >>> import numpy as np
+    >>> a = np.array([1,2,3])
+    >>> b = np.array([0,1,0])
+    >>> np.inner(a, b)
+    2
+
+    Some multidimensional examples:
+
+    >>> a = np.arange(24).reshape((2,3,4))
+    >>> b = np.arange(4)
+    >>> c = np.inner(a, b)
+    >>> c.shape
+    (2, 3)
+    >>> c
+    array([[ 14,  38,  62],
+           [ 86, 110, 134]])
+
+    >>> a = np.arange(2).reshape((1,1,2))
+    >>> b = np.arange(6).reshape((3,2))
+    >>> c = np.inner(a, b)
+    >>> c.shape
+    (1, 1, 3)
+    >>> c
+    array([[[1, 3, 5]]])
+
+    An example where `b` is a scalar:
+
+    >>> np.inner(np.eye(2), 7)
+    array([[7., 0.],
+           [0., 7.]])
+
+    """
+    return (a, b)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.where)
+def where(condition, x=None, y=None, /):
+    """
+    where(condition, [x, y], /)
+
+    Return elements chosen from `x` or `y` depending on `condition`.
+
+    .. note::
+        When only `condition` is provided, this function is a shorthand for
+        ``np.asarray(condition).nonzero()``. Using `nonzero` directly should be
+        preferred, as it behaves correctly for subclasses. The rest of this
+        documentation covers only the case where all three arguments are
+        provided.
+
+    Parameters
+    ----------
+    condition : array_like, bool
+        Where True, yield `x`, otherwise yield `y`.
+    x, y : array_like
+        Values from which to choose. `x`, `y` and `condition` need to be
+        broadcastable to some shape.
+
+    Returns
+    -------
+    out : ndarray
+        An array with elements from `x` where `condition` is True, and elements
+        from `y` elsewhere.
+
+    See Also
+    --------
+    choose
+    nonzero : The function that is called when x and y are omitted
+
+    Notes
+    -----
+    If all the arrays are 1-D, `where` is equivalent to::
+
+        [xv if c else yv
+         for c, xv, yv in zip(condition, x, y)]
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.arange(10)
+    >>> a
+    array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+    >>> np.where(a < 5, a, 10*a)
+    array([ 0,  1,  2,  3,  4, 50, 60, 70, 80, 90])
+
+    This can be used on multidimensional arrays too:
+
+    >>> np.where([[True, False], [True, True]],
+    ...          [[1, 2], [3, 4]],
+    ...          [[9, 8], [7, 6]])
+    array([[1, 8],
+           [3, 4]])
+
+    The shapes of x, y, and the condition are broadcast together:
+
+    >>> x, y = np.ogrid[:3, :4]
+    >>> np.where(x < y, x, 10 + y)  # both x and 10+y are broadcast
+    array([[10,  0,  0,  0],
+           [10, 11,  1,  1],
+           [10, 11, 12,  2]])
+
+    >>> a = np.array([[0, 1, 2],
+    ...               [0, 2, 4],
+    ...               [0, 3, 6]])
+    >>> np.where(a < 4, a, -1)  # -1 is broadcast
+    array([[ 0,  1,  2],
+           [ 0,  2, -1],
+           [ 0,  3, -1]])
+    """
+    return (condition, x, y)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.lexsort)
+def lexsort(keys, axis=-1):
+    """
+    lexsort(keys, axis=-1)
+
+    Perform an indirect stable sort using a sequence of keys.
+
+    Given multiple sorting keys, lexsort returns an array of integer indices
+    that describes the sort order by multiple keys. The last key in the
+    sequence is used for the primary sort order, ties are broken by the
+    second-to-last key, and so on.
+
+    Parameters
+    ----------
+    keys : (k, m, n, ...) array-like
+        The `k` keys to be sorted. The *last* key (e.g, the last
+        row if `keys` is a 2D array) is the primary sort key.
+        Each element of `keys` along the zeroth axis must be
+        an array-like object of the same shape.
+    axis : int, optional
+        Axis to be indirectly sorted. By default, sort over the last axis
+        of each sequence. Separate slices along `axis` sorted over
+        independently; see last example.
+
+    Returns
+    -------
+    indices : (m, n, ...) ndarray of ints
+        Array of indices that sort the keys along the specified axis.
+
+    See Also
+    --------
+    argsort : Indirect sort.
+    ndarray.sort : In-place sort.
+    sort : Return a sorted copy of an array.
+
+    Examples
+    --------
+    Sort names: first by surname, then by name.
+
+    >>> import numpy as np
+    >>> surnames =    ('Hertz',    'Galilei', 'Hertz')
+    >>> first_names = ('Heinrich', 'Galileo', 'Gustav')
+    >>> ind = np.lexsort((first_names, surnames))
+    >>> ind
+    array([1, 2, 0])
+
+    >>> [surnames[i] + ", " + first_names[i] for i in ind]
+    ['Galilei, Galileo', 'Hertz, Gustav', 'Hertz, Heinrich']
+
+    Sort according to two numerical keys, first by elements
+    of ``a``, then breaking ties according to elements of ``b``:
+
+    >>> a = [1, 5, 1, 4, 3, 4, 4]  # First sequence
+    >>> b = [9, 4, 0, 4, 0, 2, 1]  # Second sequence
+    >>> ind = np.lexsort((b, a))  # Sort by `a`, then by `b`
+    >>> ind
+    array([2, 0, 4, 6, 5, 3, 1])
+    >>> [(a[i], b[i]) for i in ind]
+    [(1, 0), (1, 9), (3, 0), (4, 1), (4, 2), (4, 4), (5, 4)]
+
+    Compare against `argsort`, which would sort each key independently.
+
+    >>> np.argsort((b, a), kind='stable')
+    array([[2, 4, 6, 5, 1, 3, 0],
+           [0, 2, 4, 3, 5, 6, 1]])
+
+    To sort lexicographically with `argsort`, we would need to provide a
+    structured array.
+
+    >>> x = np.array([(ai, bi) for ai, bi in zip(a, b)],
+    ...              dtype = np.dtype([('x', int), ('y', int)]))
+    >>> np.argsort(x)  # or np.argsort(x, order=('x', 'y'))
+    array([2, 0, 4, 6, 5, 3, 1])
+
+    The zeroth axis of `keys` always corresponds with the sequence of keys,
+    so 2D arrays are treated just like other sequences of keys.
+
+    >>> arr = np.asarray([b, a])
+    >>> ind2 = np.lexsort(arr)
+    >>> np.testing.assert_equal(ind2, ind)
+
+    Accordingly, the `axis` parameter refers to an axis of *each* key, not of
+    the `keys` argument itself. For instance, the array ``arr`` is treated as
+    a sequence of two 1-D keys, so specifying ``axis=0`` is equivalent to
+    using the default axis, ``axis=-1``.
+
+    >>> np.testing.assert_equal(np.lexsort(arr, axis=0),
+    ...                         np.lexsort(arr, axis=-1))
+
+    For higher-dimensional arrays, the axis parameter begins to matter. The
+    resulting array has the same shape as each key, and the values are what
+    we would expect if `lexsort` were performed on corresponding slices
+    of the keys independently. For instance,
+
+    >>> x = [[1, 2, 3, 4],
+    ...      [4, 3, 2, 1],
+    ...      [2, 1, 4, 3]]
+    >>> y = [[2, 2, 1, 1],
+    ...      [1, 2, 1, 2],
+    ...      [1, 1, 2, 1]]
+    >>> np.lexsort((x, y), axis=1)
+    array([[2, 3, 0, 1],
+           [2, 0, 3, 1],
+           [1, 0, 3, 2]])
+
+    Each row of the result is what we would expect if we were to perform
+    `lexsort` on the corresponding row of the keys:
+
+    >>> for i in range(3):
+    ...     print(np.lexsort((x[i], y[i])))
+    [2 3 0 1]
+    [2 0 3 1]
+    [1 0 3 2]
+
+    """
+    if isinstance(keys, tuple):
+        return keys
+    else:
+        return (keys,)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.can_cast)
+def can_cast(from_, to, casting="safe"):
+    """
+    can_cast(from_, to, casting='safe')
+
+    Returns True if cast between data types can occur according to the
+    casting rule.
+
+    Parameters
+    ----------
+    from_ : dtype, dtype specifier, NumPy scalar, or array
+        Data type, NumPy scalar, or array to cast from.
+    to : dtype or dtype specifier
+        Data type to cast to.
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+        Controls what kind of data casting may occur.
+
+        * 'no' means the data types should not be cast at all.
+        * 'equiv' means only byte-order changes are allowed.
+        * 'safe' means only casts which can preserve values are allowed.
+        * 'same_kind' means only safe casts or casts within a kind,
+          like float64 to float32, are allowed.
+        * 'unsafe' means any data conversions may be done.
+
+    Returns
+    -------
+    out : bool
+        True if cast can occur according to the casting rule.
+
+    Notes
+    -----
+    .. versionchanged:: 2.0
+       This function does not support Python scalars anymore and does not
+       apply any value-based logic for 0-D arrays and NumPy scalars.
+
+    See also
+    --------
+    dtype, result_type
+
+    Examples
+    --------
+    Basic examples
+
+    >>> import numpy as np
+    >>> np.can_cast(np.int32, np.int64)
+    True
+    >>> np.can_cast(np.float64, complex)
+    True
+    >>> np.can_cast(complex, float)
+    False
+
+    >>> np.can_cast('i8', 'f8')
+    True
+    >>> np.can_cast('i8', 'f4')
+    False
+    >>> np.can_cast('i4', 'S4')
+    False
+
+    """
+    return (from_,)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.min_scalar_type)
+def min_scalar_type(a, /):
+    """
+    min_scalar_type(a, /)
+
+    For scalar ``a``, returns the data type with the smallest size
+    and smallest scalar kind which can hold its value.  For non-scalar
+    array ``a``, returns the vector's dtype unmodified.
+
+    Floating point values are not demoted to integers,
+    and complex values are not demoted to floats.
+
+    Parameters
+    ----------
+    a : scalar or array_like
+        The value whose minimal data type is to be found.
+
+    Returns
+    -------
+    out : dtype
+        The minimal data type.
+
+    See Also
+    --------
+    result_type, promote_types, dtype, can_cast
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.min_scalar_type(10)
+    dtype('uint8')
+
+    >>> np.min_scalar_type(-260)
+    dtype('int16')
+
+    >>> np.min_scalar_type(3.1)
+    dtype('float16')
+
+    >>> np.min_scalar_type(1e50)
+    dtype('float64')
+
+    >>> np.min_scalar_type(np.arange(4, dtype=np.float64))
+    dtype('float64')
+
+    """
+    return (a,)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.result_type)
+def result_type(*arrays_and_dtypes):
+    """
+    result_type(*arrays_and_dtypes)
+
+    Returns the type that results from applying the NumPy
+    :ref:`type promotion <arrays.promotion>` rules to the arguments.
+
+    Parameters
+    ----------
+    arrays_and_dtypes : list of arrays and dtypes
+        The operands of some operation whose result type is needed.
+
+    Returns
+    -------
+    out : dtype
+        The result type.
+
+    See also
+    --------
+    dtype, promote_types, min_scalar_type, can_cast
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.result_type(3, np.arange(7, dtype=np.int8))
+    dtype('int8')
+
+    >>> np.result_type(np.int32, np.complex64)
+    dtype('complex128')
+
+    >>> np.result_type(3.0, -2)
+    dtype('float64')
+
+    """
+    return arrays_and_dtypes
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.dot)
+def dot(a, b, out=None):
+    """
+    dot(a, b, out=None)
+
+    Dot product of two arrays. Specifically,
+
+    - If both `a` and `b` are 1-D arrays, it is inner product of vectors
+      (without complex conjugation).
+
+    - If both `a` and `b` are 2-D arrays, it is matrix multiplication,
+      but using :func:`matmul` or ``a @ b`` is preferred.
+
+    - If either `a` or `b` is 0-D (scalar), it is equivalent to
+      :func:`multiply` and using ``numpy.multiply(a, b)`` or ``a * b`` is
+      preferred.
+
+    - If `a` is an N-D array and `b` is a 1-D array, it is a sum product over
+      the last axis of `a` and `b`.
+
+    - If `a` is an N-D array and `b` is an M-D array (where ``M>=2``), it is a
+      sum product over the last axis of `a` and the second-to-last axis of
+      `b`::
+
+        dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m])
+
+    It uses an optimized BLAS library when possible (see `numpy.linalg`).
+
+    Parameters
+    ----------
+    a : array_like
+        First argument.
+    b : array_like
+        Second argument.
+    out : ndarray, optional
+        Output argument. This must have the exact kind that would be returned
+        if it was not used. In particular, it must have the right type, must be
+        C-contiguous, and its dtype must be the dtype that would be returned
+        for `dot(a,b)`. This is a performance feature. Therefore, if these
+        conditions are not met, an exception is raised, instead of attempting
+        to be flexible.
+
+    Returns
+    -------
+    output : ndarray
+        Returns the dot product of `a` and `b`.  If `a` and `b` are both
+        scalars or both 1-D arrays then a scalar is returned; otherwise
+        an array is returned.
+        If `out` is given, then it is returned.
+
+    Raises
+    ------
+    ValueError
+        If the last dimension of `a` is not the same size as
+        the second-to-last dimension of `b`.
+
+    See Also
+    --------
+    vdot : Complex-conjugating dot product.
+    vecdot : Vector dot product of two arrays.
+    tensordot : Sum products over arbitrary axes.
+    einsum : Einstein summation convention.
+    matmul : '@' operator as method with out parameter.
+    linalg.multi_dot : Chained dot product.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.dot(3, 4)
+    12
+
+    Neither argument is complex-conjugated:
+
+    >>> np.dot([2j, 3j], [2j, 3j])
+    (-13+0j)
+
+    For 2-D arrays it is the matrix product:
+
+    >>> a = [[1, 0], [0, 1]]
+    >>> b = [[4, 1], [2, 2]]
+    >>> np.dot(a, b)
+    array([[4, 1],
+           [2, 2]])
+
+    >>> a = np.arange(3*4*5*6).reshape((3,4,5,6))
+    >>> b = np.arange(3*4*5*6)[::-1].reshape((5,4,6,3))
+    >>> np.dot(a, b)[2,3,2,1,2,2]
+    499128
+    >>> sum(a[2,3,2,:] * b[1,2,:,2])
+    499128
+
+    """
+    return (a, b, out)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.vdot)
+def vdot(a, b, /):
+    r"""
+    vdot(a, b, /)
+
+    Return the dot product of two vectors.
+
+    The `vdot` function handles complex numbers differently than `dot`:
+    if the first argument is complex, it is replaced by its complex conjugate
+    in the dot product calculation. `vdot` also handles multidimensional
+    arrays differently than `dot`: it does not perform a matrix product, but
+    flattens the arguments to 1-D arrays before taking a vector dot product.
+
+    Consequently, when the arguments are 2-D arrays of the same shape, this
+    function effectively returns their
+    `Frobenius inner product <https://en.wikipedia.org/wiki/Frobenius_inner_product>`_
+    (also known as the *trace inner product* or the *standard inner product*
+    on a vector space of matrices).
+
+    Parameters
+    ----------
+    a : array_like
+        If `a` is complex the complex conjugate is taken before calculation
+        of the dot product.
+    b : array_like
+        Second argument to the dot product.
+
+    Returns
+    -------
+    output : ndarray
+        Dot product of `a` and `b`.  Can be an int, float, or
+        complex depending on the types of `a` and `b`.
+
+    See Also
+    --------
+    dot : Return the dot product without using the complex conjugate of the
+          first argument.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array([1+2j,3+4j])
+    >>> b = np.array([5+6j,7+8j])
+    >>> np.vdot(a, b)
+    (70-8j)
+    >>> np.vdot(b, a)
+    (70+8j)
+
+    Note that higher-dimensional arrays are flattened!
+
+    >>> a = np.array([[1, 4], [5, 6]])
+    >>> b = np.array([[4, 1], [2, 2]])
+    >>> np.vdot(a, b)
+    30
+    >>> np.vdot(b, a)
+    30
+    >>> 1*4 + 4*1 + 5*2 + 6*2
+    30
+
+    """
+    return (a, b)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.bincount)
+def bincount(x, /, weights=None, minlength=0):
+    """
+    bincount(x, /, weights=None, minlength=0)
+
+    Count number of occurrences of each value in array of non-negative ints.
+
+    The number of bins (of size 1) is one larger than the largest value in
+    `x`. If `minlength` is specified, there will be at least this number
+    of bins in the output array (though it will be longer if necessary,
+    depending on the contents of `x`).
+    Each bin gives the number of occurrences of its index value in `x`.
+    If `weights` is specified the input array is weighted by it, i.e. if a
+    value ``n`` is found at position ``i``, ``out[n] += weight[i]`` instead
+    of ``out[n] += 1``.
+
+    Parameters
+    ----------
+    x : array_like, 1 dimension, nonnegative ints
+        Input array.
+    weights : array_like, optional
+        Weights, array of the same shape as `x`.
+    minlength : int, optional
+        A minimum number of bins for the output array.
+
+    Returns
+    -------
+    out : ndarray of ints
+        The result of binning the input array.
+        The length of `out` is equal to ``np.amax(x)+1``.
+
+    Raises
+    ------
+    ValueError
+        If the input is not 1-dimensional, or contains elements with negative
+        values, or if `minlength` is negative.
+    TypeError
+        If the type of the input is float or complex.
+
+    See Also
+    --------
+    histogram, digitize, unique
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.bincount(np.arange(5))
+    array([1, 1, 1, 1, 1])
+    >>> np.bincount(np.array([0, 1, 1, 3, 2, 1, 7]))
+    array([1, 3, 1, 1, 0, 0, 0, 1])
+
+    >>> x = np.array([0, 1, 1, 3, 2, 1, 7, 23])
+    >>> np.bincount(x).size == np.amax(x)+1
+    True
+
+    The input array needs to be of integer dtype, otherwise a
+    TypeError is raised:
+
+    >>> np.bincount(np.arange(5, dtype=np.float64))
+    Traceback (most recent call last):
+      ...
+    TypeError: Cannot cast array data from dtype('float64') to dtype('int64')
+    according to the rule 'safe'
+
+    A possible use of ``bincount`` is to perform sums over
+    variable-size chunks of an array, using the ``weights`` keyword.
+
+    >>> w = np.array([0.3, 0.5, 0.2, 0.7, 1., -0.6]) # weights
+    >>> x = np.array([0, 1, 1, 2, 2, 2])
+    >>> np.bincount(x,  weights=w)
+    array([ 0.3,  0.7,  1.1])
+
+    """
+    return (x, weights)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.ravel_multi_index)
+def ravel_multi_index(multi_index, dims, mode="raise", order="C"):
+    """
+    ravel_multi_index(multi_index, dims, mode='raise', order='C')
+
+    Converts a tuple of index arrays into an array of flat
+    indices, applying boundary modes to the multi-index.
+
+    Parameters
+    ----------
+    multi_index : tuple of array_like
+        A tuple of integer arrays, one array for each dimension.
+    dims : tuple of ints
+        The shape of array into which the indices from ``multi_index`` apply.
+    mode : {'raise', 'wrap', 'clip'}, optional
+        Specifies how out-of-bounds indices are handled.  Can specify
+        either one mode or a tuple of modes, one mode per index.
+
+        * 'raise' -- raise an error (default)
+        * 'wrap' -- wrap around
+        * 'clip' -- clip to the range
+
+        In 'clip' mode, a negative index which would normally
+        wrap will clip to 0 instead.
+    order : {'C', 'F'}, optional
+        Determines whether the multi-index should be viewed as
+        indexing in row-major (C-style) or column-major
+        (Fortran-style) order.
+
+    Returns
+    -------
+    raveled_indices : ndarray
+        An array of indices into the flattened version of an array
+        of dimensions ``dims``.
+
+    See Also
+    --------
+    unravel_index
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> arr = np.array([[3,6,6],[4,5,1]])
+    >>> np.ravel_multi_index(arr, (7,6))
+    array([22, 41, 37])
+    >>> np.ravel_multi_index(arr, (7,6), order='F')
+    array([31, 41, 13])
+    >>> np.ravel_multi_index(arr, (4,6), mode='clip')
+    array([22, 23, 19])
+    >>> np.ravel_multi_index(arr, (4,4), mode=('clip','wrap'))
+    array([12, 13, 13])
+
+    >>> np.ravel_multi_index((3,1,4,1), (6,7,8,9))
+    1621
+    """
+    return multi_index
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.unravel_index)
+def unravel_index(indices, shape, order="C"):
+    """
+    unravel_index(indices, shape, order='C')
+
+    Converts a flat index or array of flat indices into a tuple
+    of coordinate arrays.
+
+    Parameters
+    ----------
+    indices : array_like
+        An integer array whose elements are indices into the flattened
+        version of an array of dimensions ``shape``. Before version 1.6.0,
+        this function accepted just one index value.
+    shape : tuple of ints
+        The shape of the array to use for unraveling ``indices``.
+    order : {'C', 'F'}, optional
+        Determines whether the indices should be viewed as indexing in
+        row-major (C-style) or column-major (Fortran-style) order.
+
+    Returns
+    -------
+    unraveled_coords : tuple of ndarray
+        Each array in the tuple has the same shape as the ``indices``
+        array.
+
+    See Also
+    --------
+    ravel_multi_index
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.unravel_index([22, 41, 37], (7,6))
+    (array([3, 6, 6]), array([4, 5, 1]))
+    >>> np.unravel_index([31, 41, 13], (7,6), order='F')
+    (array([3, 6, 6]), array([4, 5, 1]))
+
+    >>> np.unravel_index(1621, (6,7,8,9))
+    (3, 1, 4, 1)
+
+    """
+    return (indices,)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.copyto)
+def copyto(dst, src, casting="same_kind", where=True):
+    """
+    copyto(dst, src, casting='same_kind', where=True)
+
+    Copies values from one array to another, broadcasting as necessary.
+
+    Raises a TypeError if the `casting` rule is violated, and if
+    `where` is provided, it selects which elements to copy.
+
+    Parameters
+    ----------
+    dst : ndarray
+        The array into which values are copied.
+    src : array_like
+        The array from which values are copied.
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+        Controls what kind of data casting may occur when copying.
+
+        * 'no' means the data types should not be cast at all.
+        * 'equiv' means only byte-order changes are allowed.
+        * 'safe' means only casts which can preserve values are allowed.
+        * 'same_kind' means only safe casts or casts within a kind,
+          like float64 to float32, are allowed.
+        * 'unsafe' means any data conversions may be done.
+    where : array_like of bool, optional
+        A boolean array which is broadcasted to match the dimensions
+        of `dst`, and selects elements to copy from `src` to `dst`
+        wherever it contains the value True.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> A = np.array([4, 5, 6])
+    >>> B = [1, 2, 3]
+    >>> np.copyto(A, B)
+    >>> A
+    array([1, 2, 3])
+
+    >>> A = np.array([[1, 2, 3], [4, 5, 6]])
+    >>> B = [[4, 5, 6], [7, 8, 9]]
+    >>> np.copyto(A, B)
+    >>> A
+    array([[4, 5, 6],
+           [7, 8, 9]])
+
+    """
+    return (dst, src, where)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.putmask)
+def putmask(a, /, mask, values):
+    """
+    putmask(a, /, mask, values)
+
+    Changes elements of an array based on conditional and input values.
+
+    Sets ``a.flat[n] = values[n]`` for each n where ``mask.flat[n]==True``.
+
+    If `values` is not the same size as `a` and `mask` then it will repeat.
+    This gives behavior different from ``a[mask] = values``.
+
+    Parameters
+    ----------
+    a : ndarray
+        Target array.
+    mask : array_like
+        Boolean mask array. It has to be the same shape as `a`.
+    values : array_like
+        Values to put into `a` where `mask` is True. If `values` is smaller
+        than `a` it will be repeated.
+
+    See Also
+    --------
+    place, put, take, copyto
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.arange(6).reshape(2, 3)
+    >>> np.putmask(x, x>2, x**2)
+    >>> x
+    array([[ 0,  1,  2],
+           [ 9, 16, 25]])
+
+    If `values` is smaller than `a` it is repeated:
+
+    >>> x = np.arange(5)
+    >>> np.putmask(x, x>1, [-33, -44])
+    >>> x
+    array([  0,   1, -33, -44, -33])
+
+    """
+    return (a, mask, values)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.packbits)
+def packbits(a, /, axis=None, bitorder="big"):
+    """
+    packbits(a, /, axis=None, bitorder='big')
+
+    Packs the elements of a binary-valued array into bits in a uint8 array.
+
+    The result is padded to full bytes by inserting zero bits at the end.
+
+    Parameters
+    ----------
+    a : array_like
+        An array of integers or booleans whose elements should be packed to
+        bits.
+    axis : int, optional
+        The dimension over which bit-packing is done.
+        ``None`` implies packing the flattened array.
+    bitorder : {'big', 'little'}, optional
+        The order of the input bits. 'big' will mimic bin(val),
+        ``[0, 0, 0, 0, 0, 0, 1, 1] => 3 = 0b00000011``, 'little' will
+        reverse the order so ``[1, 1, 0, 0, 0, 0, 0, 0] => 3``.
+        Defaults to 'big'.
+
+    Returns
+    -------
+    packed : ndarray
+        Array of type uint8 whose elements represent bits corresponding to the
+        logical (0 or nonzero) value of the input elements. The shape of
+        `packed` has the same number of dimensions as the input (unless `axis`
+        is None, in which case the output is 1-D).
+
+    See Also
+    --------
+    unpackbits: Unpacks elements of a uint8 array into a binary-valued output
+                array.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array([[[1,0,1],
+    ...                [0,1,0]],
+    ...               [[1,1,0],
+    ...                [0,0,1]]])
+    >>> b = np.packbits(a, axis=-1)
+    >>> b
+    array([[[160],
+            [ 64]],
+           [[192],
+            [ 32]]], dtype=uint8)
+
+    Note that in binary 160 = 1010 0000, 64 = 0100 0000, 192 = 1100 0000,
+    and 32 = 0010 0000.
+
+    """
+    return (a,)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.unpackbits)
+def unpackbits(a, /, axis=None, count=None, bitorder="big"):
+    """
+    unpackbits(a, /, axis=None, count=None, bitorder='big')
+
+    Unpacks elements of a uint8 array into a binary-valued output array.
+
+    Each element of `a` represents a bit-field that should be unpacked
+    into a binary-valued output array. The shape of the output array is
+    either 1-D (if `axis` is ``None``) or the same shape as the input
+    array with unpacking done along the axis specified.
+
+    Parameters
+    ----------
+    a : ndarray, uint8 type
+       Input array.
+    axis : int, optional
+        The dimension over which bit-unpacking is done.
+        ``None`` implies unpacking the flattened array.
+    count : int or None, optional
+        The number of elements to unpack along `axis`, provided as a way
+        of undoing the effect of packing a size that is not a multiple
+        of eight. A non-negative number means to only unpack `count`
+        bits. A negative number means to trim off that many bits from
+        the end. ``None`` means to unpack the entire array (the
+        default). Counts larger than the available number of bits will
+        add zero padding to the output. Negative counts must not
+        exceed the available number of bits.
+    bitorder : {'big', 'little'}, optional
+        The order of the returned bits. 'big' will mimic bin(val),
+        ``3 = 0b00000011 => [0, 0, 0, 0, 0, 0, 1, 1]``, 'little' will reverse
+        the order to ``[1, 1, 0, 0, 0, 0, 0, 0]``.
+        Defaults to 'big'.
+
+    Returns
+    -------
+    unpacked : ndarray, uint8 type
+       The elements are binary-valued (0 or 1).
+
+    See Also
+    --------
+    packbits : Packs the elements of a binary-valued array into bits in
+               a uint8 array.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array([[2], [7], [23]], dtype=np.uint8)
+    >>> a
+    array([[ 2],
+           [ 7],
+           [23]], dtype=uint8)
+    >>> b = np.unpackbits(a, axis=1)
+    >>> b
+    array([[0, 0, 0, 0, 0, 0, 1, 0],
+           [0, 0, 0, 0, 0, 1, 1, 1],
+           [0, 0, 0, 1, 0, 1, 1, 1]], dtype=uint8)
+    >>> c = np.unpackbits(a, axis=1, count=-3)
+    >>> c
+    array([[0, 0, 0, 0, 0],
+           [0, 0, 0, 0, 0],
+           [0, 0, 0, 1, 0]], dtype=uint8)
+
+    >>> p = np.packbits(b, axis=0)
+    >>> np.unpackbits(p, axis=0)
+    array([[0, 0, 0, 0, 0, 0, 1, 0],
+           [0, 0, 0, 0, 0, 1, 1, 1],
+           [0, 0, 0, 1, 0, 1, 1, 1],
+           [0, 0, 0, 0, 0, 0, 0, 0],
+           [0, 0, 0, 0, 0, 0, 0, 0],
+           [0, 0, 0, 0, 0, 0, 0, 0],
+           [0, 0, 0, 0, 0, 0, 0, 0],
+           [0, 0, 0, 0, 0, 0, 0, 0]], dtype=uint8)
+    >>> np.array_equal(b, np.unpackbits(p, axis=0, count=b.shape[0]))
+    True
+
+    """
+    return (a,)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.shares_memory)
+def shares_memory(a, b, /, max_work=-1):
+    """
+    shares_memory(a, b, /, max_work=-1)
+
+    Determine if two arrays share memory.
+
+    .. warning::
+
+       This function can be exponentially slow for some inputs, unless
+       `max_work` is set to zero or a positive integer.
+       If in doubt, use `numpy.may_share_memory` instead.
+
+    Parameters
+    ----------
+    a, b : ndarray
+        Input arrays
+    max_work : int, optional
+        Effort to spend on solving the overlap problem (maximum number
+        of candidate solutions to consider). The following special
+        values are recognized:
+
+        max_work=-1 (default)
+            The problem is solved exactly. In this case, the function returns
+            True only if there is an element shared between the arrays. Finding
+            the exact solution may take extremely long in some cases.
+        max_work=0
+            Only the memory bounds of a and b are checked.
+            This is equivalent to using ``may_share_memory()``.
+
+    Raises
+    ------
+    numpy.exceptions.TooHardError
+        Exceeded max_work.
+
+    Returns
+    -------
+    out : bool
+
+    See Also
+    --------
+    may_share_memory
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.array([1, 2, 3, 4])
+    >>> np.shares_memory(x, np.array([5, 6, 7]))
+    False
+    >>> np.shares_memory(x[::2], x)
+    True
+    >>> np.shares_memory(x[::2], x[1::2])
+    False
+
+    Checking whether two arrays share memory is NP-complete, and
+    runtime may increase exponentially in the number of
+    dimensions. Hence, `max_work` should generally be set to a finite
+    number, as it is possible to construct examples that take
+    extremely long to run:
+
+    >>> from numpy.lib.stride_tricks import as_strided
+    >>> x = np.zeros([192163377], dtype=np.int8)
+    >>> x1 = as_strided(
+    ...     x, strides=(36674, 61119, 85569), shape=(1049, 1049, 1049))
+    >>> x2 = as_strided(
+    ...     x[64023025:], strides=(12223, 12224, 1), shape=(1049, 1049, 1))
+    >>> np.shares_memory(x1, x2, max_work=1000)
+    Traceback (most recent call last):
+    ...
+    numpy.exceptions.TooHardError: Exceeded max_work
+
+    Running ``np.shares_memory(x1, x2)`` without `max_work` set takes
+    around 1 minute for this case. It is possible to find problems
+    that take still significantly longer.
+
+    """
+    return (a, b)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.may_share_memory)
+def may_share_memory(a, b, /, max_work=0):
+    """
+    may_share_memory(a, b, /, max_work=0)
+
+    Determine if two arrays might share memory
+
+    A return of True does not necessarily mean that the two arrays
+    share any element.  It just means that they *might*.
+
+    Only the memory bounds of a and b are checked by default.
+
+    Parameters
+    ----------
+    a, b : ndarray
+        Input arrays
+    max_work : int, optional
+        Effort to spend on solving the overlap problem.  See
+        `shares_memory` for details.  Default for ``may_share_memory``
+        is to do a bounds check.
+
+    Returns
+    -------
+    out : bool
+
+    See Also
+    --------
+    shares_memory
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.may_share_memory(np.array([1,2]), np.array([5,8,9]))
+    False
+    >>> x = np.zeros([3, 4])
+    >>> np.may_share_memory(x[:,0], x[:,1])
+    True
+
+    """
+    return (a, b)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.is_busday)
+def is_busday(dates, weekmask="1111100", holidays=None, busdaycal=None, out=None):
+    """
+    is_busday(
+        dates,
+        weekmask='1111100',
+        holidays=None,
+        busdaycal=None,
+        out=None,
+    )
+
+    Calculates which of the given dates are valid days, and which are not.
+
+    Parameters
+    ----------
+    dates : array_like of datetime64[D]
+        The array of dates to process.
+    weekmask : str or array_like of bool, optional
+        A seven-element array indicating which of Monday through Sunday are
+        valid days. May be specified as a length-seven list or array, like
+        [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string
+        like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for
+        weekdays, optionally separated by white space. Valid abbreviations
+        are: Mon Tue Wed Thu Fri Sat Sun
+    holidays : array_like of datetime64[D], optional
+        An array of dates to consider as invalid dates.  They may be
+        specified in any order, and NaT (not-a-time) dates are ignored.
+        This list is saved in a normalized form that is suited for
+        fast calculations of valid days.
+    busdaycal : busdaycalendar, optional
+        A `busdaycalendar` object which specifies the valid days. If this
+        parameter is provided, neither weekmask nor holidays may be
+        provided.
+    out : array of bool, optional
+        If provided, this array is filled with the result.
+
+    Returns
+    -------
+    out : array of bool
+        An array with the same shape as ``dates``, containing True for
+        each valid day, and False for each invalid day.
+
+    See Also
+    --------
+    busdaycalendar : An object that specifies a custom set of valid days.
+    busday_offset : Applies an offset counted in valid days.
+    busday_count : Counts how many valid days are in a half-open date range.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # The weekdays are Friday, Saturday, and Monday
+    ... np.is_busday(['2011-07-01', '2011-07-02', '2011-07-18'],
+    ...                 holidays=['2011-07-01', '2011-07-04', '2011-07-17'])
+    array([False, False,  True])
+    """
+    return (dates, weekmask, holidays, out)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.busday_offset)
+def busday_offset(dates, offsets, roll="raise", weekmask="1111100", holidays=None,
+                  busdaycal=None, out=None):
+    """
+    busday_offset(
+        dates,
+        offsets,
+        roll='raise',
+        weekmask='1111100',
+        holidays=None,
+        busdaycal=None,
+        out=None,
+    )
+
+    First adjusts the date to fall on a valid day according to
+    the ``roll`` rule, then applies offsets to the given dates
+    counted in valid days.
+
+    Parameters
+    ----------
+    dates : array_like of datetime64[D]
+        The array of dates to process.
+    offsets : array_like of int
+        The array of offsets, which is broadcast with ``dates``.
+    roll : {'raise', 'nat', 'forward', 'following', 'backward', 'preceding', \
+        'modifiedfollowing', 'modifiedpreceding'}, optional
+        How to treat dates that do not fall on a valid day. The default
+        is 'raise'.
+
+        * 'raise' means to raise an exception for an invalid day.
+        * 'nat' means to return a NaT (not-a-time) for an invalid day.
+        * 'forward' and 'following' mean to take the first valid day
+          later in time.
+        * 'backward' and 'preceding' mean to take the first valid day
+          earlier in time.
+        * 'modifiedfollowing' means to take the first valid day
+          later in time unless it is across a Month boundary, in which
+          case to take the first valid day earlier in time.
+        * 'modifiedpreceding' means to take the first valid day
+          earlier in time unless it is across a Month boundary, in which
+          case to take the first valid day later in time.
+    weekmask : str or array_like of bool, optional
+        A seven-element array indicating which of Monday through Sunday are
+        valid days. May be specified as a length-seven list or array, like
+        [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string
+        like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for
+        weekdays, optionally separated by white space. Valid abbreviations
+        are: Mon Tue Wed Thu Fri Sat Sun
+    holidays : array_like of datetime64[D], optional
+        An array of dates to consider as invalid dates.  They may be
+        specified in any order, and NaT (not-a-time) dates are ignored.
+        This list is saved in a normalized form that is suited for
+        fast calculations of valid days.
+    busdaycal : busdaycalendar, optional
+        A `busdaycalendar` object which specifies the valid days. If this
+        parameter is provided, neither weekmask nor holidays may be
+        provided.
+    out : array of datetime64[D], optional
+        If provided, this array is filled with the result.
+
+    Returns
+    -------
+    out : array of datetime64[D]
+        An array with a shape from broadcasting ``dates`` and ``offsets``
+        together, containing the dates with offsets applied.
+
+    See Also
+    --------
+    busdaycalendar : An object that specifies a custom set of valid days.
+    is_busday : Returns a boolean array indicating valid days.
+    busday_count : Counts how many valid days are in a half-open date range.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # First business day in October 2011 (not accounting for holidays)
+    ... np.busday_offset('2011-10', 0, roll='forward')
+    np.datetime64('2011-10-03')
+    >>> # Last business day in February 2012 (not accounting for holidays)
+    ... np.busday_offset('2012-03', -1, roll='forward')
+    np.datetime64('2012-02-29')
+    >>> # Third Wednesday in January 2011
+    ... np.busday_offset('2011-01', 2, roll='forward', weekmask='Wed')
+    np.datetime64('2011-01-19')
+    >>> # 2012 Mother's Day in Canada and the U.S.
+    ... np.busday_offset('2012-05', 1, roll='forward', weekmask='Sun')
+    np.datetime64('2012-05-13')
+
+    >>> # First business day on or after a date
+    ... np.busday_offset('2011-03-20', 0, roll='forward')
+    np.datetime64('2011-03-21')
+    >>> np.busday_offset('2011-03-22', 0, roll='forward')
+    np.datetime64('2011-03-22')
+    >>> # First business day after a date
+    ... np.busday_offset('2011-03-20', 1, roll='backward')
+    np.datetime64('2011-03-21')
+    >>> np.busday_offset('2011-03-22', 1, roll='backward')
+    np.datetime64('2011-03-23')
+    """
+    return (dates, offsets, weekmask, holidays, out)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.busday_count)
+def busday_count(begindates, enddates, weekmask="1111100", holidays=(),
+                 busdaycal=None, out=None):
+    """
+    busday_count(
+        begindates,
+        enddates,
+        weekmask='1111100',
+        holidays=[],
+        busdaycal=None,
+        out=None
+    )
+
+    Counts the number of valid days between `begindates` and
+    `enddates`, not including the day of `enddates`.
+
+    If ``enddates`` specifies a date value that is earlier than the
+    corresponding ``begindates`` date value, the count will be negative.
+
+    Parameters
+    ----------
+    begindates : array_like of datetime64[D]
+        The array of the first dates for counting.
+    enddates : array_like of datetime64[D]
+        The array of the end dates for counting, which are excluded
+        from the count themselves.
+    weekmask : str or array_like of bool, optional
+        A seven-element array indicating which of Monday through Sunday are
+        valid days. May be specified as a length-seven list or array, like
+        [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string
+        like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for
+        weekdays, optionally separated by white space. Valid abbreviations
+        are: Mon Tue Wed Thu Fri Sat Sun
+    holidays : array_like of datetime64[D], optional
+        An array of dates to consider as invalid dates.  They may be
+        specified in any order, and NaT (not-a-time) dates are ignored.
+        This list is saved in a normalized form that is suited for
+        fast calculations of valid days.
+    busdaycal : busdaycalendar, optional
+        A `busdaycalendar` object which specifies the valid days. If this
+        parameter is provided, neither weekmask nor holidays may be
+        provided.
+    out : array of int, optional
+        If provided, this array is filled with the result.
+
+    Returns
+    -------
+    out : array of int
+        An array with a shape from broadcasting ``begindates`` and ``enddates``
+        together, containing the number of valid days between
+        the begin and end dates.
+
+    See Also
+    --------
+    busdaycalendar : An object that specifies a custom set of valid days.
+    is_busday : Returns a boolean array indicating valid days.
+    busday_offset : Applies an offset counted in valid days.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> # Number of weekdays in January 2011
+    ... np.busday_count('2011-01', '2011-02')
+    21
+    >>> # Number of weekdays in 2011
+    >>> np.busday_count('2011', '2012')
+    260
+    >>> # Number of Saturdays in 2011
+    ... np.busday_count('2011', '2012', weekmask='Sat')
+    53
+    """
+    return (begindates, enddates, weekmask, holidays, out)
+
+
+@array_function_from_c_func_and_dispatcher(_multiarray_umath.datetime_as_string)
+def datetime_as_string(arr, unit=None, timezone="naive", casting="same_kind"):
+    """
+    datetime_as_string(arr, unit=None, timezone='naive', casting='same_kind')
+
+    Convert an array of datetimes into an array of strings.
+
+    Parameters
+    ----------
+    arr : array_like of datetime64
+        The array of UTC timestamps to format.
+    unit : str
+        One of None, 'auto', or
+        a :ref:`datetime unit <arrays.dtypes.dateunits>`.
+    timezone : {'naive', 'UTC', 'local'} or tzinfo
+        Timezone information to use when displaying the datetime. If 'UTC',
+        end with a Z to indicate UTC time. If 'local', convert to the local
+        timezone first, and suffix with a +-#### timezone offset. If a tzinfo
+        object, then do as with 'local', but use the specified timezone.
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}
+        Casting to allow when changing between datetime units.
+
+    Returns
+    -------
+    str_arr : ndarray
+        An array of strings the same shape as `arr`.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from zoneinfo import ZoneInfo
+    >>> d = np.arange('2002-10-27T04:30', 4*60, 60, dtype='M8[m]')
+    >>> d
+    array(['2002-10-27T04:30', '2002-10-27T05:30', '2002-10-27T06:30',
+           '2002-10-27T07:30'], dtype='datetime64[m]')
+
+    Setting the timezone to UTC shows the same information, but with a Z suffix
+
+    >>> np.datetime_as_string(d, timezone='UTC')
+    array(['2002-10-27T04:30Z', '2002-10-27T05:30Z', '2002-10-27T06:30Z',
+           '2002-10-27T07:30Z'], dtype='<U35')
+
+    Note that we picked datetimes that cross a DST boundary. Passing in a
+    ``ZoneInfo`` object will print the appropriate offset
+
+    >>> np.datetime_as_string(d, timezone=ZoneInfo('US/Eastern'))
+    array(['2002-10-27T00:30-0400', '2002-10-27T01:30-0400',
+           '2002-10-27T01:30-0500', '2002-10-27T02:30-0500'], dtype='<U39')
+
+    Passing in a unit will change the precision
+
+    >>> np.datetime_as_string(d, unit='h')
+    array(['2002-10-27T04', '2002-10-27T05', '2002-10-27T06', '2002-10-27T07'],
+          dtype='<U32')
+    >>> np.datetime_as_string(d, unit='s')
+    array(['2002-10-27T04:30:00', '2002-10-27T05:30:00', '2002-10-27T06:30:00',
+           '2002-10-27T07:30:00'], dtype='<U38')
+
+    'casting' can be used to specify whether precision can be changed
+
+    >>> np.datetime_as_string(d, unit='h', casting='safe')
+    Traceback (most recent call last):
+        ...
+    TypeError: Cannot create a datetime string as units 'h' from a NumPy
+    datetime with units 'm' according to the rule 'safe'
+    """
+    return (arr,)

v12x/pylib/numpy/_core/numeric.py

@@ -0,0 +1,2707 @@
+import builtins
+import functools
+import itertools
+import math
+import numbers
+import operator
+import sys
+import warnings
+
+import numpy as np
+from numpy.exceptions import AxisError
+
+from . import multiarray, numerictypes, numerictypes as nt, overrides, shape_base, umath
+from ._ufunc_config import errstate
+from .multiarray import (  # noqa: F401
+    ALLOW_THREADS,
+    BUFSIZE,
+    CLIP,
+    MAXDIMS,
+    MAY_SHARE_BOUNDS,
+    MAY_SHARE_EXACT,
+    RAISE,
+    WRAP,
+    arange,
+    array,
+    asanyarray,
+    asarray,
+    ascontiguousarray,
+    asfortranarray,
+    broadcast,
+    can_cast,
+    concatenate,
+    copyto,
+    dot,
+    dtype,
+    empty,
+    empty_like,
+    flatiter,
+    from_dlpack,
+    frombuffer,
+    fromfile,
+    fromiter,
+    fromstring,
+    inner,
+    lexsort,
+    matmul,
+    may_share_memory,
+    min_scalar_type,
+    ndarray,
+    nditer,
+    nested_iters,
+    normalize_axis_index,
+    promote_types,
+    putmask,
+    result_type,
+    shares_memory,
+    vdot,
+    vecdot,
+    where,
+    zeros,
+)
+from .overrides import finalize_array_function_like, set_module
+from .umath import NAN, PINF, invert, multiply, sin
+
+bitwise_not = invert
+ufunc = type(sin)
+newaxis = None
+
+array_function_dispatch = functools.partial(
+    overrides.array_function_dispatch, module='numpy')
+
+
+__all__ = [
+    'newaxis', 'ndarray', 'flatiter', 'nditer', 'nested_iters', 'ufunc',
+    'arange', 'array', 'asarray', 'asanyarray', 'ascontiguousarray',
+    'asfortranarray', 'zeros', 'count_nonzero', 'empty', 'broadcast', 'dtype',
+    'fromstring', 'fromfile', 'frombuffer', 'from_dlpack', 'where',
+    'argwhere', 'copyto', 'concatenate', 'lexsort', 'astype',
+    'can_cast', 'promote_types', 'min_scalar_type',
+    'result_type', 'isfortran', 'empty_like', 'zeros_like', 'ones_like',
+    'correlate', 'convolve', 'inner', 'dot', 'outer', 'vdot', 'roll',
+    'rollaxis', 'moveaxis', 'cross', 'tensordot', 'little_endian',
+    'fromiter', 'array_equal', 'array_equiv', 'indices', 'fromfunction',
+    'isclose', 'isscalar', 'binary_repr', 'base_repr', 'ones',
+    'identity', 'allclose', 'putmask',
+    'flatnonzero', 'inf', 'nan', 'False_', 'True_', 'bitwise_not',
+    'full', 'full_like', 'matmul', 'vecdot', 'shares_memory',
+    'may_share_memory']
+
+
+def _zeros_like_dispatcher(
+    a, dtype=None, order=None, subok=None, shape=None, *, device=None
+):
+    return (a,)
+
+
+@array_function_dispatch(_zeros_like_dispatcher)
+def zeros_like(
+    a, dtype=None, order='K', subok=True, shape=None, *, device=None
+):
+    """
+    Return an array of zeros with the same shape and type as a given array.
+
+    Parameters
+    ----------
+    a : array_like
+        The shape and data-type of `a` define these same attributes of
+        the returned array.
+    dtype : data-type, optional
+        Overrides the data type of the result.
+    order : {'C', 'F', 'A', or 'K'}, optional
+        Overrides the memory layout of the result. 'C' means C-order,
+        'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous,
+        'C' otherwise. 'K' means match the layout of `a` as closely
+        as possible.
+    subok : bool, optional.
+        If True, then the newly created array will use the sub-class
+        type of `a`, otherwise it will be a base-class array. Defaults
+        to True.
+    shape : int or sequence of ints, optional.
+        Overrides the shape of the result. If order='K' and the number of
+        dimensions is unchanged, will try to keep order, otherwise,
+        order='C' is implied.
+    device : str, optional
+        The device on which to place the created array. Default: None.
+        For Array-API interoperability only, so must be ``"cpu"`` if passed.
+
+        .. versionadded:: 2.0.0
+
+    Returns
+    -------
+    out : ndarray
+        Array of zeros with the same shape and type as `a`.
+
+    See Also
+    --------
+    empty_like : Return an empty array with shape and type of input.
+    ones_like : Return an array of ones with shape and type of input.
+    full_like : Return a new array with shape of input filled with value.
+    zeros : Return a new array setting values to zero.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.arange(6)
+    >>> x = x.reshape((2, 3))
+    >>> x
+    array([[0, 1, 2],
+           [3, 4, 5]])
+    >>> np.zeros_like(x)
+    array([[0, 0, 0],
+           [0, 0, 0]])
+
+    >>> y = np.arange(3, dtype=np.float64)
+    >>> y
+    array([0., 1., 2.])
+    >>> np.zeros_like(y)
+    array([0.,  0.,  0.])
+
+    """
+    res = empty_like(
+        a, dtype=dtype, order=order, subok=subok, shape=shape, device=device
+    )
+    # needed instead of a 0 to get same result as zeros for string dtypes
+    z = zeros(1, dtype=res.dtype)
+    multiarray.copyto(res, z, casting='unsafe')
+    return res
+
+
+@finalize_array_function_like
+@set_module('numpy')
+def ones(shape, dtype=None, order='C', *, device=None, like=None):
+    """
+    Return a new array of given shape and type, filled with ones.
+
+    Parameters
+    ----------
+    shape : int or sequence of ints
+        Shape of the new array, e.g., ``(2, 3)`` or ``2``.
+    dtype : data-type, optional
+        The desired data-type for the array, e.g., `numpy.int8`.  Default is
+        `numpy.float64`.
+    order : {'C', 'F'}, optional, default: C
+        Whether to store multi-dimensional data in row-major
+        (C-style) or column-major (Fortran-style) order in
+        memory.
+    device : str, optional
+        The device on which to place the created array. Default: None.
+        For Array-API interoperability only, so must be ``"cpu"`` if passed.
+
+        .. versionadded:: 2.0.0
+    ${ARRAY_FUNCTION_LIKE}
+
+        .. versionadded:: 1.20.0
+
+    Returns
+    -------
+    out : ndarray
+        Array of ones with the given shape, dtype, and order.
+
+    See Also
+    --------
+    ones_like : Return an array of ones with shape and type of input.
+    empty : Return a new uninitialized array.
+    zeros : Return a new array setting values to zero.
+    full : Return a new array of given shape filled with value.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.ones(5)
+    array([1., 1., 1., 1., 1.])
+
+    >>> np.ones((5,), dtype=np.int_)
+    array([1, 1, 1, 1, 1])
+
+    >>> np.ones((2, 1))
+    array([[1.],
+           [1.]])
+
+    >>> s = (2,2)
+    >>> np.ones(s)
+    array([[1.,  1.],
+           [1.,  1.]])
+
+    """
+    if like is not None:
+        return _ones_with_like(
+            like, shape, dtype=dtype, order=order, device=device
+        )
+
+    a = empty(shape, dtype, order, device=device)
+    multiarray.copyto(a, 1, casting='unsafe')
+    return a
+
+
+_ones_with_like = array_function_dispatch()(ones)
+
+
+def _ones_like_dispatcher(
+    a, dtype=None, order=None, subok=None, shape=None, *, device=None
+):
+    return (a,)
+
+
+@array_function_dispatch(_ones_like_dispatcher)
+def ones_like(
+    a, dtype=None, order='K', subok=True, shape=None, *, device=None
+):
+    """
+    Return an array of ones with the same shape and type as a given array.
+
+    Parameters
+    ----------
+    a : array_like
+        The shape and data-type of `a` define these same attributes of
+        the returned array.
+    dtype : data-type, optional
+        Overrides the data type of the result.
+    order : {'C', 'F', 'A', or 'K'}, optional
+        Overrides the memory layout of the result. 'C' means C-order,
+        'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous,
+        'C' otherwise. 'K' means match the layout of `a` as closely
+        as possible.
+    subok : bool, optional.
+        If True, then the newly created array will use the sub-class
+        type of `a`, otherwise it will be a base-class array. Defaults
+        to True.
+    shape : int or sequence of ints, optional.
+        Overrides the shape of the result. If order='K' and the number of
+        dimensions is unchanged, will try to keep order, otherwise,
+        order='C' is implied.
+    device : str, optional
+        The device on which to place the created array. Default: None.
+        For Array-API interoperability only, so must be ``"cpu"`` if passed.
+
+        .. versionadded:: 2.0.0
+
+    Returns
+    -------
+    out : ndarray
+        Array of ones with the same shape and type as `a`.
+
+    See Also
+    --------
+    empty_like : Return an empty array with shape and type of input.
+    zeros_like : Return an array of zeros with shape and type of input.
+    full_like : Return a new array with shape of input filled with value.
+    ones : Return a new array setting values to one.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.arange(6)
+    >>> x = x.reshape((2, 3))
+    >>> x
+    array([[0, 1, 2],
+           [3, 4, 5]])
+    >>> np.ones_like(x)
+    array([[1, 1, 1],
+           [1, 1, 1]])
+
+    >>> y = np.arange(3, dtype=np.float64)
+    >>> y
+    array([0., 1., 2.])
+    >>> np.ones_like(y)
+    array([1.,  1.,  1.])
+
+    """
+    res = empty_like(
+        a, dtype=dtype, order=order, subok=subok, shape=shape, device=device
+    )
+    multiarray.copyto(res, 1, casting='unsafe')
+    return res
+
+
+def _full_dispatcher(
+    shape, fill_value, dtype=None, order=None, *, device=None, like=None
+):
+    return (like,)
+
+
+@finalize_array_function_like
+@set_module('numpy')
+def full(shape, fill_value, dtype=None, order='C', *, device=None, like=None):
+    """
+    Return a new array of given shape and type, filled with `fill_value`.
+
+    Parameters
+    ----------
+    shape : int or sequence of ints
+        Shape of the new array, e.g., ``(2, 3)`` or ``2``.
+    fill_value : scalar or array_like
+        Fill value.
+    dtype : data-type, optional
+        The desired data-type for the array  The default, None, means
+         ``np.array(fill_value).dtype``.
+    order : {'C', 'F'}, optional
+        Whether to store multidimensional data in C- or Fortran-contiguous
+        (row- or column-wise) order in memory.
+    device : str, optional
+        The device on which to place the created array. Default: None.
+        For Array-API interoperability only, so must be ``"cpu"`` if passed.
+
+        .. versionadded:: 2.0.0
+    ${ARRAY_FUNCTION_LIKE}
+
+        .. versionadded:: 1.20.0
+
+    Returns
+    -------
+    out : ndarray
+        Array of `fill_value` with the given shape, dtype, and order.
+
+    See Also
+    --------
+    full_like : Return a new array with shape of input filled with value.
+    empty : Return a new uninitialized array.
+    ones : Return a new array setting values to one.
+    zeros : Return a new array setting values to zero.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.full((2, 2), np.inf)
+    array([[inf, inf],
+           [inf, inf]])
+    >>> np.full((2, 2), 10)
+    array([[10, 10],
+           [10, 10]])
+
+    >>> np.full((2, 2), [1, 2])
+    array([[1, 2],
+           [1, 2]])
+
+    """
+    if like is not None:
+        return _full_with_like(
+            like, shape, fill_value, dtype=dtype, order=order, device=device
+        )
+
+    if dtype is None:
+        fill_value = asarray(fill_value)
+        dtype = fill_value.dtype
+    a = empty(shape, dtype, order, device=device)
+    multiarray.copyto(a, fill_value, casting='unsafe')
+    return a
+
+
+_full_with_like = array_function_dispatch()(full)
+
+
+def _full_like_dispatcher(
+    a, fill_value, dtype=None, order=None, subok=None, shape=None,
+    *, device=None
+):
+    return (a,)
+
+
+@array_function_dispatch(_full_like_dispatcher)
+def full_like(
+    a, fill_value, dtype=None, order='K', subok=True, shape=None,
+    *, device=None
+):
+    """
+    Return a full array with the same shape and type as a given array.
+
+    Parameters
+    ----------
+    a : array_like
+        The shape and data-type of `a` define these same attributes of
+        the returned array.
+    fill_value : array_like
+        Fill value.
+    dtype : data-type, optional
+        Overrides the data type of the result.
+    order : {'C', 'F', 'A', or 'K'}, optional
+        Overrides the memory layout of the result. 'C' means C-order,
+        'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous,
+        'C' otherwise. 'K' means match the layout of `a` as closely
+        as possible.
+    subok : bool, optional.
+        If True, then the newly created array will use the sub-class
+        type of `a`, otherwise it will be a base-class array. Defaults
+        to True.
+    shape : int or sequence of ints, optional.
+        Overrides the shape of the result. If order='K' and the number of
+        dimensions is unchanged, will try to keep order, otherwise,
+        order='C' is implied.
+    device : str, optional
+        The device on which to place the created array. Default: None.
+        For Array-API interoperability only, so must be ``"cpu"`` if passed.
+
+        .. versionadded:: 2.0.0
+
+    Returns
+    -------
+    out : ndarray
+        Array of `fill_value` with the same shape and type as `a`.
+
+    See Also
+    --------
+    empty_like : Return an empty array with shape and type of input.
+    ones_like : Return an array of ones with shape and type of input.
+    zeros_like : Return an array of zeros with shape and type of input.
+    full : Return a new array of given shape filled with value.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.arange(6, dtype=np.int_)
+    >>> np.full_like(x, 1)
+    array([1, 1, 1, 1, 1, 1])
+    >>> np.full_like(x, 0.1)
+    array([0, 0, 0, 0, 0, 0])
+    >>> np.full_like(x, 0.1, dtype=np.float64)
+    array([0.1, 0.1, 0.1, 0.1, 0.1, 0.1])
+    >>> np.full_like(x, np.nan, dtype=np.float64)
+    array([nan, nan, nan, nan, nan, nan])
+
+    >>> y = np.arange(6, dtype=np.float64)
+    >>> np.full_like(y, 0.1)
+    array([0.1, 0.1, 0.1, 0.1, 0.1, 0.1])
+
+    >>> y = np.zeros([2, 2, 3], dtype=np.int_)
+    >>> np.full_like(y, [0, 0, 255])
+    array([[[  0,   0, 255],
+            [  0,   0, 255]],
+           [[  0,   0, 255],
+            [  0,   0, 255]]])
+    """
+    res = empty_like(
+        a, dtype=dtype, order=order, subok=subok, shape=shape, device=device
+    )
+    multiarray.copyto(res, fill_value, casting='unsafe')
+    return res
+
+
+def _count_nonzero_dispatcher(a, axis=None, *, keepdims=None):
+    return (a,)
+
+
+@array_function_dispatch(_count_nonzero_dispatcher)
+def count_nonzero(a, axis=None, *, keepdims=False):
+    """
+    Counts the number of non-zero values in the array ``a``.
+
+    A non-zero value is one that evaluates to truthful in a boolean
+    context, including any non-zero number and any string that
+    is not empty. This function recursively counts how many elements
+    in ``a`` (and its sub-arrays) are non-zero values.
+
+    Parameters
+    ----------
+    a : array_like
+        The array for which to count non-zeros.
+    axis : int or tuple, optional
+        Axis or tuple of axes along which to count non-zeros.
+        Default is None, meaning that non-zeros will be counted
+        along a flattened version of ``a``.
+    keepdims : bool, optional
+        If this is set to True, the axes that are counted are left
+        in the result as dimensions with size one. With this option,
+        the result will broadcast correctly against the input array.
+
+    Returns
+    -------
+    count : int or array of int
+        Number of non-zero values in the array along a given axis.
+        Otherwise, the total number of non-zero values in the array
+        is returned.
+
+    See Also
+    --------
+    nonzero : Return the coordinates of all the non-zero values.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.count_nonzero(np.eye(4))
+    np.int64(4)
+    >>> a = np.array([[0, 1, 7, 0],
+    ...               [3, 0, 2, 19]])
+    >>> np.count_nonzero(a)
+    np.int64(5)
+    >>> np.count_nonzero(a, axis=0)
+    array([1, 1, 2, 1])
+    >>> np.count_nonzero(a, axis=1)
+    array([2, 3])
+    >>> np.count_nonzero(a, axis=1, keepdims=True)
+    array([[2],
+           [3]])
+    """
+    if axis is None and not keepdims:
+        return multiarray.count_nonzero(a)
+
+    a = asanyarray(a)
+
+    # This is a performance optimization for character dtypes
+    # TODO: this can be removed if the legacy fixed-width string dtypes are ever removed
+    if np.issubdtype(a.dtype, np.character):
+        a_bool = a != a.dtype.type()
+    else:
+        a_bool = a.astype(np.bool, copy=False)
+
+    return a_bool.sum(axis=axis, dtype=np.intp, keepdims=keepdims)
+
+
+@set_module('numpy')
+def isfortran(a):
+    """
+    Check if the array is Fortran contiguous but *not* C contiguous.
+
+    This function is obsolete. If you only want to check if an array is Fortran
+    contiguous use ``a.flags.f_contiguous`` instead.
+
+    Parameters
+    ----------
+    a : ndarray
+        Input array.
+
+    Returns
+    -------
+    isfortran : bool
+        Returns True if the array is Fortran contiguous but *not* C contiguous.
+
+
+    Examples
+    --------
+
+    np.array allows to specify whether the array is written in C-contiguous
+    order (last index varies the fastest), or FORTRAN-contiguous order in
+    memory (first index varies the fastest).
+
+    >>> import numpy as np
+    >>> a = np.array([[1, 2, 3], [4, 5, 6]], order='C')
+    >>> a
+    array([[1, 2, 3],
+           [4, 5, 6]])
+    >>> np.isfortran(a)
+    False
+
+    >>> b = np.array([[1, 2, 3], [4, 5, 6]], order='F')
+    >>> b
+    array([[1, 2, 3],
+           [4, 5, 6]])
+    >>> np.isfortran(b)
+    True
+
+
+    The transpose of a C-ordered array is a FORTRAN-ordered array.
+
+    >>> a = np.array([[1, 2, 3], [4, 5, 6]], order='C')
+    >>> a
+    array([[1, 2, 3],
+           [4, 5, 6]])
+    >>> np.isfortran(a)
+    False
+    >>> b = a.T
+    >>> b
+    array([[1, 4],
+           [2, 5],
+           [3, 6]])
+    >>> np.isfortran(b)
+    True
+
+    C-ordered arrays evaluate as False even if they are also FORTRAN-ordered.
+
+    >>> np.isfortran(np.array([1, 2], order='F'))
+    False
+
+    """
+    return a.flags.fnc
+
+
+def _argwhere_dispatcher(a):
+    return (a,)
+
+
+@array_function_dispatch(_argwhere_dispatcher)
+def argwhere(a):
+    """
+    Find the indices of array elements that are non-zero, grouped by element.
+
+    Parameters
+    ----------
+    a : array_like
+        Input data.
+
+    Returns
+    -------
+    index_array : (N, a.ndim) ndarray
+        Indices of elements that are non-zero. Indices are grouped by element.
+        This array will have shape ``(N, a.ndim)`` where ``N`` is the number of
+        non-zero items.
+
+    See Also
+    --------
+    where, nonzero
+
+    Notes
+    -----
+    ``np.argwhere(a)`` is almost the same as ``np.transpose(np.nonzero(a))``,
+    but produces a result of the correct shape for a 0D array.
+
+    The output of ``argwhere`` is not suitable for indexing arrays.
+    For this purpose use ``nonzero(a)`` instead.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.arange(6).reshape(2,3)
+    >>> x
+    array([[0, 1, 2],
+           [3, 4, 5]])
+    >>> np.argwhere(x>1)
+    array([[0, 2],
+           [1, 0],
+           [1, 1],
+           [1, 2]])
+
+    """
+    # nonzero does not behave well on 0d, so promote to 1d
+    if np.ndim(a) == 0:
+        a = shape_base.atleast_1d(a)
+        # then remove the added dimension
+        return argwhere(a)[:, :0]
+    return transpose(nonzero(a))
+
+
+def _flatnonzero_dispatcher(a):
+    return (a,)
+
+
+@array_function_dispatch(_flatnonzero_dispatcher)
+def flatnonzero(a):
+    """
+    Return indices that are non-zero in the flattened version of a.
+
+    This is equivalent to ``np.nonzero(np.ravel(a))[0]``.
+
+    Parameters
+    ----------
+    a : array_like
+        Input data.
+
+    Returns
+    -------
+    res : ndarray
+        Output array, containing the indices of the elements of ``a.ravel()``
+        that are non-zero.
+
+    See Also
+    --------
+    nonzero : Return the indices of the non-zero elements of the input array.
+    ravel : Return a 1-D array containing the elements of the input array.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.arange(-2, 3)
+    >>> x
+    array([-2, -1,  0,  1,  2])
+    >>> np.flatnonzero(x)
+    array([0, 1, 3, 4])
+
+    Use the indices of the non-zero elements as an index array to extract
+    these elements:
+
+    >>> x.ravel()[np.flatnonzero(x)]
+    array([-2, -1,  1,  2])
+
+    """
+    return np.nonzero(np.ravel(a))[0]
+
+
+def _correlate_dispatcher(a, v, mode=None):
+    return (a, v)
+
+
+@array_function_dispatch(_correlate_dispatcher)
+def correlate(a, v, mode='valid'):
+    r"""
+    Cross-correlation of two 1-dimensional sequences.
+
+    This function computes the correlation as generally defined in signal
+    processing texts [1]_:
+
+    .. math:: c_k = \sum_n a_{n+k} \cdot \overline{v}_n
+
+    with a and v sequences being zero-padded where necessary and
+    :math:`\overline v` denoting complex conjugation.
+
+    Parameters
+    ----------
+    a, v : array_like
+        Input sequences.
+    mode : {'valid', 'same', 'full'}, optional
+        Refer to the `convolve` docstring.  Note that the default
+        is 'valid', unlike `convolve`, which uses 'full'.
+
+    Returns
+    -------
+    out : ndarray
+        Discrete cross-correlation of `a` and `v`.
+
+    See Also
+    --------
+    convolve : Discrete, linear convolution of two one-dimensional sequences.
+    scipy.signal.correlate : uses FFT which has superior performance
+        on large arrays.
+
+    Notes
+    -----
+    The definition of correlation above is not unique and sometimes
+    correlation may be defined differently. Another common definition is [1]_:
+
+    .. math:: c'_k = \sum_n a_{n} \cdot \overline{v_{n+k}}
+
+    which is related to :math:`c_k` by :math:`c'_k = c_{-k}`.
+
+    `numpy.correlate` may perform slowly in large arrays (i.e. n = 1e5)
+    because it does not use the FFT to compute the convolution; in that case,
+    `scipy.signal.correlate` might be preferable.
+
+    References
+    ----------
+    .. [1] Wikipedia, "Cross-correlation",
+           https://en.wikipedia.org/wiki/Cross-correlation
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.correlate([1, 2, 3], [0, 1, 0.5])
+    array([3.5])
+    >>> np.correlate([1, 2, 3], [0, 1, 0.5], "same")
+    array([2. ,  3.5,  3. ])
+    >>> np.correlate([1, 2, 3], [0, 1, 0.5], "full")
+    array([0.5,  2. ,  3.5,  3. ,  0. ])
+
+    Using complex sequences:
+
+    >>> np.correlate([1+1j, 2, 3-1j], [0, 1, 0.5j], 'full')
+    array([ 0.5-0.5j,  1.0+0.j ,  1.5-1.5j,  3.0-1.j ,  0.0+0.j ])
+
+    Note that you get the time reversed, complex conjugated result
+    (:math:`\overline{c_{-k}}`) when the two input sequences a and v change
+    places:
+
+    >>> np.correlate([0, 1, 0.5j], [1+1j, 2, 3-1j], 'full')
+    array([ 0.0+0.j ,  3.0+1.j ,  1.5+1.5j,  1.0+0.j ,  0.5+0.5j])
+
+    """
+    return multiarray.correlate2(a, v, mode)
+
+
+def _convolve_dispatcher(a, v, mode=None):
+    return (a, v)
+
+
+@array_function_dispatch(_convolve_dispatcher)
+def convolve(a, v, mode='full'):
+    """
+    Returns the discrete, linear convolution of two one-dimensional sequences.
+
+    The convolution operator is often seen in signal processing, where it
+    models the effect of a linear time-invariant system on a signal [1]_.  In
+    probability theory, the sum of two independent random variables is
+    distributed according to the convolution of their individual
+    distributions.
+
+    If `v` is longer than `a`, the arrays are swapped before computation.
+
+    Parameters
+    ----------
+    a : (N,) array_like
+        First one-dimensional input array.
+    v : (M,) array_like
+        Second one-dimensional input array.
+    mode : {'full', 'valid', 'same'}, optional
+        'full':
+          By default, mode is 'full'.  This returns the convolution
+          at each point of overlap, with an output shape of (N+M-1,). At
+          the end-points of the convolution, the signals do not overlap
+          completely, and boundary effects may be seen.
+
+        'same':
+          Mode 'same' returns output of length ``max(M, N)``.  Boundary
+          effects are still visible.
+
+        'valid':
+          Mode 'valid' returns output of length
+          ``max(M, N) - min(M, N) + 1``.  The convolution product is only given
+          for points where the signals overlap completely.  Values outside
+          the signal boundary have no effect.
+
+    Returns
+    -------
+    out : ndarray
+        Discrete, linear convolution of `a` and `v`.
+
+    See Also
+    --------
+    scipy.signal.fftconvolve : Convolve two arrays using the Fast Fourier
+                               Transform.
+    scipy.linalg.toeplitz : Used to construct the convolution operator.
+    polymul : Polynomial multiplication. Same output as convolve, but also
+              accepts poly1d objects as input.
+
+    Notes
+    -----
+    The discrete convolution operation is defined as
+
+    .. math:: (a * v)_n = \\sum_{m = -\\infty}^{\\infty} a_m v_{n - m}
+
+    It can be shown that a convolution :math:`x(t) * y(t)` in time/space
+    is equivalent to the multiplication :math:`X(f) Y(f)` in the Fourier
+    domain, after appropriate padding (padding is necessary to prevent
+    circular convolution).  Since multiplication is more efficient (faster)
+    than convolution, the function `scipy.signal.fftconvolve` exploits the
+    FFT to calculate the convolution of large data-sets.
+
+    References
+    ----------
+    .. [1] Wikipedia, "Convolution",
+        https://en.wikipedia.org/wiki/Convolution
+
+    Examples
+    --------
+    Note how the convolution operator flips the second array
+    before "sliding" the two across one another:
+
+    >>> import numpy as np
+    >>> np.convolve([1, 2, 3], [0, 1, 0.5])
+    array([0. , 1. , 2.5, 4. , 1.5])
+
+    Only return the middle values of the convolution.
+    Contains boundary effects, where zeros are taken
+    into account:
+
+    >>> np.convolve([1,2,3],[0,1,0.5], 'same')
+    array([1. ,  2.5,  4. ])
+
+    The two arrays are of the same length, so there
+    is only one position where they completely overlap:
+
+    >>> np.convolve([1,2,3],[0,1,0.5], 'valid')
+    array([2.5])
+
+    """
+    a, v = array(a, copy=None, ndmin=1), array(v, copy=None, ndmin=1)
+    if len(a) == 0:
+        raise ValueError('a cannot be empty')
+    if len(v) == 0:
+        raise ValueError('v cannot be empty')
+    if len(v) > len(a):
+        a, v = v, a
+    return multiarray.correlate(a, v[::-1], mode)
+
+
+def _outer_dispatcher(a, b, out=None):
+    return (a, b, out)
+
+
+@array_function_dispatch(_outer_dispatcher)
+def outer(a, b, out=None):
+    """
+    Compute the outer product of two vectors.
+
+    Given two vectors `a` and `b` of length ``M`` and ``N``, respectively,
+    the outer product [1]_ is::
+
+      [[a_0*b_0  a_0*b_1 ... a_0*b_{N-1} ]
+       [a_1*b_0    .
+       [ ...          .
+       [a_{M-1}*b_0            a_{M-1}*b_{N-1} ]]
+
+    Parameters
+    ----------
+    a : (M,) array_like
+        First input vector.  Input is flattened if
+        not already 1-dimensional.
+    b : (N,) array_like
+        Second input vector.  Input is flattened if
+        not already 1-dimensional.
+    out : (M, N) ndarray, optional
+        A location where the result is stored
+
+    Returns
+    -------
+    out : (M, N) ndarray
+        ``out[i, j] = a[i] * b[j]``
+
+    See also
+    --------
+    inner
+    einsum : ``einsum('i,j->ij', a.ravel(), b.ravel())`` is the equivalent.
+    ufunc.outer : A generalization to dimensions other than 1D and other
+                  operations. ``np.multiply.outer(a.ravel(), b.ravel())``
+                  is the equivalent.
+    linalg.outer : An Array API compatible variation of ``np.outer``,
+                   which accepts 1-dimensional inputs only.
+    tensordot : ``np.tensordot(a.ravel(), b.ravel(), axes=((), ()))``
+                is the equivalent.
+
+    References
+    ----------
+    .. [1] G. H. Golub and C. F. Van Loan, *Matrix Computations*, 3rd
+           ed., Baltimore, MD, Johns Hopkins University Press, 1996,
+           pg. 8.
+
+    Examples
+    --------
+    Make a (*very* coarse) grid for computing a Mandelbrot set:
+
+    >>> import numpy as np
+    >>> rl = np.outer(np.ones((5,)), np.linspace(-2, 2, 5))
+    >>> rl
+    array([[-2., -1.,  0.,  1.,  2.],
+           [-2., -1.,  0.,  1.,  2.],
+           [-2., -1.,  0.,  1.,  2.],
+           [-2., -1.,  0.,  1.,  2.],
+           [-2., -1.,  0.,  1.,  2.]])
+    >>> im = np.outer(1j*np.linspace(2, -2, 5), np.ones((5,)))
+    >>> im
+    array([[0.+2.j, 0.+2.j, 0.+2.j, 0.+2.j, 0.+2.j],
+           [0.+1.j, 0.+1.j, 0.+1.j, 0.+1.j, 0.+1.j],
+           [0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j],
+           [0.-1.j, 0.-1.j, 0.-1.j, 0.-1.j, 0.-1.j],
+           [0.-2.j, 0.-2.j, 0.-2.j, 0.-2.j, 0.-2.j]])
+    >>> grid = rl + im
+    >>> grid
+    array([[-2.+2.j, -1.+2.j,  0.+2.j,  1.+2.j,  2.+2.j],
+           [-2.+1.j, -1.+1.j,  0.+1.j,  1.+1.j,  2.+1.j],
+           [-2.+0.j, -1.+0.j,  0.+0.j,  1.+0.j,  2.+0.j],
+           [-2.-1.j, -1.-1.j,  0.-1.j,  1.-1.j,  2.-1.j],
+           [-2.-2.j, -1.-2.j,  0.-2.j,  1.-2.j,  2.-2.j]])
+
+    An example using a "vector" of letters:
+
+    >>> x = np.array(['a', 'b', 'c'], dtype=np.object_)
+    >>> np.outer(x, [1, 2, 3])
+    array([['a', 'aa', 'aaa'],
+           ['b', 'bb', 'bbb'],
+           ['c', 'cc', 'ccc']], dtype=object)
+
+    """
+    a = asarray(a)
+    b = asarray(b)
+    return multiply(a.ravel()[:, newaxis], b.ravel()[newaxis, :], out)
+
+
+def _tensordot_dispatcher(a, b, axes=None):
+    return (a, b)
+
+
+@array_function_dispatch(_tensordot_dispatcher)
+def tensordot(a, b, axes=2):
+    """
+    Compute tensor dot product along specified axes.
+
+    Given two tensors, `a` and `b`, and an array_like object containing
+    two array_like objects, ``(a_axes, b_axes)``, sum the products of
+    `a`'s and `b`'s elements (components) over the axes specified by
+    ``a_axes`` and ``b_axes``. The third argument can be a single non-negative
+    integer_like scalar, ``N``; if it is such, then the last ``N`` dimensions
+    of `a` and the first ``N`` dimensions of `b` are summed over.
+
+    Parameters
+    ----------
+    a, b : array_like
+        Tensors to "dot".
+
+    axes : int or (2,) array_like
+        * integer_like
+          If an int N, sum over the last N axes of `a` and the first N axes
+          of `b` in order. The sizes of the corresponding axes must match.
+        * (2,) array_like
+          Or, a list of axes to be summed over, first sequence applying to `a`,
+          second to `b`. Both elements array_like must be of the same length.
+          Each axis may appear at most once; repeated axes are not allowed.
+          For example, ``axes=([1, 1], [0, 0])`` is invalid.
+    Returns
+    -------
+    output : ndarray
+        The tensor dot product of the input.
+
+    See Also
+    --------
+    dot, einsum
+
+    Notes
+    -----
+    Three common use cases are:
+        * ``axes = 0`` : tensor product :math:`a\\otimes b`
+        * ``axes = 1`` : tensor dot product :math:`a\\cdot b`
+        * ``axes = 2`` : (default) tensor double contraction :math:`a:b`
+
+    When `axes` is integer_like, the sequence of axes for evaluation
+    will be: from the -Nth axis to the -1th axis in `a`,
+    and from the 0th axis to (N-1)th axis in `b`.
+    For example, ``axes = 2`` is the equal to
+    ``axes = [[-2, -1], [0, 1]]``.
+    When N-1 is smaller than 0, or when -N is larger than -1,
+    the element of `a` and `b` are defined as the `axes`.
+
+    When there is more than one axis to sum over - and they are not the last
+    (first) axes of `a` (`b`) - the argument `axes` should consist of
+    two sequences of the same length, with the first axis to sum over given
+    first in both sequences, the second axis second, and so forth.
+    The calculation can be referred to ``numpy.einsum``.
+
+    For example, if ``a.shape == (2, 3, 4)`` and ``b.shape == (3, 4, 5)``,
+    then ``axes=([1, 2], [0, 1])`` sums over the ``(3, 4)`` dimensions of
+    both arrays and produces an output of shape ``(2, 5)``.
+
+    Each summation axis corresponds to a distinct contraction index; repeating
+    an axis (for example ``axes=([1, 1], [0, 0])``) is invalid.
+
+    The shape of the result consists of the non-contracted axes of the
+    first tensor, followed by the non-contracted axes of the second.
+
+    Examples
+    --------
+    An example on integer_like:
+
+    >>> a_0 = np.array([[1, 2], [3, 4]])
+    >>> b_0 = np.array([[5, 6], [7, 8]])
+    >>> c_0 = np.tensordot(a_0, b_0, axes=0)
+    >>> c_0.shape
+    (2, 2, 2, 2)
+    >>> c_0
+    array([[[[ 5,  6],
+             [ 7,  8]],
+            [[10, 12],
+             [14, 16]]],
+           [[[15, 18],
+             [21, 24]],
+            [[20, 24],
+             [28, 32]]]])
+
+    An example on array_like:
+
+    >>> a = np.arange(60.).reshape(3,4,5)
+    >>> b = np.arange(24.).reshape(4,3,2)
+    >>> c = np.tensordot(a,b, axes=([1,0],[0,1]))
+    >>> c.shape
+    (5, 2)
+    >>> c
+    array([[4400., 4730.],
+           [4532., 4874.],
+           [4664., 5018.],
+           [4796., 5162.],
+           [4928., 5306.]])
+
+    A slower but equivalent way of computing the same...
+
+    >>> d = np.zeros((5,2))
+    >>> for i in range(5):
+    ...   for j in range(2):
+    ...     for k in range(3):
+    ...       for n in range(4):
+    ...         d[i,j] += a[k,n,i] * b[n,k,j]
+    >>> c == d
+    array([[ True,  True],
+           [ True,  True],
+           [ True,  True],
+           [ True,  True],
+           [ True,  True]])
+
+    An extended example taking advantage of the overloading of + and \\*:
+
+    >>> a = np.array(range(1, 9)).reshape((2, 2, 2))
+    >>> A = np.array(('a', 'b', 'c', 'd'), dtype=np.object_)
+    >>> A = A.reshape((2, 2))
+    >>> a; A
+    array([[[1, 2],
+            [3, 4]],
+           [[5, 6],
+            [7, 8]]])
+    array([['a', 'b'],
+           ['c', 'd']], dtype=object)
+
+    >>> np.tensordot(a, A) # third argument default is 2 for double-contraction
+    array(['abbcccdddd', 'aaaaabbbbbbcccccccdddddddd'], dtype=object)
+
+    >>> np.tensordot(a, A, 1)
+    array([[['acc', 'bdd'],
+            ['aaacccc', 'bbbdddd']],
+           [['aaaaacccccc', 'bbbbbdddddd'],
+            ['aaaaaaacccccccc', 'bbbbbbbdddddddd']]], dtype=object)
+
+    >>> np.tensordot(a, A, 0) # tensor product (result too long to incl.)
+    array([[[[['a', 'b'],
+              ['c', 'd']],
+              ...
+
+    >>> np.tensordot(a, A, (0, 1))
+    array([[['abbbbb', 'cddddd'],
+            ['aabbbbbb', 'ccdddddd']],
+           [['aaabbbbbbb', 'cccddddddd'],
+            ['aaaabbbbbbbb', 'ccccdddddddd']]], dtype=object)
+
+    >>> np.tensordot(a, A, (2, 1))
+    array([[['abb', 'cdd'],
+            ['aaabbbb', 'cccdddd']],
+           [['aaaaabbbbbb', 'cccccdddddd'],
+            ['aaaaaaabbbbbbbb', 'cccccccdddddddd']]], dtype=object)
+
+    >>> np.tensordot(a, A, ((0, 1), (0, 1)))
+    array(['abbbcccccddddddd', 'aabbbbccccccdddddddd'], dtype=object)
+
+    >>> np.tensordot(a, A, ((2, 1), (1, 0)))
+    array(['acccbbdddd', 'aaaaacccccccbbbbbbdddddddd'], dtype=object)
+
+    """
+    try:
+        iter(axes)
+    except Exception:
+        axes_a = list(range(-axes, 0))
+        axes_b = list(range(axes))
+    else:
+        axes_a, axes_b = axes
+    try:
+        na = len(axes_a)
+        axes_a = list(axes_a)
+    except TypeError:
+        axes_a = [axes_a]
+        na = 1
+    try:
+        nb = len(axes_b)
+        axes_b = list(axes_b)
+    except TypeError:
+        axes_b = [axes_b]
+        nb = 1
+
+    if len(set(axes_a)) != len(axes_a):
+        raise ValueError("duplicate axes are not allowed in tensordot")
+    if len(set(axes_b)) != len(axes_b):
+        raise ValueError("duplicate axes are not allowed in tensordot")
+
+    a, b = asarray(a), asarray(b)
+    as_ = a.shape
+    nda = a.ndim
+    bs = b.shape
+    ndb = b.ndim
+    equal = True
+    if na != nb:
+        equal = False
+    else:
+        for k in range(na):
+            if as_[axes_a[k]] != bs[axes_b[k]]:
+                equal = False
+                break
+            if axes_a[k] < 0:
+                axes_a[k] += nda
+            if axes_b[k] < 0:
+                axes_b[k] += ndb
+    if not equal:
+        raise ValueError("shape-mismatch for sum")
+
+    # Move the axes to sum over to the end of "a"
+    # and to the front of "b"
+    notin = [k for k in range(nda) if k not in axes_a]
+    newaxes_a = notin + axes_a
+    N2 = math.prod(as_[axis] for axis in axes_a)
+    newshape_a = (math.prod(as_[ax] for ax in notin), N2)
+    olda = [as_[axis] for axis in notin]
+
+    notin = [k for k in range(ndb) if k not in axes_b]
+    newaxes_b = axes_b + notin
+    N2 = math.prod(bs[axis] for axis in axes_b)
+    newshape_b = (N2, math.prod(bs[ax] for ax in notin))
+    oldb = [bs[axis] for axis in notin]
+
+    at = a.transpose(newaxes_a).reshape(newshape_a)
+    bt = b.transpose(newaxes_b).reshape(newshape_b)
+    res = dot(at, bt)
+    return res.reshape(olda + oldb)
+
+
+def _roll_dispatcher(a, shift, axis=None):
+    return (a,)
+
+
+@array_function_dispatch(_roll_dispatcher)
+def roll(a, shift, axis=None):
+    """
+    Roll array elements along a given axis.
+
+    Elements that roll beyond the last position are re-introduced at
+    the first.
+
+    Parameters
+    ----------
+    a : array_like
+        Input array.
+    shift : int or tuple of ints
+        The number of places by which elements are shifted.  If a tuple,
+        then `axis` must be a tuple of the same size, and each of the
+        given axes is shifted by the corresponding number.  If an int
+        while `axis` is a tuple of ints, then the same value is used for
+        all given axes.
+    axis : int or tuple of ints, optional
+        Axis or axes along which elements are shifted.  By default, the
+        array is flattened before shifting, after which the original
+        shape is restored.
+
+    Returns
+    -------
+    res : ndarray
+        Output array, with the same shape as `a`.
+
+    See Also
+    --------
+    rollaxis : Roll the specified axis backwards, until it lies in a
+               given position.
+
+    Notes
+    -----
+    Supports rolling over multiple dimensions simultaneously.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.arange(10)
+    >>> np.roll(x, 2)
+    array([8, 9, 0, 1, 2, 3, 4, 5, 6, 7])
+    >>> np.roll(x, -2)
+    array([2, 3, 4, 5, 6, 7, 8, 9, 0, 1])
+
+    >>> x2 = np.reshape(x, (2, 5))
+    >>> x2
+    array([[0, 1, 2, 3, 4],
+           [5, 6, 7, 8, 9]])
+    >>> np.roll(x2, 1)
+    array([[9, 0, 1, 2, 3],
+           [4, 5, 6, 7, 8]])
+    >>> np.roll(x2, -1)
+    array([[1, 2, 3, 4, 5],
+           [6, 7, 8, 9, 0]])
+    >>> np.roll(x2, 1, axis=0)
+    array([[5, 6, 7, 8, 9],
+           [0, 1, 2, 3, 4]])
+    >>> np.roll(x2, -1, axis=0)
+    array([[5, 6, 7, 8, 9],
+           [0, 1, 2, 3, 4]])
+    >>> np.roll(x2, 1, axis=1)
+    array([[4, 0, 1, 2, 3],
+           [9, 5, 6, 7, 8]])
+    >>> np.roll(x2, -1, axis=1)
+    array([[1, 2, 3, 4, 0],
+           [6, 7, 8, 9, 5]])
+    >>> np.roll(x2, (1, 1), axis=(1, 0))
+    array([[9, 5, 6, 7, 8],
+           [4, 0, 1, 2, 3]])
+    >>> np.roll(x2, (2, 1), axis=(1, 0))
+    array([[8, 9, 5, 6, 7],
+           [3, 4, 0, 1, 2]])
+
+    """
+    a = asanyarray(a)
+    if axis is None:
+        return roll(a.ravel(), shift, 0).reshape(a.shape)
+
+    else:
+        axis = normalize_axis_tuple(axis, a.ndim, allow_duplicate=True)
+        broadcasted = broadcast(shift, axis)
+        if broadcasted.ndim > 1:
+            raise ValueError(
+                "'shift' and 'axis' should be scalars or 1D sequences")
+        shifts = dict.fromkeys(range(a.ndim), 0)
+        for sh, ax in broadcasted:
+            shifts[ax] += int(sh)
+
+        rolls = [((slice(None), slice(None)),)] * a.ndim
+        for ax, offset in shifts.items():
+            offset %= a.shape[ax] or 1  # If `a` is empty, nothing matters.
+            if offset:
+                # (original, result), (original, result)
+                rolls[ax] = ((slice(None, -offset), slice(offset, None)),
+                             (slice(-offset, None), slice(None, offset)))
+
+        result = empty_like(a)
+        for indices in itertools.product(*rolls):
+            arr_index, res_index = zip(*indices)
+            result[res_index] = a[arr_index]
+
+        return result
+
+
+def _rollaxis_dispatcher(a, axis, start=None):
+    return (a,)
+
+
+@array_function_dispatch(_rollaxis_dispatcher)
+def rollaxis(a, axis, start=0):
+    """
+    Roll the specified axis backwards, until it lies in a given position.
+
+    This function continues to be supported for backward compatibility, but you
+    should prefer `moveaxis`. The `moveaxis` function was added in NumPy
+    1.11.
+
+    Parameters
+    ----------
+    a : ndarray
+        Input array.
+    axis : int
+        The axis to be rolled. The positions of the other axes do not
+        change relative to one another.
+    start : int, optional
+        When ``start <= axis``, the axis is rolled back until it lies in
+        this position. When ``start > axis``, the axis is rolled until it
+        lies before this position. The default, 0, results in a "complete"
+        roll. The following table describes how negative values of ``start``
+        are interpreted:
+
+        .. table::
+           :align: left
+
+           +-------------------+----------------------+
+           |     ``start``     | Normalized ``start`` |
+           +===================+======================+
+           | ``-(arr.ndim+1)`` | raise ``AxisError``  |
+           +-------------------+----------------------+
+           | ``-arr.ndim``     | 0                    |
+           +-------------------+----------------------+
+           | |vdots|           | |vdots|              |
+           +-------------------+----------------------+
+           | ``-1``            | ``arr.ndim-1``       |
+           +-------------------+----------------------+
+           | ``0``             | ``0``                |
+           +-------------------+----------------------+
+           | |vdots|           | |vdots|              |
+           +-------------------+----------------------+
+           | ``arr.ndim``      | ``arr.ndim``         |
+           +-------------------+----------------------+
+           | ``arr.ndim + 1``  | raise ``AxisError``  |
+           +-------------------+----------------------+
+
+        .. |vdots|   unicode:: U+22EE .. Vertical Ellipsis
+
+    Returns
+    -------
+    res : ndarray
+        For NumPy >= 1.10.0 a view of `a` is always returned. For earlier
+        NumPy versions a view of `a` is returned only if the order of the
+        axes is changed, otherwise the input array is returned.
+
+    See Also
+    --------
+    moveaxis : Move array axes to new positions.
+    roll : Roll the elements of an array by a number of positions along a
+        given axis.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.ones((3,4,5,6))
+    >>> np.rollaxis(a, 3, 1).shape
+    (3, 6, 4, 5)
+    >>> np.rollaxis(a, 2).shape
+    (5, 3, 4, 6)
+    >>> np.rollaxis(a, 1, 4).shape
+    (3, 5, 6, 4)
+
+    """
+    n = a.ndim
+    axis = normalize_axis_index(axis, n)
+    if start < 0:
+        start += n
+    msg = "'%s' arg requires %d <= %s < %d, but %d was passed in"
+    if not (0 <= start < n + 1):
+        raise AxisError(msg % ('start', -n, 'start', n + 1, start))
+    if axis < start:
+        # it's been removed
+        start -= 1
+    if axis == start:
+        return a[...]
+    axes = list(range(n))
+    axes.remove(axis)
+    axes.insert(start, axis)
+    return a.transpose(axes)
+
+
+@set_module("numpy.lib.array_utils")
+def normalize_axis_tuple(axis, ndim, argname=None, allow_duplicate=False):
+    """
+    Normalizes an axis argument into a tuple of non-negative integer axes.
+
+    This handles shorthands such as ``1`` and converts them to ``(1,)``,
+    as well as performing the handling of negative indices covered by
+    `normalize_axis_index`.
+
+    By default, this forbids axes from being specified multiple times.
+
+    Used internally by multi-axis-checking logic.
+
+    Parameters
+    ----------
+    axis : int, iterable of int
+        The un-normalized index or indices of the axis.
+    ndim : int
+        The number of dimensions of the array that `axis` should be normalized
+        against.
+    argname : str, optional
+        A prefix to put before the error message, typically the name of the
+        argument.
+    allow_duplicate : bool, optional
+        If False, the default, disallow an axis from being specified twice.
+
+    Returns
+    -------
+    normalized_axes : tuple of int
+        The normalized axis index, such that `0 <= normalized_axis < ndim`
+
+    Raises
+    ------
+    AxisError
+        If any axis provided is out of range
+    ValueError
+        If an axis is repeated
+
+    See also
+    --------
+    normalize_axis_index : normalizing a single scalar axis
+    """
+    # Optimization to speed-up the most common cases.
+    if not isinstance(axis, (tuple, list)):
+        try:
+            axis = [operator.index(axis)]
+        except TypeError:
+            pass
+    # Going via an iterator directly is slower than via list comprehension.
+    axis = tuple(normalize_axis_index(ax, ndim, argname) for ax in axis)
+    if not allow_duplicate and len(set(axis)) != len(axis):
+        if argname:
+            raise ValueError(f'repeated axis in `{argname}` argument')
+        else:
+            raise ValueError('repeated axis')
+    return axis
+
+
+def _moveaxis_dispatcher(a, source, destination):
+    return (a,)
+
+
+@array_function_dispatch(_moveaxis_dispatcher)
+def moveaxis(a, source, destination):
+    """
+    Move axes of an array to new positions.
+
+    Other axes remain in their original order.
+
+    Parameters
+    ----------
+    a : np.ndarray
+        The array whose axes should be reordered.
+    source : int or sequence of int
+        Original positions of the axes to move. These must be unique.
+    destination : int or sequence of int
+        Destination positions for each of the original axes. These must also be
+        unique.
+
+    Returns
+    -------
+    result : np.ndarray
+        Array with moved axes. This array is a view of the input array.
+
+    See Also
+    --------
+    transpose : Permute the dimensions of an array.
+    swapaxes : Interchange two axes of an array.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.zeros((3, 4, 5))
+    >>> np.moveaxis(x, 0, -1).shape
+    (4, 5, 3)
+    >>> np.moveaxis(x, -1, 0).shape
+    (5, 3, 4)
+
+    These all achieve the same result:
+
+    >>> np.transpose(x).shape
+    (5, 4, 3)
+    >>> np.swapaxes(x, 0, -1).shape
+    (5, 4, 3)
+    >>> np.moveaxis(x, [0, 1], [-1, -2]).shape
+    (5, 4, 3)
+    >>> np.moveaxis(x, [0, 1, 2], [-1, -2, -3]).shape
+    (5, 4, 3)
+
+    """
+    try:
+        # allow duck-array types if they define transpose
+        transpose = a.transpose
+    except AttributeError:
+        a = asarray(a)
+        transpose = a.transpose
+
+    source = normalize_axis_tuple(source, a.ndim, 'source')
+    destination = normalize_axis_tuple(destination, a.ndim, 'destination')
+    if len(source) != len(destination):
+        raise ValueError('`source` and `destination` arguments must have '
+                         'the same number of elements')
+
+    order = [n for n in range(a.ndim) if n not in source]
+
+    for dest, src in sorted(zip(destination, source)):
+        order.insert(dest, src)
+
+    result = transpose(order)
+    return result
+
+
+def _cross_dispatcher(a, b, axisa=None, axisb=None, axisc=None, axis=None):
+    return (a, b)
+
+
+@array_function_dispatch(_cross_dispatcher)
+def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None):
+    """
+    Return the cross product of two (arrays of) vectors.
+
+    The cross product of `a` and `b` in :math:`R^3` is a vector perpendicular
+    to both `a` and `b`.  If `a` and `b` are arrays of vectors, the vectors
+    are defined by the last axis of `a` and `b` by default, and these axes
+    must have 3 dimensions.
+
+    Parameters
+    ----------
+    a : array_like
+        Components of the first vector(s).
+    b : array_like
+        Components of the second vector(s).
+    axisa : int, optional
+        Axis of `a` that defines the vector(s).  By default, the last axis.
+    axisb : int, optional
+        Axis of `b` that defines the vector(s).  By default, the last axis.
+    axisc : int, optional
+        Axis of `c` containing the cross product vector(s).  By default, the last axis.
+    axis : int, optional
+        If defined, the axis of `a`, `b` and `c` that defines the vector(s)
+        and cross product(s).  Overrides `axisa`, `axisb` and `axisc`.
+
+    Returns
+    -------
+    c : ndarray
+        Vector cross product(s).
+
+    Raises
+    ------
+    ValueError
+        When the dimension of the vector(s) in `a` or `b` does not equal 3.
+
+    See Also
+    --------
+    inner : Inner product
+    outer : Outer product.
+    linalg.cross : An Array API compatible variation of ``np.cross``.
+    ix_ : Construct index arrays.
+
+    Notes
+    -----
+    Supports full broadcasting of the inputs.
+
+    Examples
+    --------
+    Vector cross-product.
+
+    >>> import numpy as np
+    >>> x = [1, 2, 3]
+    >>> y = [4, 5, 6]
+    >>> np.cross(x, y)
+    array([-3,  6, -3])
+
+    One vector with dimension 2.
+
+    >>> x = [1, 2, 0]
+    >>> y = [4, 5, 6]
+    >>> np.cross(x, y)
+    array([12, -6, -3])
+
+    Both vectors with dimension 2.
+
+    >>> x = [1, 2, 0]
+    >>> y = [4, 5, 0]
+    >>> np.cross(x, y)
+    array([0, 0, -3])
+
+    Multiple vector cross-products. Note that the direction of the cross
+    product vector is defined by the *right-hand rule*.
+
+    >>> x = np.array([[1,2,3], [4,5,6]])
+    >>> y = np.array([[4,5,6], [1,2,3]])
+    >>> np.cross(x, y)
+    array([[-3,  6, -3],
+           [ 3, -6,  3]])
+
+    The orientation of `c` can be changed using the `axisc` keyword.
+
+    >>> np.cross(x, y, axisc=0)
+    array([[-3,  3],
+           [ 6, -6],
+           [-3,  3]])
+
+    Change the vector definition of `x` and `y` using `axisa` and `axisb`.
+
+    >>> x = np.array([[1,2,3], [4,5,6], [7, 8, 9]])
+    >>> y = np.array([[7, 8, 9], [4,5,6], [1,2,3]])
+    >>> np.cross(x, y)
+    array([[ -6,  12,  -6],
+           [  0,   0,   0],
+           [  6, -12,   6]])
+    >>> np.cross(x, y, axisa=0, axisb=0)
+    array([[-24,  48, -24],
+           [-30,  60, -30],
+           [-36,  72, -36]])
+
+    """
+    if axis is not None:
+        axisa, axisb, axisc = (axis,) * 3
+    a = asarray(a)
+    b = asarray(b)
+
+    if (a.ndim < 1) or (b.ndim < 1):
+        raise ValueError("At least one array has zero dimension")
+
+    # Check axisa and axisb are within bounds
+    axisa = normalize_axis_index(axisa, a.ndim, msg_prefix='axisa')
+    axisb = normalize_axis_index(axisb, b.ndim, msg_prefix='axisb')
+
+    # Move working axis to the end of the shape
+    a = moveaxis(a, axisa, -1)
+    b = moveaxis(b, axisb, -1)
+    if a.shape[-1] != 3 or b.shape[-1] != 3:
+        raise ValueError(
+            f"Both input arrays must be (arrays of) 3-dimensional vectors, "
+            f"but they are {a.shape[-1]} and {b.shape[-1]} dimensional instead."
+        )
+
+    # Create the output array
+    shape = *broadcast(a[..., 0], b[..., 0]).shape, 3
+    # Check axisc is within bounds
+    axisc = normalize_axis_index(axisc, len(shape), msg_prefix='axisc')
+    dtype = promote_types(a.dtype, b.dtype)
+    cp = empty(shape, dtype)
+
+    # recast arrays as dtype
+    a = a.astype(dtype)
+    b = b.astype(dtype)
+
+    # create local aliases for readability
+    a0 = a[..., 0]
+    a1 = a[..., 1]
+    a2 = a[..., 2]
+    b0 = b[..., 0]
+    b1 = b[..., 1]
+    b2 = b[..., 2]
+    cp0 = cp[..., 0]
+    cp1 = cp[..., 1]
+    cp2 = cp[..., 2]
+
+    # cp0 = a1 * b2 - a2 * b1
+    # cp1 = a2 * b0 - a0 * b2
+    # cp2 = a0 * b1 - a1 * b0
+    multiply(a1, b2, out=cp0)
+    tmp = np.multiply(a2, b1, out=...)
+    cp0 -= tmp
+    multiply(a2, b0, out=cp1)
+    multiply(a0, b2, out=tmp)
+    cp1 -= tmp
+    multiply(a0, b1, out=cp2)
+    multiply(a1, b0, out=tmp)
+    cp2 -= tmp
+
+    return moveaxis(cp, -1, axisc)
+
+
+little_endian = (sys.byteorder == 'little')
+
+
+@set_module('numpy')
+def indices(dimensions, dtype=int, sparse=False):
+    """
+    Return an array representing the indices of a grid.
+
+    Compute an array where the subarrays contain index values 0, 1, ...
+    varying only along the corresponding axis.
+
+    Parameters
+    ----------
+    dimensions : sequence of ints
+        The shape of the grid.
+    dtype : dtype, optional
+        Data type of the result.
+    sparse : boolean, optional
+        Return a sparse representation of the grid instead of a dense
+        representation. Default is False.
+
+    Returns
+    -------
+    grid : one ndarray or tuple of ndarrays
+        If sparse is False:
+            Returns one array of grid indices,
+            ``grid.shape = (len(dimensions),) + tuple(dimensions)``.
+        If sparse is True:
+            Returns a tuple of arrays, with
+            ``grid[i].shape = (1, ..., 1, dimensions[i], 1, ..., 1)`` with
+            dimensions[i] in the ith place
+
+    See Also
+    --------
+    mgrid, ogrid, meshgrid
+
+    Notes
+    -----
+    The output shape in the dense case is obtained by prepending the number
+    of dimensions in front of the tuple of dimensions, i.e. if `dimensions`
+    is a tuple ``(r0, ..., rN-1)`` of length ``N``, the output shape is
+    ``(N, r0, ..., rN-1)``.
+
+    The subarrays ``grid[k]`` contains the N-D array of indices along the
+    ``k-th`` axis. Explicitly::
+
+        grid[k, i0, i1, ..., iN-1] = ik
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> grid = np.indices((2, 3))
+    >>> grid.shape
+    (2, 2, 3)
+    >>> grid[0]        # row indices
+    array([[0, 0, 0],
+           [1, 1, 1]])
+    >>> grid[1]        # column indices
+    array([[0, 1, 2],
+           [0, 1, 2]])
+
+    The indices can be used as an index into an array.
+
+    >>> x = np.arange(20).reshape(5, 4)
+    >>> row, col = np.indices((2, 3))
+    >>> x[row, col]
+    array([[0, 1, 2],
+           [4, 5, 6]])
+
+    Note that it would be more straightforward in the above example to
+    extract the required elements directly with ``x[:2, :3]``.
+
+    If sparse is set to true, the grid will be returned in a sparse
+    representation.
+
+    >>> i, j = np.indices((2, 3), sparse=True)
+    >>> i.shape
+    (2, 1)
+    >>> j.shape
+    (1, 3)
+    >>> i        # row indices
+    array([[0],
+           [1]])
+    >>> j        # column indices
+    array([[0, 1, 2]])
+
+    """
+    dimensions = tuple(dimensions)
+    N = len(dimensions)
+    shape = (1,) * N
+    if sparse:
+        res = ()
+    else:
+        res = empty((N,) + dimensions, dtype=dtype)
+    for i, dim in enumerate(dimensions):
+        idx = arange(dim, dtype=dtype).reshape(
+            shape[:i] + (dim,) + shape[i + 1:]
+        )
+        if sparse:
+            res = res + (idx,)
+        else:
+            res[i] = idx
+    return res
+
+
+@finalize_array_function_like
+@set_module('numpy')
+def fromfunction(function, shape, *, dtype=float, like=None, **kwargs):
+    """
+    Construct an array by executing a function over each coordinate.
+
+    The resulting array therefore has a value ``fn(x, y, z)`` at
+    coordinate ``(x, y, z)``.
+
+    Parameters
+    ----------
+    function : callable
+        The function is called with N parameters, where N is the rank of
+        `shape`.  Each parameter represents the coordinates of the array
+        varying along a specific axis.  For example, if `shape`
+        were ``(2, 2)``, then the parameters would be
+        ``array([[0, 0], [1, 1]])`` and ``array([[0, 1], [0, 1]])``
+    shape : (N,) tuple of ints
+        Shape of the output array, which also determines the shape of
+        the coordinate arrays passed to `function`.
+    dtype : data-type, optional
+        Data-type of the coordinate arrays passed to `function`.
+        By default, `dtype` is float.
+    ${ARRAY_FUNCTION_LIKE}
+
+        .. versionadded:: 1.20.0
+
+    Returns
+    -------
+    fromfunction : any
+        The result of the call to `function` is passed back directly.
+        Therefore the shape of `fromfunction` is completely determined by
+        `function`.  If `function` returns a scalar value, the shape of
+        `fromfunction` would not match the `shape` parameter.
+
+    See Also
+    --------
+    indices, meshgrid
+
+    Notes
+    -----
+    Keywords other than `dtype` and `like` are passed to `function`.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.fromfunction(lambda i, j: i, (2, 2), dtype=np.float64)
+    array([[0., 0.],
+           [1., 1.]])
+
+    >>> np.fromfunction(lambda i, j: j, (2, 2), dtype=np.float64)
+    array([[0., 1.],
+           [0., 1.]])
+
+    >>> np.fromfunction(lambda i, j: i == j, (3, 3), dtype=np.int_)
+    array([[ True, False, False],
+           [False,  True, False],
+           [False, False,  True]])
+
+    >>> np.fromfunction(lambda i, j: i + j, (3, 3), dtype=np.int_)
+    array([[0, 1, 2],
+           [1, 2, 3],
+           [2, 3, 4]])
+
+    """
+    if like is not None:
+        return _fromfunction_with_like(
+                like, function, shape, dtype=dtype, **kwargs)
+
+    args = indices(shape, dtype=dtype)
+    return function(*args, **kwargs)
+
+
+_fromfunction_with_like = array_function_dispatch()(fromfunction)
+
+
+def _frombuffer(buf, dtype, shape, order, axis_order=None):
+    array = frombuffer(buf, dtype=dtype)
+    if order == 'K' and axis_order is not None:
+        return array.reshape(shape, order='C').transpose(axis_order)
+    return array.reshape(shape, order=order)
+
+
+@set_module('numpy')
+def isscalar(element):
+    """
+    Returns True if the type of `element` is a scalar type.
+
+    Parameters
+    ----------
+    element : any
+        Input argument, can be of any type and shape.
+
+    Returns
+    -------
+    val : bool
+        True if `element` is a scalar type, False if it is not.
+
+    See Also
+    --------
+    ndim : Get the number of dimensions of an array
+
+    Notes
+    -----
+    If you need a stricter way to identify a *numerical* scalar, use
+    ``isinstance(x, numbers.Number)``, as that returns ``False`` for most
+    non-numerical elements such as strings.
+
+    In most cases ``np.ndim(x) == 0`` should be used instead of this function,
+    as that will also return true for 0d arrays. This is how numpy overloads
+    functions in the style of the ``dx`` arguments to `gradient` and
+    the ``bins`` argument to `histogram`. Some key differences:
+
+    +------------------------------------+---------------+-------------------+
+    | x                                  |``isscalar(x)``|``np.ndim(x) == 0``|
+    +====================================+===============+===================+
+    | PEP 3141 numeric objects           | ``True``      | ``True``          |
+    | (including builtins)               |               |                   |
+    +------------------------------------+---------------+-------------------+
+    | builtin string and buffer objects  | ``True``      | ``True``          |
+    +------------------------------------+---------------+-------------------+
+    | other builtin objects, like        | ``False``     | ``True``          |
+    | `pathlib.Path`, `Exception`,       |               |                   |
+    | the result of `re.compile`         |               |                   |
+    +------------------------------------+---------------+-------------------+
+    | third-party objects like           | ``False``     | ``True``          |
+    | `matplotlib.figure.Figure`         |               |                   |
+    +------------------------------------+---------------+-------------------+
+    | zero-dimensional numpy arrays      | ``False``     | ``True``          |
+    +------------------------------------+---------------+-------------------+
+    | other numpy arrays                 | ``False``     | ``False``         |
+    +------------------------------------+---------------+-------------------+
+    | `list`, `tuple`, and other         | ``False``     | ``False``         |
+    | sequence objects                   |               |                   |
+    +------------------------------------+---------------+-------------------+
+
+    Examples
+    --------
+    >>> import numpy as np
+
+    >>> np.isscalar(3.1)
+    True
+
+    >>> np.isscalar(np.array(3.1))
+    False
+
+    >>> np.isscalar([3.1])
+    False
+
+    >>> np.isscalar(False)
+    True
+
+    >>> np.isscalar('numpy')
+    True
+
+    NumPy supports PEP 3141 numbers:
+
+    >>> from fractions import Fraction
+    >>> np.isscalar(Fraction(5, 17))
+    True
+    >>> from numbers import Number
+    >>> np.isscalar(Number())
+    True
+
+    """
+    return (isinstance(element, generic)
+            or type(element) in ScalarType
+            or isinstance(element, numbers.Number))
+
+
+@set_module('numpy')
+def binary_repr(num, width=None):
+    """
+    Return the binary representation of the input number as a string.
+
+    For negative numbers, if width is not given, a minus sign is added to the
+    front. If width is given, the two's complement of the number is
+    returned, with respect to that width.
+
+    In a two's-complement system negative numbers are represented by the two's
+    complement of the absolute value. This is the most common method of
+    representing signed integers on computers [1]_. An N-bit two's-complement
+    system can represent every integer in the range
+    :math:`-2^{N-1}` to :math:`+2^{N-1}-1`.
+
+    Parameters
+    ----------
+    num : int
+        Only an integer decimal number can be used.
+    width : int, optional
+        The length of the returned string if `num` is positive, or the length
+        of the two's complement if `num` is negative, provided that `width` is
+        at least a sufficient number of bits for `num` to be represented in
+        the designated form. If the `width` value is insufficient, an error is
+        raised.
+
+    Returns
+    -------
+    bin : str
+        Binary representation of `num` or two's complement of `num`.
+
+    See Also
+    --------
+    base_repr: Return a string representation of a number in the given base
+               system.
+    bin: Python's built-in binary representation generator of an integer.
+
+    Notes
+    -----
+    `binary_repr` is equivalent to using `base_repr` with base 2, but about 25x
+    faster.
+
+    References
+    ----------
+    .. [1] Wikipedia, "Two's complement",
+        https://en.wikipedia.org/wiki/Two's_complement
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.binary_repr(3)
+    '11'
+    >>> np.binary_repr(-3)
+    '-11'
+    >>> np.binary_repr(3, width=4)
+    '0011'
+
+    The two's complement is returned when the input number is negative and
+    width is specified:
+
+    >>> np.binary_repr(-3, width=3)
+    '101'
+    >>> np.binary_repr(-3, width=5)
+    '11101'
+
+    """
+    def err_if_insufficient(width, binwidth):
+        if width is not None and width < binwidth:
+            raise ValueError(
+                f"Insufficient bit {width=} provided for {binwidth=}"
+            )
+
+    # Ensure that num is a Python integer to avoid overflow or unwanted
+    # casts to floating point.
+    num = operator.index(num)
+
+    if num == 0:
+        return '0' * (width or 1)
+
+    elif num > 0:
+        binary = f'{num:b}'
+        binwidth = len(binary)
+        outwidth = (binwidth if width is None
+                    else builtins.max(binwidth, width))
+        err_if_insufficient(width, binwidth)
+        return binary.zfill(outwidth)
+
+    elif width is None:
+        return f'-{-num:b}'
+
+    else:
+        poswidth = len(f'{-num:b}')
+
+        # See gh-8679: remove extra digit
+        # for numbers at boundaries.
+        if 2**(poswidth - 1) == -num:
+            poswidth -= 1
+
+        twocomp = 2**(poswidth + 1) + num
+        binary = f'{twocomp:b}'
+        binwidth = len(binary)
+
+        outwidth = builtins.max(binwidth, width)
+        err_if_insufficient(width, binwidth)
+        return '1' * (outwidth - binwidth) + binary
+
+
+@set_module('numpy')
+def base_repr(number, base=2, padding=0):
+    """
+    Return a string representation of a number in the given base system.
+
+    Parameters
+    ----------
+    number : int
+        The value to convert. Positive and negative values are handled.
+    base : int, optional
+        Convert `number` to the `base` number system. The valid range is 2-36,
+        the default value is 2.
+    padding : int, optional
+        Number of zeros padded on the left. Default is 0 (no padding).
+
+    Returns
+    -------
+    out : str
+        String representation of `number` in `base` system.
+
+    See Also
+    --------
+    binary_repr : Faster version of `base_repr` for base 2.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.base_repr(5)
+    '101'
+    >>> np.base_repr(6, 5)
+    '11'
+    >>> np.base_repr(7, base=5, padding=3)
+    '00012'
+
+    >>> np.base_repr(10, base=16)
+    'A'
+    >>> np.base_repr(32, base=16)
+    '20'
+
+    """
+    digits = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+    if base > len(digits):
+        raise ValueError("Bases greater than 36 not handled in base_repr.")
+    elif base < 2:
+        raise ValueError("Bases less than 2 not handled in base_repr.")
+
+    num = abs(int(number))
+    res = []
+    while num:
+        res.append(digits[num % base])
+        num //= base
+    if padding:
+        res.append('0' * padding)
+    if number < 0:
+        res.append('-')
+    return ''.join(reversed(res or '0'))
+
+
+# These are all essentially abbreviations
+# These might wind up in a special abbreviations module
+
+
+def _maketup(descr, val):
+    dt = dtype(descr)
+    # Place val in all scalar tuples:
+    fields = dt.fields
+    if fields is None:
+        return val
+    else:
+        res = [_maketup(fields[name][0], val) for name in dt.names]
+        return tuple(res)
+
+
+@finalize_array_function_like
+@set_module('numpy')
+def identity(n, dtype=None, *, like=None):
+    """
+    Return the identity array.
+
+    The identity array is a square array with ones on
+    the main diagonal.
+
+    Parameters
+    ----------
+    n : int
+        Number of rows (and columns) in `n` x `n` output.
+    dtype : data-type, optional
+        Data-type of the output.  Defaults to ``float``.
+    ${ARRAY_FUNCTION_LIKE}
+
+        .. versionadded:: 1.20.0
+
+    Returns
+    -------
+    out : ndarray
+        `n` x `n` array with its main diagonal set to one,
+        and all other elements 0.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.identity(3)
+    array([[1.,  0.,  0.],
+           [0.,  1.,  0.],
+           [0.,  0.,  1.]])
+
+    """
+    if like is not None:
+        return _identity_with_like(like, n, dtype=dtype)
+
+    from numpy import eye
+    return eye(n, dtype=dtype, like=like)
+
+
+_identity_with_like = array_function_dispatch()(identity)
+
+
+def _allclose_dispatcher(a, b, rtol=None, atol=None, equal_nan=None):
+    return (a, b, rtol, atol)
+
+
+@array_function_dispatch(_allclose_dispatcher)
+def allclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False):
+    """
+    Returns True if two arrays are element-wise equal within a tolerance.
+
+    The tolerance values are positive, typically very small numbers.  The
+    relative difference (`rtol` * abs(`b`)) and the absolute difference
+    `atol` are added together to compare against the absolute difference
+    between `a` and `b`.
+
+    .. warning:: The default `atol` is not appropriate for comparing numbers
+                 with magnitudes much smaller than one (see Notes).
+
+    NaNs are treated as equal if they are in the same place and if
+    ``equal_nan=True``.  Infs are treated as equal if they are in the same
+    place and of the same sign in both arrays.
+
+    Parameters
+    ----------
+    a, b : array_like
+        Input arrays to compare.
+    rtol : array_like
+        The relative tolerance parameter (see Notes).
+    atol : array_like
+        The absolute tolerance parameter (see Notes).
+    equal_nan : bool
+        Whether to compare NaN's as equal.  If True, NaN's in `a` will be
+        considered equal to NaN's in `b` in the output array.
+
+    Returns
+    -------
+    allclose : bool
+        Returns True if the two arrays are equal within the given
+        tolerance; False otherwise.
+
+    See Also
+    --------
+    isclose, all, any, equal
+
+    Notes
+    -----
+    If the following equation is element-wise True, then allclose returns
+    True.::
+
+     absolute(a - b) <= (atol + rtol * absolute(b))
+
+    The above equation is not symmetric in `a` and `b`, so that
+    ``allclose(a, b)`` might be different from ``allclose(b, a)`` in
+    some rare cases.
+
+    The default value of `atol` is not appropriate when the reference value
+    `b` has magnitude smaller than one. For example, it is unlikely that
+    ``a = 1e-9`` and ``b = 2e-9`` should be considered "close", yet
+    ``allclose(1e-9, 2e-9)`` is ``True`` with default settings. Be sure
+    to select `atol` for the use case at hand, especially for defining the
+    threshold below which a non-zero value in `a` will be considered "close"
+    to a very small or zero value in `b`.
+
+    The comparison of `a` and `b` uses standard broadcasting, which
+    means that `a` and `b` need not have the same shape in order for
+    ``allclose(a, b)`` to evaluate to True.  The same is true for
+    `equal` but not `array_equal`.
+
+    `allclose` is not defined for non-numeric data types.
+    `bool` is considered a numeric data-type for this purpose.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.allclose([1e10,1e-7], [1.00001e10,1e-8])
+    False
+
+    >>> np.allclose([1e10,1e-8], [1.00001e10,1e-9])
+    True
+
+    >>> np.allclose([1e10,1e-8], [1.0001e10,1e-9])
+    False
+
+    >>> np.allclose([1.0, np.nan], [1.0, np.nan])
+    False
+
+    >>> np.allclose([1.0, np.nan], [1.0, np.nan], equal_nan=True)
+    True
+
+
+    """
+    res = all(isclose(a, b, rtol=rtol, atol=atol, equal_nan=equal_nan))
+    return builtins.bool(res)
+
+
+def _isclose_dispatcher(a, b, rtol=None, atol=None, equal_nan=None):
+    return (a, b, rtol, atol)
+
+
+@array_function_dispatch(_isclose_dispatcher)
+def isclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False):
+    """
+    Returns a boolean array where two arrays are element-wise equal within a
+    tolerance.
+
+    The tolerance values are positive, typically very small numbers.  The
+    relative difference (`rtol` * abs(`b`)) and the absolute difference
+    `atol` are added together to compare against the absolute difference
+    between `a` and `b`.
+
+    .. warning:: The default `atol` is not appropriate for comparing numbers
+                 with magnitudes much smaller than one (see Notes).
+
+    Parameters
+    ----------
+    a, b : array_like
+        Input arrays to compare.
+    rtol : array_like
+        The relative tolerance parameter (see Notes).
+    atol : array_like
+        The absolute tolerance parameter (see Notes).
+    equal_nan : bool
+        Whether to compare NaN's as equal.  If True, NaN's in `a` will be
+        considered equal to NaN's in `b` in the output array.
+
+    Returns
+    -------
+    y : array_like
+        Returns a boolean array of where `a` and `b` are equal within the
+        given tolerance. If both `a` and `b` are scalars, returns a single
+        boolean value.
+
+    See Also
+    --------
+    allclose
+    math.isclose
+
+    Notes
+    -----
+    For finite values, isclose uses the following equation to test whether
+    two floating point values are equivalent.::
+
+     absolute(a - b) <= (atol + rtol * absolute(b))
+
+    Unlike the built-in `math.isclose`, the above equation is not symmetric
+    in `a` and `b` -- it assumes `b` is the reference value -- so that
+    `isclose(a, b)` might be different from `isclose(b, a)`.
+
+    The default value of `atol` is not appropriate when the reference value
+    `b` has magnitude smaller than one. For example, it is unlikely that
+    ``a = 1e-9`` and ``b = 2e-9`` should be considered "close", yet
+    ``isclose(1e-9, 2e-9)`` is ``True`` with default settings. Be sure
+    to select `atol` for the use case at hand, especially for defining the
+    threshold below which a non-zero value in `a` will be considered "close"
+    to a very small or zero value in `b`.
+
+    `isclose` is not defined for non-numeric data types.
+    :class:`bool` is considered a numeric data-type for this purpose.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.isclose([1e10,1e-7], [1.00001e10,1e-8])
+    array([ True, False])
+
+    >>> np.isclose([1e10,1e-8], [1.00001e10,1e-9])
+    array([ True, True])
+
+    >>> np.isclose([1e10,1e-8], [1.0001e10,1e-9])
+    array([False,  True])
+
+    >>> np.isclose([1.0, np.nan], [1.0, np.nan])
+    array([ True, False])
+
+    >>> np.isclose([1.0, np.nan], [1.0, np.nan], equal_nan=True)
+    array([ True, True])
+
+    >>> np.isclose([1e-8, 1e-7], [0.0, 0.0])
+    array([ True, False])
+
+    >>> np.isclose([1e-100, 1e-7], [0.0, 0.0], atol=0.0)
+    array([False, False])
+
+    >>> np.isclose([1e-10, 1e-10], [1e-20, 0.0])
+    array([ True,  True])
+
+    >>> np.isclose([1e-10, 1e-10], [1e-20, 0.999999e-10], atol=0.0)
+    array([False,  True])
+
+    """
+    # Turn all but python scalars into arrays.
+    x, y, atol, rtol = (
+        a if isinstance(a, (int, float, complex)) else asanyarray(a)
+        for a in (a, b, atol, rtol))
+
+    # Make sure y is an inexact type to avoid bad behavior on abs(MIN_INT).
+    # This will cause casting of x later. Also, make sure to allow subclasses
+    # (e.g., for numpy.ma).
+    # NOTE: We explicitly allow timedelta, which used to work. This could
+    #       possibly be deprecated. See also gh-18286.
+    #       timedelta works if `atol` is an integer or also a timedelta.
+    #       Although, the default tolerances are unlikely to be useful
+    if (dtype := getattr(y, "dtype", None)) is not None and dtype.kind != "m":
+        dt = multiarray.result_type(y, 1.)
+        y = asanyarray(y, dtype=dt)
+    elif isinstance(y, int):
+        y = float(y)
+
+    # atol and rtol can be arrays
+    if not (np.all(np.isfinite(atol)) and np.all(np.isfinite(rtol))):
+        err_s = np.geterr()["invalid"]
+        err_msg = f"One of rtol or atol is not valid, atol: {atol}, rtol: {rtol}"
+
+        if err_s == "warn":
+            warnings.warn(err_msg, RuntimeWarning, stacklevel=2)
+        elif err_s == "raise":
+            raise FloatingPointError(err_msg)
+        elif err_s == "print":
+            print(err_msg)
+
+    with errstate(invalid='ignore'):
+
+        result = (less_equal(abs(x - y), atol + rtol * abs(y))
+                  & isfinite(y)
+                  | (x == y))
+        if equal_nan:
+            result |= isnan(x) & isnan(y)
+
+    return result[()]  # Flatten 0d arrays to scalars
+
+
+def _array_equal_dispatcher(a1, a2, equal_nan=None):
+    return (a1, a2)
+
+
+_no_nan_types = {
+    # should use np.dtype.BoolDType, but as of writing
+    # that fails the reloading test.
+    type(dtype(nt.bool)),
+    type(dtype(nt.int8)),
+    type(dtype(nt.int16)),
+    type(dtype(nt.int32)),
+    type(dtype(nt.int64)),
+}
+
+
+def _dtype_cannot_hold_nan(dtype):
+    return type(dtype) in _no_nan_types
+
+
+@array_function_dispatch(_array_equal_dispatcher)
+def array_equal(a1, a2, equal_nan=False):
+    """
+    True if two arrays have the same shape and elements, False otherwise.
+
+    Parameters
+    ----------
+    a1, a2 : array_like
+        Input arrays.
+    equal_nan : bool
+        Whether to compare NaN's as equal. If the dtype of a1 and a2 is
+        complex, values will be considered equal if either the real or the
+        imaginary component of a given value is ``nan``.
+
+    Returns
+    -------
+    b : bool
+        Returns True if the arrays are equal.
+
+    See Also
+    --------
+    allclose: Returns True if two arrays are element-wise equal within a
+              tolerance.
+    array_equiv: Returns True if input arrays are shape consistent and all
+                 elements equal.
+
+    Examples
+    --------
+    >>> import numpy as np
+
+    >>> np.array_equal([1, 2], [1, 2])
+    True
+
+    >>> np.array_equal(np.array([1, 2]), np.array([1, 2]))
+    True
+
+    >>> np.array_equal([1, 2], [1, 2, 3])
+    False
+
+    >>> np.array_equal([1, 2], [1, 4])
+    False
+
+    >>> a = np.array([1, np.nan])
+    >>> np.array_equal(a, a)
+    False
+
+    >>> np.array_equal(a, a, equal_nan=True)
+    True
+
+    When ``equal_nan`` is True, complex values with nan components are
+    considered equal if either the real *or* the imaginary components are nan.
+
+    >>> a = np.array([1 + 1j])
+    >>> b = a.copy()
+    >>> a.real = np.nan
+    >>> b.imag = np.nan
+    >>> np.array_equal(a, b, equal_nan=True)
+    True
+    """
+    try:
+        a1, a2 = asarray(a1), asarray(a2)
+    except Exception:
+        return False
+    if a1.shape != a2.shape:
+        return False
+    if not equal_nan:
+        return builtins.bool((asanyarray(a1 == a2)).all())
+
+    if a1 is a2:
+        # nan will compare equal so an array will compare equal to itself.
+        return True
+
+    cannot_have_nan = (_dtype_cannot_hold_nan(a1.dtype)
+                       and _dtype_cannot_hold_nan(a2.dtype))
+    if cannot_have_nan:
+        return builtins.bool(asarray(a1 == a2).all())
+
+    # Fast path for a1 and a2 being all NaN arrays
+    a1nan = isnan(a1)
+    if a1nan.all():
+        return builtins.bool(isnan(a2).all())
+
+    equal_or_both_nan = (a1 == a2) | (a1nan & isnan(a2))
+    return builtins.bool(equal_or_both_nan.all())
+
+
+def _array_equiv_dispatcher(a1, a2):
+    return (a1, a2)
+
+
+@array_function_dispatch(_array_equiv_dispatcher)
+def array_equiv(a1, a2):
+    """
+    Returns True if input arrays are shape consistent and all elements equal.
+
+    Shape consistent means they are either the same shape, or one input array
+    can be broadcasted to create the same shape as the other one.
+
+    Parameters
+    ----------
+    a1, a2 : array_like
+        Input arrays.
+
+    Returns
+    -------
+    out : bool
+        True if equivalent, False otherwise.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.array_equiv([1, 2], [1, 2])
+    True
+    >>> np.array_equiv([1, 2], [1, 3])
+    False
+
+    Showing the shape equivalence:
+
+    >>> np.array_equiv([1, 2], [[1, 2], [1, 2]])
+    True
+    >>> np.array_equiv([1, 2], [[1, 2, 1, 2], [1, 2, 1, 2]])
+    False
+
+    >>> np.array_equiv([1, 2], [[1, 2], [1, 3]])
+    False
+
+    """
+    try:
+        a1, a2 = asarray(a1), asarray(a2)
+    except Exception:
+        return False
+    try:
+        multiarray.broadcast(a1, a2)
+    except Exception:
+        return False
+
+    return builtins.bool(asanyarray(a1 == a2).all())
+
+
+def _astype_dispatcher(x, dtype, /, *, copy=None, device=None):
+    return (x, dtype)
+
+
+@array_function_dispatch(_astype_dispatcher)
+def astype(x, dtype, /, *, copy=True, device=None):
+    """
+    Copies an array to a specified data type.
+
+    This function is an Array API compatible alternative to
+    `numpy.ndarray.astype`.
+
+    Parameters
+    ----------
+    x : ndarray
+        Input NumPy array to cast. ``array_likes`` are explicitly not
+        supported here.
+    dtype : dtype
+        Data type of the result.
+    copy : bool, optional
+        Specifies whether to copy an array when the specified dtype matches
+        the data type of the input array ``x``. If ``True``, a newly allocated
+        array must always be returned. If ``False`` and the specified dtype
+        matches the data type of the input array, the input array must be
+        returned; otherwise, a newly allocated array must be returned.
+        Defaults to ``True``.
+    device : str, optional
+        The device on which to place the returned array. Default: None.
+        For Array-API interoperability only, so must be ``"cpu"`` if passed.
+
+        .. versionadded:: 2.1.0
+
+    Returns
+    -------
+    out : ndarray
+        An array having the specified data type.
+
+    See Also
+    --------
+    ndarray.astype
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> arr = np.array([1, 2, 3]); arr
+    array([1, 2, 3])
+    >>> np.astype(arr, np.float64)
+    array([1., 2., 3.])
+
+    Non-copy case:
+
+    >>> arr = np.array([1, 2, 3])
+    >>> arr_noncpy = np.astype(arr, arr.dtype, copy=False)
+    >>> np.shares_memory(arr, arr_noncpy)
+    True
+
+    """
+    if not (isinstance(x, np.ndarray) or isscalar(x)):
+        raise TypeError(
+            "Input should be a NumPy array or scalar. "
+            f"It is a {type(x)} instead."
+        )
+    if device is not None and device != "cpu":
+        raise ValueError(
+            'Device not understood. Only "cpu" is allowed, but received:'
+            f' {device}'
+        )
+    return x.astype(dtype, copy=copy)
+
+
+inf = PINF
+nan = NAN
+False_ = nt.bool(False)
+True_ = nt.bool(True)
+
+
+def extend_all(module):
+    existing = set(__all__)
+    mall = module.__all__
+    for a in mall:
+        if a not in existing:
+            __all__.append(a)
+
+
+from . import _asarray, _ufunc_config, arrayprint, fromnumeric
+from ._asarray import *
+from ._ufunc_config import *
+from .arrayprint import *
+from .fromnumeric import *
+from .numerictypes import *
+from .umath import *
+
+extend_all(fromnumeric)
+extend_all(umath)
+extend_all(numerictypes)
+extend_all(arrayprint)
+extend_all(_asarray)
+extend_all(_ufunc_config)

v12x/pylib/numpy/_core/numerictypes.py

@@ -0,0 +1,576 @@
+"""
+numerictypes: Define the numeric type objects
+
+This module is designed so "from numerictypes import \\*" is safe.
+Exported symbols include:
+
+  Dictionary with all registered number types (including aliases):
+    sctypeDict
+
+  Type objects (not all will be available, depends on platform):
+      see variable sctypes for which ones you have
+
+    Bit-width names
+
+    int8 int16 int32 int64
+    uint8 uint16 uint32 uint64
+    float16 float32 float64 float96 float128
+    complex64 complex128 complex192 complex256
+    datetime64 timedelta64
+
+    c-based names
+
+    bool
+
+    object_
+
+    void, str_
+
+    byte, ubyte,
+    short, ushort
+    intc, uintc,
+    intp, uintp,
+    int_, uint,
+    longlong, ulonglong,
+
+    single, csingle,
+    double, cdouble,
+    longdouble, clongdouble,
+
+   As part of the type-hierarchy:    xx -- is bit-width
+
+   generic
+     +-> bool                                   (kind=b)
+     +-> number
+     |   +-> integer
+     |   |   +-> signedinteger     (intxx)      (kind=i)
+     |   |   |     byte
+     |   |   |     short
+     |   |   |     intc
+     |   |   |     intp
+     |   |   |     int_
+     |   |   |     longlong
+     |   |   \\-> unsignedinteger  (uintxx)     (kind=u)
+     |   |         ubyte
+     |   |         ushort
+     |   |         uintc
+     |   |         uintp
+     |   |         uint
+     |   |         ulonglong
+     |   +-> inexact
+     |       +-> floating          (floatxx)    (kind=f)
+     |       |     half
+     |       |     single
+     |       |     double
+     |       |     longdouble
+     |       \\-> complexfloating  (complexxx)  (kind=c)
+     |             csingle
+     |             cdouble
+     |             clongdouble
+     +-> flexible
+     |   +-> character
+     |   |     bytes_                           (kind=S)
+     |   |     str_                             (kind=U)
+     |   |
+     |   \\-> void                              (kind=V)
+     \\-> object_ (not used much)               (kind=O)
+
+"""
+import numbers
+
+from numpy._utils import set_module
+
+from . import multiarray as ma
+from ._multiarray_umath import StringDType
+from .multiarray import (
+    busday_count,
+    busday_offset,
+    busdaycalendar,
+    datetime_as_string,
+    datetime_data,
+    dtype,
+    is_busday,
+    ndarray,
+)
+
+# we add more at the bottom
+__all__ = [
+    'ScalarType', 'typecodes', 'issubdtype', 'datetime_data',
+    'datetime_as_string', 'busday_offset', 'busday_count',
+    'is_busday', 'busdaycalendar', 'isdtype'
+]
+
+# we don't need all these imports, but we need to keep them for compatibility
+# for users using np._core.numerictypes.UPPER_TABLE
+# we don't export these for import *, but we do want them accessible
+# as numerictypes.bool, etc.
+from builtins import bool, bytes, complex, float, int, object, str  # noqa: F401, UP029
+
+from ._string_helpers import (  # noqa: F401
+    LOWER_TABLE,
+    UPPER_TABLE,
+    english_capitalize,
+    english_lower,
+    english_upper,
+)
+from ._type_aliases import allTypes, sctypeDict, sctypes
+
+# We use this later
+generic = allTypes['generic']
+
+genericTypeRank = ['bool', 'int8', 'uint8', 'int16', 'uint16',
+                   'int32', 'uint32', 'int64', 'uint64',
+                   'float16', 'float32', 'float64', 'float96', 'float128',
+                   'complex64', 'complex128', 'complex192', 'complex256',
+                   'object']
+
+
+@set_module('numpy')
+def issctype(rep):
+    """
+    Determines whether the given object represents a scalar data-type.
+
+    Parameters
+    ----------
+    rep : any
+        If `rep` is an instance of a scalar dtype, True is returned. If not,
+        False is returned.
+
+    Returns
+    -------
+    out : bool
+        Boolean result of check whether `rep` is a scalar dtype.
+
+    See Also
+    --------
+    issubsctype, issubdtype, obj2sctype, sctype2char
+
+    Examples
+    --------
+    >>> from numpy._core.numerictypes import issctype
+    >>> issctype(np.int32)
+    True
+    >>> issctype(list)
+    False
+    >>> issctype(1.1)
+    False
+
+    Strings are also a scalar type:
+
+    >>> issctype(np.dtype(np.str_))
+    True
+
+    """
+    if not isinstance(rep, (type, dtype)):
+        return False
+    try:
+        res = obj2sctype(rep)
+        if res and res != object_:
+            return True
+        else:
+            return False
+    except Exception:
+        return False
+
+
+def obj2sctype(rep, default=None):
+    """
+    Return the scalar dtype or NumPy equivalent of Python type of an object.
+
+    Parameters
+    ----------
+    rep : any
+        The object of which the type is returned.
+    default : any, optional
+        If given, this is returned for objects whose types can not be
+        determined. If not given, None is returned for those objects.
+
+    Returns
+    -------
+    dtype : dtype or Python type
+        The data type of `rep`.
+
+    See Also
+    --------
+    sctype2char, issctype, issubsctype, issubdtype
+
+    Examples
+    --------
+    >>> from numpy._core.numerictypes import obj2sctype
+    >>> obj2sctype(np.int32)
+    <class 'numpy.int32'>
+    >>> obj2sctype(np.array([1., 2.]))
+    <class 'numpy.float64'>
+    >>> obj2sctype(np.array([1.j]))
+    <class 'numpy.complex128'>
+
+    >>> obj2sctype(dict)
+    <class 'numpy.object_'>
+    >>> obj2sctype('string')
+
+    >>> obj2sctype(1, default=list)
+    <class 'list'>
+
+    """
+    # prevent abstract classes being upcast
+    if isinstance(rep, type) and issubclass(rep, generic):
+        return rep
+    # extract dtype from arrays
+    if isinstance(rep, ndarray):
+        return rep.dtype.type
+    # fall back on dtype to convert
+    try:
+        res = dtype(rep)
+    except Exception:
+        return default
+    else:
+        return res.type
+
+
+@set_module('numpy')
+def issubclass_(arg1, arg2):
+    """
+    Determine if a class is a subclass of a second class.
+
+    `issubclass_` is equivalent to the Python built-in ``issubclass``,
+    except that it returns False instead of raising a TypeError if one
+    of the arguments is not a class.
+
+    Parameters
+    ----------
+    arg1 : class
+        Input class. True is returned if `arg1` is a subclass of `arg2`.
+    arg2 : class or tuple of classes.
+        Input class. If a tuple of classes, True is returned if `arg1` is a
+        subclass of any of the tuple elements.
+
+    Returns
+    -------
+    out : bool
+        Whether `arg1` is a subclass of `arg2` or not.
+
+    See Also
+    --------
+    issubsctype, issubdtype, issctype
+
+    Examples
+    --------
+    >>> np.issubclass_(np.int32, int)
+    False
+    >>> np.issubclass_(np.int32, float)
+    False
+    >>> np.issubclass_(np.float64, float)
+    True
+
+    """
+    try:
+        return issubclass(arg1, arg2)
+    except TypeError:
+        return False
+
+
+@set_module('numpy')
+def issubsctype(arg1, arg2):
+    """
+    Determine if the first argument is a subclass of the second argument.
+
+    Parameters
+    ----------
+    arg1, arg2 : dtype or dtype specifier
+        Data-types.
+
+    Returns
+    -------
+    out : bool
+        The result.
+
+    See Also
+    --------
+    issctype, issubdtype, obj2sctype
+
+    Examples
+    --------
+    >>> from numpy._core import issubsctype
+    >>> issubsctype('S8', str)
+    False
+    >>> issubsctype(np.array([1]), int)
+    True
+    >>> issubsctype(np.array([1]), float)
+    False
+
+    """
+    return issubclass(obj2sctype(arg1), obj2sctype(arg2))
+
+
+class _PreprocessDTypeError(Exception):
+    pass
+
+
+def _preprocess_dtype(dtype):
+    """
+    Preprocess dtype argument by:
+      1. fetching type from a data type
+      2. verifying that types are built-in NumPy dtypes
+    """
+    orig_dtype = dtype
+    if isinstance(dtype, ma.dtype):
+        dtype = dtype.type
+    if isinstance(dtype, ndarray) or dtype not in allTypes.values():
+        if isinstance(orig_dtype, StringDType) or orig_dtype is StringDType:
+            # StringDType's scalar type is the builtin `str`, which is not
+            # a NumPy scalar type, so use the DType class to identify it.
+            # if we ever fix gh-28165, this should be deleted
+            return StringDType
+        raise _PreprocessDTypeError
+    return dtype
+
+
+@set_module('numpy')
+def isdtype(dtype, kind):
+    """
+    Determine if a provided dtype is of a specified data type ``kind``.
+
+    This function only supports built-in NumPy's data types.
+    Third-party dtypes are not yet supported.
+
+    Parameters
+    ----------
+    dtype : dtype
+        The input dtype.
+    kind : dtype or str or tuple of dtypes/strs.
+        dtype or dtype kind. Allowed dtype kinds are:
+        * ``'bool'`` : boolean kind
+        * ``'signed integer'`` : signed integer data types
+        * ``'unsigned integer'`` : unsigned integer data types
+        * ``'integral'`` : integer data types
+        * ``'real floating'`` : real-valued floating-point data types
+        * ``'complex floating'`` : complex floating-point data types
+        * ``'numeric'`` : numeric data types
+
+    Returns
+    -------
+    out : bool
+
+    See Also
+    --------
+    issubdtype
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.isdtype(np.float32, np.float64)
+    False
+    >>> np.isdtype(np.float32, "real floating")
+    True
+    >>> np.isdtype(np.complex128, ("real floating", "complex floating"))
+    True
+
+    """
+    try:
+        dtype = _preprocess_dtype(dtype)
+    except _PreprocessDTypeError:
+        raise TypeError(
+            "dtype argument must be a NumPy dtype, "
+            f"but it is a {type(dtype)}."
+        ) from None
+
+    input_kinds = kind if isinstance(kind, tuple) else (kind,)
+
+    processed_kinds = set()
+
+    for kind in input_kinds:
+        if kind == "bool":
+            processed_kinds.add(allTypes["bool"])
+        elif kind == "signed integer":
+            processed_kinds.update(sctypes["int"])
+        elif kind == "unsigned integer":
+            processed_kinds.update(sctypes["uint"])
+        elif kind == "integral":
+            processed_kinds.update(sctypes["int"] + sctypes["uint"])
+        elif kind == "real floating":
+            processed_kinds.update(sctypes["float"])
+        elif kind == "complex floating":
+            processed_kinds.update(sctypes["complex"])
+        elif kind == "numeric":
+            processed_kinds.update(
+                sctypes["int"] + sctypes["uint"] +
+                sctypes["float"] + sctypes["complex"]
+            )
+        elif isinstance(kind, str):
+            raise ValueError(
+                "kind argument is a string, but"
+                f" {kind!r} is not a known kind name."
+            )
+        else:
+            try:
+                kind = _preprocess_dtype(kind)
+            except _PreprocessDTypeError:
+                raise TypeError(
+                    "kind argument must be comprised of "
+                    "NumPy dtypes or strings only, "
+                    f"but is a {type(kind)}."
+                ) from None
+            processed_kinds.add(kind)
+
+    return dtype in processed_kinds
+
+
+@set_module('numpy')
+def issubdtype(arg1, arg2):
+    r"""
+    Returns True if first argument is a typecode lower/equal in type hierarchy.
+
+    This is like the builtin :func:`issubclass`, but for `dtype`\ s.
+
+    Parameters
+    ----------
+    arg1, arg2 : dtype_like
+        `dtype` or object coercible to one
+
+    Returns
+    -------
+    out : bool
+
+    See Also
+    --------
+    :ref:`arrays.scalars` : Overview of the numpy type hierarchy.
+
+    Examples
+    --------
+    `issubdtype` can be used to check the type of arrays:
+
+    >>> ints = np.array([1, 2, 3], dtype=np.int32)
+    >>> np.issubdtype(ints.dtype, np.integer)
+    True
+    >>> np.issubdtype(ints.dtype, np.floating)
+    False
+
+    >>> floats = np.array([1, 2, 3], dtype=np.float32)
+    >>> np.issubdtype(floats.dtype, np.integer)
+    False
+    >>> np.issubdtype(floats.dtype, np.floating)
+    True
+
+    Similar types of different sizes are not subdtypes of each other:
+
+    >>> np.issubdtype(np.float64, np.float32)
+    False
+    >>> np.issubdtype(np.float32, np.float64)
+    False
+
+    but both are subtypes of `floating`:
+
+    >>> np.issubdtype(np.float64, np.floating)
+    True
+    >>> np.issubdtype(np.float32, np.floating)
+    True
+
+    For convenience, dtype-like objects are allowed too:
+
+    >>> np.issubdtype('S1', np.bytes_)
+    True
+    >>> np.issubdtype('i4', np.signedinteger)
+    True
+
+    """
+    if not issubclass_(arg1, generic):
+        arg1 = dtype(arg1).type
+    if not issubclass_(arg2, generic):
+        arg2 = dtype(arg2).type
+
+    return issubclass(arg1, arg2)
+
+
+@set_module('numpy')
+def sctype2char(sctype):
+    """
+    Return the string representation of a scalar dtype.
+
+    Parameters
+    ----------
+    sctype : scalar dtype or object
+        If a scalar dtype, the corresponding string character is
+        returned. If an object, `sctype2char` tries to infer its scalar type
+        and then return the corresponding string character.
+
+    Returns
+    -------
+    typechar : str
+        The string character corresponding to the scalar type.
+
+    Raises
+    ------
+    ValueError
+        If `sctype` is an object for which the type can not be inferred.
+
+    See Also
+    --------
+    obj2sctype, issctype, issubsctype, mintypecode
+
+    Examples
+    --------
+    >>> from numpy._core.numerictypes import sctype2char
+    >>> for sctype in [np.int32, np.double, np.cdouble, np.bytes_, np.ndarray]:
+    ...     print(sctype2char(sctype))
+    l # may vary
+    d
+    D
+    S
+    O
+
+    >>> x = np.array([1., 2-1.j])
+    >>> sctype2char(x)
+    'D'
+    >>> sctype2char(list)
+    'O'
+
+    """
+    sctype = obj2sctype(sctype)
+    if sctype is None:
+        raise ValueError("unrecognized type")
+    if sctype not in sctypeDict.values():
+        # for compatibility
+        raise KeyError(sctype)
+    return dtype(sctype).char
+
+
+def _scalar_type_key(typ):
+    """A ``key`` function for `sorted`."""
+    dt = dtype(typ)
+    return (dt.kind.lower(), dt.itemsize)
+
+
+ScalarType = [int, float, complex, bool, bytes, str, memoryview]
+ScalarType += sorted(dict.fromkeys(sctypeDict.values()), key=_scalar_type_key)
+ScalarType = tuple(ScalarType)
+
+
+# Now add the types we've determined to this module
+for key in allTypes:
+    globals()[key] = allTypes[key]
+    __all__.append(key)
+
+del key
+
+typecodes = {'Character': 'c',
+             'Integer': 'bhilqnp',
+             'UnsignedInteger': 'BHILQNP',
+             'Float': 'efdg',
+             'Complex': 'FDG',
+             'AllInteger': 'bBhHiIlLqQnNpP',
+             'AllFloat': 'efdgFDG',
+             'Datetime': 'Mm',
+             'All': '?bhilqnpBHILQNPefdgFDGSUVOMm'}
+
+# backwards compatibility --- deprecated name
+# Formal deprecation: Numpy 1.20.0, 2020-10-19 (see numpy/__init__.py)
+typeDict = sctypeDict
+
+def _register_types():
+    numbers.Integral.register(integer)
+    numbers.Complex.register(inexact)
+    numbers.Real.register(floating)
+    numbers.Number.register(number)
+
+
+_register_types()

v12x/pylib/numpy/_core/overrides.py

@@ -0,0 +1,188 @@
+"""Implementation of __array_function__ overrides from NEP-18."""
+import collections
+import functools
+import inspect
+
+from numpy._core._multiarray_umath import (
+    _ArrayFunctionDispatcher,
+    _get_implementing_args,
+    add_docstring,
+)
+from numpy._utils import set_module  # noqa: F401
+from numpy._utils._inspect import getargspec
+
+ARRAY_FUNCTIONS = set()
+
+array_function_like_doc = (
+    """like : array_like, optional
+        Reference object to allow the creation of arrays which are not
+        NumPy arrays. If an array-like passed in as ``like`` supports
+        the ``__array_function__`` protocol, the result will be defined
+        by it. In this case, it ensures the creation of an array object
+        compatible with that passed in via this argument."""
+)
+
+def get_array_function_like_doc(public_api, docstring_template=""):
+    ARRAY_FUNCTIONS.add(public_api)
+    docstring = public_api.__doc__ or docstring_template
+    return docstring.replace("${ARRAY_FUNCTION_LIKE}", array_function_like_doc)
+
+def finalize_array_function_like(public_api):
+    public_api.__doc__ = get_array_function_like_doc(public_api)
+    return public_api
+
+
+add_docstring(
+    _ArrayFunctionDispatcher,
+    """
+    Class to wrap functions with checks for __array_function__ overrides.
+
+    All arguments are required, and can only be passed by position.
+
+    Parameters
+    ----------
+    dispatcher : function or None
+        The dispatcher function that returns a single sequence-like object
+        of all arguments relevant.  It must have the same signature (except
+        the default values) as the actual implementation.
+        If ``None``, this is a ``like=`` dispatcher and the
+        ``_ArrayFunctionDispatcher`` must be called with ``like`` as the
+        first (additional and positional) argument.
+    implementation : function
+        Function that implements the operation on NumPy arrays without
+        overrides.  Arguments passed calling the ``_ArrayFunctionDispatcher``
+        will be forwarded to this (and the ``dispatcher``) as if using
+        ``*args, **kwargs``.
+
+    Attributes
+    ----------
+    _implementation : function
+        The original implementation passed in.
+    """)
+
+
+# exposed for testing purposes; used internally by _ArrayFunctionDispatcher
+add_docstring(
+    _get_implementing_args,
+    """
+    Collect arguments on which to call __array_function__.
+
+    Parameters
+    ----------
+    relevant_args : iterable of array-like
+        Iterable of possibly array-like arguments to check for
+        __array_function__ methods.
+
+    Returns
+    -------
+    Sequence of arguments with __array_function__ methods, in the order in
+    which they should be called.
+    """)
+
+
+ArgSpec = collections.namedtuple('ArgSpec', 'args varargs keywords defaults')
+
+
+def verify_matching_signatures(implementation, dispatcher):
+    """Verify that a dispatcher function has the right signature."""
+    implementation_spec = ArgSpec(*getargspec(implementation))
+    dispatcher_spec = ArgSpec(*getargspec(dispatcher))
+
+    if (implementation_spec.args != dispatcher_spec.args or
+            implementation_spec.varargs != dispatcher_spec.varargs or
+            implementation_spec.keywords != dispatcher_spec.keywords or
+            (bool(implementation_spec.defaults) !=
+             bool(dispatcher_spec.defaults)) or
+            (implementation_spec.defaults is not None and
+             len(implementation_spec.defaults) !=
+             len(dispatcher_spec.defaults))):
+        raise RuntimeError(f'implementation and dispatcher for {implementation} have '
+                           'different function signatures')
+
+    if implementation_spec.defaults is not None:
+        if dispatcher_spec.defaults != (None,) * len(dispatcher_spec.defaults):
+            raise RuntimeError('dispatcher functions can only use None for '
+                               'default argument values')
+
+
+def array_function_dispatch(dispatcher=None, module=None, verify=True,
+                            docs_from_dispatcher=False):
+    """Decorator for adding dispatch with the __array_function__ protocol.
+
+    See NEP-18 for example usage.
+
+    Parameters
+    ----------
+    dispatcher : callable or None
+        Function that when called like ``dispatcher(*args, **kwargs)`` with
+        arguments from the NumPy function call returns an iterable of
+        array-like arguments to check for ``__array_function__``.
+
+        If `None`, the first argument is used as the single `like=` argument
+        and not passed on.  A function implementing `like=` must call its
+        dispatcher with `like` as the first non-keyword argument.
+    module : str, optional
+        __module__ attribute to set on new function, e.g., ``module='numpy'``.
+        By default, module is copied from the decorated function.
+    verify : bool, optional
+        If True, verify the that the signature of the dispatcher and decorated
+        function signatures match exactly: all required and optional arguments
+        should appear in order with the same names, but the default values for
+        all optional arguments should be ``None``. Only disable verification
+        if the dispatcher's signature needs to deviate for some particular
+        reason, e.g., because the function has a signature like
+        ``func(*args, **kwargs)``.
+    docs_from_dispatcher : bool, optional
+        If True, copy docs from the dispatcher function onto the dispatched
+        function, rather than from the implementation. This is useful for
+        functions defined in C, which otherwise don't have docstrings.
+
+    Returns
+    -------
+    Function suitable for decorating the implementation of a NumPy function.
+
+    """
+    def decorator(implementation):
+        if verify:
+            if dispatcher is not None:
+                verify_matching_signatures(implementation, dispatcher)
+            else:
+                # Using __code__ directly similar to verify_matching_signature
+                co = implementation.__code__
+                last_arg = co.co_argcount + co.co_kwonlyargcount - 1
+                last_arg = co.co_varnames[last_arg]
+                if last_arg != "like" or co.co_kwonlyargcount == 0:
+                    raise RuntimeError(
+                        "__array_function__ expects `like=` to be the last "
+                        "argument and a keyword-only argument. "
+                        f"{implementation} does not seem to comply.")
+
+        if docs_from_dispatcher and dispatcher.__doc__ is not None:
+            doc = inspect.cleandoc(dispatcher.__doc__)
+            add_docstring(implementation, doc)
+
+        public_api = _ArrayFunctionDispatcher(dispatcher, implementation)
+        functools.update_wrapper(public_api, implementation)
+
+        if not verify and not getattr(implementation, "__text_signature__", None):
+            public_api.__signature__ = inspect.signature(dispatcher)
+
+        if module is not None:
+            public_api.__module__ = module
+
+        ARRAY_FUNCTIONS.add(public_api)
+
+        return public_api
+
+    return decorator
+
+
+def array_function_from_dispatcher(
+        implementation, module=None, verify=True, docs_from_dispatcher=True):
+    """Like array_function_dispatcher, but with function arguments flipped."""
+
+    def decorator(dispatcher):
+        return array_function_dispatch(
+            dispatcher, module, verify=verify,
+            docs_from_dispatcher=docs_from_dispatcher)(implementation)
+    return decorator

v12x/pylib/numpy/_core/printoptions.py

@@ -0,0 +1,32 @@
+"""
+Stores and defines the low-level format_options context variable.
+
+This is defined in its own file outside of the arrayprint module
+so we can import it from C while initializing the multiarray
+C module during import without introducing circular dependencies.
+"""
+
+import sys
+from contextvars import ContextVar
+
+__all__ = ["format_options"]
+
+default_format_options_dict = {
+    "edgeitems": 3,  # repr N leading and trailing items of each dimension
+    "threshold": 1000,  # total items > triggers array summarization
+    "floatmode": "maxprec",
+    "precision": 8,  # precision of floating point representations
+    "suppress": False,  # suppress printing small floating values in exp format
+    "linewidth": 75,
+    "nanstr": "nan",
+    "infstr": "inf",
+    "sign": "-",
+    "formatter": None,
+    # Internally stored as an int to simplify comparisons; converted from/to
+    # str/False on the way in/out.
+    'legacy': sys.maxsize,
+    'override_repr': None,
+}
+
+format_options = ContextVar(
+    "format_options", default=default_format_options_dict)

v12x/pylib/numpy/_core/records.py

@@ -0,0 +1,1101 @@
+"""
+This module contains a set of functions for record arrays.
+"""
+import os
+import warnings
+from collections import Counter
+from contextlib import nullcontext
+
+from numpy._utils import set_module
+
+from . import numeric as sb, numerictypes as nt
+from .arrayprint import _get_legacy_print_mode
+
+# All of the functions allow formats to be a dtype
+__all__ = [
+    'record', 'recarray', 'format_parser', 'fromarrays', 'fromrecords',
+    'fromstring', 'fromfile', 'array', 'find_duplicate',
+]
+
+
+ndarray = sb.ndarray
+
+_byteorderconv = {'b': '>',
+                  'l': '<',
+                  'n': '=',
+                  'B': '>',
+                  'L': '<',
+                  'N': '=',
+                  'S': 's',
+                  's': 's',
+                  '>': '>',
+                  '<': '<',
+                  '=': '=',
+                  '|': '|',
+                  'I': '|',
+                  'i': '|'}
+
+# formats regular expression
+# allows multidimensional spec with a tuple syntax in front
+# of the letter code '(2,3)f4' and ' (  2 ,  3  )  f4  '
+# are equally allowed
+
+numfmt = nt.sctypeDict
+
+
+@set_module('numpy.rec')
+def find_duplicate(list):
+    """Find duplication in a list, return a list of duplicated elements"""
+    return [
+        item
+        for item, counts in Counter(list).items()
+        if counts > 1
+    ]
+
+
+@set_module('numpy.rec')
+class format_parser:
+    """
+    Class to convert formats, names, titles description to a dtype.
+
+    After constructing the format_parser object, the dtype attribute is
+    the converted data-type:
+    ``dtype = format_parser(formats, names, titles).dtype``
+
+    Attributes
+    ----------
+    dtype : dtype
+        The converted data-type.
+
+    Parameters
+    ----------
+    formats : str or list of str
+        The format description, either specified as a string with
+        comma-separated format descriptions in the form ``'f8, i4, S5'``, or
+        a list of format description strings  in the form
+        ``['f8', 'i4', 'S5']``.
+    names : str or list/tuple of str
+        The field names, either specified as a comma-separated string in the
+        form ``'col1, col2, col3'``, or as a list or tuple of strings in the
+        form ``['col1', 'col2', 'col3']``.
+        An empty list can be used, in that case default field names
+        ('f0', 'f1', ...) are used.
+    titles : sequence
+        Sequence of title strings. An empty list can be used to leave titles
+        out.
+    aligned : bool, optional
+        If True, align the fields by padding as the C-compiler would.
+        Default is False.
+    byteorder : str, optional
+        If specified, all the fields will be changed to the
+        provided byte-order.  Otherwise, the default byte-order is
+        used. For all available string specifiers, see `dtype.newbyteorder`.
+
+    See Also
+    --------
+    numpy.dtype, numpy.typename
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.rec.format_parser(['<f8', '<i4'], ['col1', 'col2'],
+    ...                      ['T1', 'T2']).dtype
+    dtype([(('T1', 'col1'), '<f8'), (('T2', 'col2'), '<i4')])
+
+    `names` and/or `titles` can be empty lists. If `titles` is an empty list,
+    titles will simply not appear. If `names` is empty, default field names
+    will be used.
+
+    >>> np.rec.format_parser(['f8', 'i4', 'S5'], ['col1', 'col2', 'col3'],
+    ...                      []).dtype
+    dtype([('col1', '<f8'), ('col2', '<i4'), ('col3', '<S5')])
+    >>> np.rec.format_parser(['<f8', '<i4', '<S5'], [], []).dtype
+    dtype([('f0', '<f8'), ('f1', '<i4'), ('f2', 'S5')])
+
+    """
+
+    def __init__(self, formats, names, titles, aligned=False, byteorder=None):
+        self._parseFormats(formats, aligned)
+        self._setfieldnames(names, titles)
+        self._createdtype(byteorder)
+
+    def _parseFormats(self, formats, aligned=False):
+        """ Parse the field formats """
+
+        if formats is None:
+            raise ValueError("Need formats argument")
+        if isinstance(formats, list):
+            dtype = sb.dtype(
+                [
+                    (f'f{i}', format_)
+                    for i, format_ in enumerate(formats)
+                ],
+                aligned,
+            )
+        else:
+            dtype = sb.dtype(formats, aligned)
+        fields = dtype.fields
+        if fields is None:
+            dtype = sb.dtype([('f1', dtype)], aligned)
+            fields = dtype.fields
+        keys = dtype.names
+        self._f_formats = [fields[key][0] for key in keys]
+        self._offsets = [fields[key][1] for key in keys]
+        self._nfields = len(keys)
+
+    def _setfieldnames(self, names, titles):
+        """convert input field names into a list and assign to the _names
+        attribute """
+
+        if names:
+            if type(names) in [list, tuple]:
+                pass
+            elif isinstance(names, str):
+                names = names.split(',')
+            else:
+                raise NameError(f"illegal input names {repr(names)}")
+
+            self._names = [n.strip() for n in names[:self._nfields]]
+        else:
+            self._names = []
+
+        # if the names are not specified, they will be assigned as
+        #  "f0, f1, f2,..."
+        # if not enough names are specified, they will be assigned as "f[n],
+        # f[n+1],..." etc. where n is the number of specified names..."
+        self._names += [f'f{i}' for i in range(len(self._names),
+                                                 self._nfields)]
+        # check for redundant names
+        _dup = find_duplicate(self._names)
+        if _dup:
+            raise ValueError(f"Duplicate field names: {_dup}")
+
+        if titles:
+            self._titles = [n.strip() for n in titles[:self._nfields]]
+        else:
+            self._titles = []
+            titles = []
+
+        if self._nfields > len(titles):
+            self._titles += [None] * (self._nfields - len(titles))
+
+    def _createdtype(self, byteorder):
+        dtype = sb.dtype({
+            'names': self._names,
+            'formats': self._f_formats,
+            'offsets': self._offsets,
+            'titles': self._titles,
+        })
+        if byteorder is not None:
+            byteorder = _byteorderconv[byteorder[0]]
+            dtype = dtype.newbyteorder(byteorder)
+
+        self.dtype = dtype
+
+
+class record(nt.void):
+    """A data-type scalar that allows field access as attribute lookup.
+    """
+
+    # manually set name and module so that this class's type shows up
+    # as numpy.record when printed
+    __name__ = 'record'
+    __module__ = 'numpy'
+
+    def __repr__(self):
+        if _get_legacy_print_mode() <= 113:
+            return self.__str__()
+        return super().__repr__()
+
+    def __str__(self):
+        if _get_legacy_print_mode() <= 113:
+            return str(self.item())
+        return super().__str__()
+
+    def __getattribute__(self, attr):
+        if attr in ('setfield', 'getfield', 'dtype'):
+            return nt.void.__getattribute__(self, attr)
+        try:
+            return nt.void.__getattribute__(self, attr)
+        except AttributeError:
+            pass
+        fielddict = nt.void.__getattribute__(self, 'dtype').fields
+        res = fielddict.get(attr, None)
+        if res:
+            obj = self.getfield(*res[:2])
+            # if it has fields return a record,
+            # otherwise return the object
+            try:
+                dt = obj.dtype
+            except AttributeError:
+                # happens if field is Object type
+                return obj
+            if dt.names is not None:
+                return obj.view((self.__class__, obj.dtype))
+            return obj
+        else:
+            raise AttributeError(f"'record' object has no attribute '{attr}'")
+
+    def __setattr__(self, attr, val):
+        if attr in ('setfield', 'getfield', 'dtype'):
+            raise AttributeError(f"Cannot set '{attr}' attribute")
+        fielddict = nt.void.__getattribute__(self, 'dtype').fields
+        res = fielddict.get(attr, None)
+        if res:
+            return self.setfield(val, *res[:2])
+        elif getattr(self, attr, None):
+            return nt.void.__setattr__(self, attr, val)
+        else:
+            raise AttributeError(f"'record' object has no attribute '{attr}'")
+
+    def __getitem__(self, indx):
+        obj = nt.void.__getitem__(self, indx)
+
+        # copy behavior of record.__getattribute__,
+        if isinstance(obj, nt.void) and obj.dtype.names is not None:
+            return obj.view((self.__class__, obj.dtype))
+        else:
+            # return a single element
+            return obj
+
+    def pprint(self):
+        """Pretty-print all fields."""
+        # pretty-print all fields
+        names = self.dtype.names
+        maxlen = max(len(name) for name in names)
+        rows = [f"{name:>{maxlen}}: {getattr(self, name)}" for name in names]
+        return "\n".join(rows)
+
+# The recarray is almost identical to a standard array (which supports
+#   named fields already)  The biggest difference is that it can use
+#   attribute-lookup to find the fields and it is constructed using
+#   a record.
+
+# If byteorder is given it forces a particular byteorder on all
+#  the fields (and any subfields)
+
+
+@set_module("numpy.rec")
+class recarray(ndarray):
+    """Construct an ndarray that allows field access using attributes.
+
+    Arrays may have a data-types containing fields, analogous
+    to columns in a spread sheet.  An example is ``[(x, int), (y, float)]``,
+    where each entry in the array is a pair of ``(int, float)``.  Normally,
+    these attributes are accessed using dictionary lookups such as ``arr['x']``
+    and ``arr['y']``.  Record arrays allow the fields to be accessed as members
+    of the array, using ``arr.x`` and ``arr.y``.
+
+    Parameters
+    ----------
+    shape : tuple
+        Shape of output array.
+    dtype : data-type, optional
+        The desired data-type.  By default, the data-type is determined
+        from `formats`, `names`, `titles`, `aligned` and `byteorder`.
+    formats : list of data-types, optional
+        A list containing the data-types for the different columns, e.g.
+        ``['i4', 'f8', 'i4']``.  `formats` does *not* support the new
+        convention of using types directly, i.e. ``(int, float, int)``.
+        Note that `formats` must be a list, not a tuple.
+        Given that `formats` is somewhat limited, we recommend specifying
+        `dtype` instead.
+    names : tuple of str, optional
+        The name of each column, e.g. ``('x', 'y', 'z')``.
+    buf : buffer, optional
+        By default, a new array is created of the given shape and data-type.
+        If `buf` is specified and is an object exposing the buffer interface,
+        the array will use the memory from the existing buffer.  In this case,
+        the `offset` and `strides` keywords are available.
+
+    Other Parameters
+    ----------------
+    titles : tuple of str, optional
+        Aliases for column names.  For example, if `names` were
+        ``('x', 'y', 'z')`` and `titles` is
+        ``('x_coordinate', 'y_coordinate', 'z_coordinate')``, then
+        ``arr['x']`` is equivalent to both ``arr.x`` and ``arr.x_coordinate``.
+    byteorder : {'<', '>', '='}, optional
+        Byte-order for all fields.
+    aligned : bool, optional
+        Align the fields in memory as the C-compiler would.
+    strides : tuple of ints, optional
+        Buffer (`buf`) is interpreted according to these strides (strides
+        define how many bytes each array element, row, column, etc.
+        occupy in memory).
+    offset : int, optional
+        Start reading buffer (`buf`) from this offset onwards.
+    order : {'C', 'F'}, optional
+        Row-major (C-style) or column-major (Fortran-style) order.
+
+    Returns
+    -------
+    rec : recarray
+        Empty array of the given shape and type.
+
+    See Also
+    --------
+    numpy.rec.fromrecords : Construct a record array from data.
+    numpy.record : fundamental data-type for `recarray`.
+    numpy.rec.format_parser : determine data-type from formats, names, titles.
+
+    Notes
+    -----
+    This constructor can be compared to ``empty``: it creates a new record
+    array but does not fill it with data.  To create a record array from data,
+    use one of the following methods:
+
+    1. Create a standard ndarray and convert it to a record array,
+       using ``arr.view(np.recarray)``
+    2. Use the `buf` keyword.
+    3. Use `np.rec.fromrecords`.
+
+    Examples
+    --------
+    Create an array with two fields, ``x`` and ``y``:
+
+    >>> import numpy as np
+    >>> x = np.array([(1.0, 2), (3.0, 4)], dtype=[('x', '<f8'), ('y', '<i8')])
+    >>> x
+    array([(1., 2), (3., 4)], dtype=[('x', '<f8'), ('y', '<i8')])
+
+    >>> x['x']
+    array([1., 3.])
+
+    View the array as a record array:
+
+    >>> x = x.view(np.recarray)
+
+    >>> x.x
+    array([1., 3.])
+
+    >>> x.y
+    array([2, 4])
+
+    Create a new, empty record array:
+
+    >>> np.recarray((2,),
+    ... dtype=[('x', int), ('y', float), ('z', int)]) #doctest: +SKIP
+    rec.array([(-1073741821, 1.2249118382103472e-301, 24547520),
+           (3471280, 1.2134086255804012e-316, 0)],
+          dtype=[('x', '<i4'), ('y', '<f8'), ('z', '<i4')])
+
+    """
+
+    def __new__(cls, shape, dtype=None, buf=None, offset=0, strides=None,
+                formats=None, names=None, titles=None,
+                byteorder=None, aligned=False, order='C'):
+
+        if dtype is not None:
+            descr = sb.dtype(dtype)
+        else:
+            descr = format_parser(
+                formats, names, titles, aligned, byteorder
+            ).dtype
+
+        if buf is None:
+            self = ndarray.__new__(cls, shape, (record, descr), order=order)
+        else:
+            self = ndarray.__new__(
+                cls, shape, (record, descr), buffer=buf,
+                offset=offset, strides=strides, order=order
+            )
+        return self
+
+    _set_dtype = None  # __array_finalize__ can deal with dtype changes
+
+    def __array_finalize__(self, obj):
+        if (self.dtype.type is not record and
+                issubclass(self.dtype.type, nt.void) and
+                self.dtype.names is not None):
+            # if self.dtype is not np.record, invoke __setattr__ which will
+            # convert it to a record if it is a void dtype.
+            ndarray._set_dtype(self, sb.dtype((record, self.dtype)))
+
+    def __getattribute__(self, attr):
+        # See if ndarray has this attr, and return it if so. (note that this
+        # means a field with the same name as an ndarray attr cannot be
+        # accessed by attribute).
+        try:
+            return object.__getattribute__(self, attr)
+        except AttributeError:  # attr must be a fieldname
+            pass
+
+        # look for a field with this name
+        fielddict = ndarray.__getattribute__(self, 'dtype').fields
+        try:
+            res = fielddict[attr][:2]
+        except (TypeError, KeyError) as e:
+            raise AttributeError(f"recarray has no attribute {attr}") from e
+        obj = self.getfield(*res)
+
+        # At this point obj will always be a recarray, since (see
+        # PyArray_GetField) the type of obj is inherited. Next, if obj.dtype is
+        # non-structured, convert it to an ndarray. Then if obj is structured
+        # with void type convert it to the same dtype.type (eg to preserve
+        # numpy.record type if present), since nested structured fields do not
+        # inherit type. Don't do this for non-void structures though.
+        if obj.dtype.names is not None:
+            if issubclass(obj.dtype.type, nt.void):
+                return obj.view(dtype=(self.dtype.type, obj.dtype))
+            return obj
+        else:
+            return obj.view(ndarray)
+
+    # Save the dictionary.
+    # If the attr is a field name and not in the saved dictionary
+    # Undo any "setting" of the attribute and do a setfield
+    # Thus, you can't create attributes on-the-fly that are field names.
+    def __setattr__(self, attr, val):
+
+        # Automatically convert (void) structured types to records
+        # (but not non-void structures, subarrays, or non-structured voids)
+        if (
+            attr == 'dtype' and
+            issubclass(val.type, nt.void) and
+            val.names is not None
+        ):
+            val = sb.dtype((record, val))
+
+        newattr = attr not in self.__dict__
+        try:
+            ret = object.__setattr__(self, attr, val)
+        except Exception:
+            fielddict = ndarray.__getattribute__(self, 'dtype').fields or {}
+            if attr not in fielddict:
+                raise
+        else:
+            fielddict = ndarray.__getattribute__(self, 'dtype').fields or {}
+            if attr not in fielddict:
+                return ret
+            if newattr:
+                # We just added this one or this setattr worked on an
+                # internal attribute.
+                try:
+                    object.__delattr__(self, attr)
+                except Exception:
+                    return ret
+        try:
+            res = fielddict[attr][:2]
+        except (TypeError, KeyError) as e:
+            raise AttributeError(
+                f"record array has no attribute {attr}"
+            ) from e
+        return self.setfield(val, *res)
+
+    def __getitem__(self, indx):
+        obj = super().__getitem__(indx)
+
+        # copy behavior of getattr, except that here
+        # we might also be returning a single element
+        if isinstance(obj, ndarray):
+            if obj.dtype.names is not None:
+                obj = obj.view(type(self))
+                if issubclass(obj.dtype.type, nt.void):
+                    return obj.view(dtype=(self.dtype.type, obj.dtype))
+                return obj
+            else:
+                return obj.view(type=ndarray)
+        else:
+            # return a single element
+            return obj
+
+    def __repr__(self):
+
+        repr_dtype = self.dtype
+        if (
+            self.dtype.type is record or
+            not issubclass(self.dtype.type, nt.void)
+        ):
+            # If this is a full record array (has numpy.record dtype),
+            # or if it has a scalar (non-void) dtype with no records,
+            # represent it using the rec.array function. Since rec.array
+            # converts dtype to a numpy.record for us, convert back
+            # to non-record before printing
+            if repr_dtype.type is record:
+                repr_dtype = sb.dtype((nt.void, repr_dtype))
+            prefix = "rec.array("
+            fmt = 'rec.array(%s,%sdtype=%s)'
+        else:
+            # otherwise represent it using np.array plus a view
+            # This should only happen if the user is playing
+            # strange games with dtypes.
+            prefix = "array("
+            fmt = 'array(%s,%sdtype=%s).view(numpy.recarray)'
+
+        # get data/shape string. logic taken from numeric.array_repr
+        if self.size > 0 or self.shape == (0,):
+            lst = sb.array2string(
+                self, separator=', ', prefix=prefix, suffix=',')
+        else:
+            # show zero-length shape unless it is (0,)
+            lst = f"[], shape={repr(self.shape)}"
+
+        lf = '\n' + ' ' * len(prefix)
+        if _get_legacy_print_mode() <= 113:
+            lf = ' ' + lf  # trailing space
+        return fmt % (lst, lf, repr_dtype)
+
+    def field(self, attr, val=None):
+        if isinstance(attr, int):
+            names = ndarray.__getattribute__(self, 'dtype').names
+            attr = names[attr]
+
+        fielddict = ndarray.__getattribute__(self, 'dtype').fields
+
+        res = fielddict[attr][:2]
+
+        if val is None:
+            obj = self.getfield(*res)
+            if obj.dtype.names is not None:
+                return obj
+            return obj.view(ndarray)
+        else:
+            return self.setfield(val, *res)
+
+
+def _deprecate_shape_0_as_None(shape):
+    if shape == 0:
+        warnings.warn(
+            "Passing `shape=0` to have the shape be inferred is deprecated, "
+            "and in future will be equivalent to `shape=(0,)`. To infer "
+            "the shape and suppress this warning, pass `shape=None` instead.",
+            FutureWarning, stacklevel=3)
+        return None
+    else:
+        return shape
+
+
+@set_module("numpy.rec")
+def fromarrays(arrayList, dtype=None, shape=None, formats=None,
+               names=None, titles=None, aligned=False, byteorder=None):
+    """Create a record array from a (flat) list of arrays
+
+    Parameters
+    ----------
+    arrayList : list or tuple
+        List of array-like objects (such as lists, tuples,
+        and ndarrays).
+    dtype : data-type, optional
+        valid dtype for all arrays
+    shape : int or tuple of ints, optional
+        Shape of the resulting array. If not provided, inferred from
+        ``arrayList[0]``.
+    formats, names, titles, aligned, byteorder :
+        If `dtype` is ``None``, these arguments are passed to
+        `numpy.rec.format_parser` to construct a dtype. See that function for
+        detailed documentation.
+
+    Returns
+    -------
+    np.recarray
+        Record array consisting of given arrayList columns.
+
+    Examples
+    --------
+    >>> x1=np.array([1,2,3,4])
+    >>> x2=np.array(['a','dd','xyz','12'])
+    >>> x3=np.array([1.1,2,3,4])
+    >>> r = np.rec.fromarrays([x1,x2,x3],names='a,b,c')
+    >>> print(r[1])
+    (2, 'dd', 2.0) # may vary
+    >>> x1[1]=34
+    >>> r.a
+    array([1, 2, 3, 4])
+
+    >>> x1 = np.array([1, 2, 3, 4])
+    >>> x2 = np.array(['a', 'dd', 'xyz', '12'])
+    >>> x3 = np.array([1.1, 2, 3,4])
+    >>> r = np.rec.fromarrays(
+    ...     [x1, x2, x3],
+    ...     dtype=np.dtype([('a', np.int32), ('b', 'S3'), ('c', np.float32)]))
+    >>> r
+    rec.array([(1, b'a', 1.1), (2, b'dd', 2. ), (3, b'xyz', 3. ),
+               (4, b'12', 4. )],
+              dtype=[('a', '<i4'), ('b', 'S3'), ('c', '<f4')])
+    """
+
+    arrayList = [sb.asarray(x) for x in arrayList]
+
+    # NumPy 1.19.0, 2020-01-01
+    shape = _deprecate_shape_0_as_None(shape)
+
+    if shape is None:
+        shape = arrayList[0].shape
+    elif isinstance(shape, int):
+        shape = (shape,)
+
+    if formats is None and dtype is None:
+        # go through each object in the list to see if it is an ndarray
+        # and determine the formats.
+        formats = [obj.dtype for obj in arrayList]
+
+    if dtype is not None:
+        descr = sb.dtype(dtype)
+    else:
+        descr = format_parser(formats, names, titles, aligned, byteorder).dtype
+    _names = descr.names
+
+    # Determine shape from data-type.
+    if len(descr) != len(arrayList):
+        raise ValueError("mismatch between the number of fields "
+                "and the number of arrays")
+
+    d0 = descr[0].shape
+    nn = len(d0)
+    if nn > 0:
+        shape = shape[:-nn]
+
+    _array = recarray(shape, descr)
+
+    # populate the record array (makes a copy)
+    for k, obj in enumerate(arrayList):
+        nn = descr[k].ndim
+        testshape = obj.shape[:obj.ndim - nn]
+        name = _names[k]
+        if testshape != shape:
+            raise ValueError(f'array-shape mismatch in array {k} ("{name}")')
+
+        _array[name] = obj
+
+    return _array
+
+
+@set_module("numpy.rec")
+def fromrecords(recList, dtype=None, shape=None, formats=None, names=None,
+                titles=None, aligned=False, byteorder=None):
+    """Create a recarray from a list of records in text form.
+
+    Parameters
+    ----------
+    recList : sequence
+        data in the same field may be heterogeneous - they will be promoted
+        to the highest data type.
+    dtype : data-type, optional
+        valid dtype for all arrays
+    shape : int or tuple of ints, optional
+        shape of each array.
+    formats, names, titles, aligned, byteorder :
+        If `dtype` is ``None``, these arguments are passed to
+        `numpy.format_parser` to construct a dtype. See that function for
+        detailed documentation.
+
+        If both `formats` and `dtype` are None, then this will auto-detect
+        formats. Use list of tuples rather than list of lists for faster
+        processing.
+
+    Returns
+    -------
+    np.recarray
+        record array consisting of given recList rows.
+
+    Examples
+    --------
+    >>> r=np.rec.fromrecords([(456,'dbe',1.2),(2,'de',1.3)],
+    ... names='col1,col2,col3')
+    >>> print(r[0])
+    (456, 'dbe', 1.2)
+    >>> r.col1
+    array([456,   2])
+    >>> r.col2
+    array(['dbe', 'de'], dtype='<U3')
+    >>> import pickle
+    >>> pickle.loads(pickle.dumps(r))
+    rec.array([(456, 'dbe', 1.2), (  2, 'de', 1.3)],
+              dtype=[('col1', '<i8'), ('col2', '<U3'), ('col3', '<f8')])
+    """
+
+    if formats is None and dtype is None:  # slower
+        obj = sb.array(recList, dtype=object)
+        arrlist = [
+            sb.array(obj[..., i].tolist()) for i in range(obj.shape[-1])
+        ]
+        return fromarrays(arrlist, formats=formats, shape=shape, names=names,
+                          titles=titles, aligned=aligned, byteorder=byteorder)
+
+    if dtype is not None:
+        descr = sb.dtype((record, dtype))
+    else:
+        descr = format_parser(
+            formats, names, titles, aligned, byteorder
+        ).dtype
+
+    try:
+        retval = sb.array(recList, dtype=descr)
+    except (TypeError, ValueError):
+        # NumPy 1.19.0, 2020-01-01
+        shape = _deprecate_shape_0_as_None(shape)
+        if shape is None:
+            shape = len(recList)
+        if isinstance(shape, int):
+            shape = (shape,)
+        if len(shape) > 1:
+            raise ValueError("Can only deal with 1-d array.")
+        _array = recarray(shape, descr)
+        for k in range(_array.size):
+            _array[k] = tuple(recList[k])
+        # list of lists instead of list of tuples ?
+        # 2018-02-07, 1.14.1
+        warnings.warn(
+            "fromrecords expected a list of tuples, may have received a list "
+            "of lists instead. In the future that will raise an error",
+            FutureWarning, stacklevel=2)
+        return _array
+    else:
+        if shape is not None and retval.shape != shape:
+            retval = retval.reshape(shape)
+
+    res = retval.view(recarray)
+
+    return res
+
+
+@set_module("numpy.rec")
+def fromstring(datastring, dtype=None, shape=None, offset=0, formats=None,
+               names=None, titles=None, aligned=False, byteorder=None):
+    r"""Create a record array from binary data
+
+    Note that despite the name of this function it does not accept `str`
+    instances.
+
+    Parameters
+    ----------
+    datastring : bytes-like
+        Buffer of binary data
+    dtype : data-type, optional
+        Valid dtype for all arrays
+    shape : int or tuple of ints, optional
+        Shape of each array.
+    offset : int, optional
+        Position in the buffer to start reading from.
+    formats, names, titles, aligned, byteorder :
+        If `dtype` is ``None``, these arguments are passed to
+        `numpy.format_parser` to construct a dtype. See that function for
+        detailed documentation.
+
+
+    Returns
+    -------
+    np.recarray
+        Record array view into the data in datastring. This will be readonly
+        if `datastring` is readonly.
+
+    See Also
+    --------
+    numpy.frombuffer
+
+    Examples
+    --------
+    >>> a = b'\x01\x02\x03abc'
+    >>> np.rec.fromstring(a, dtype='u1,u1,u1,S3')
+    rec.array([(1, 2, 3, b'abc')],
+            dtype=[('f0', 'u1'), ('f1', 'u1'), ('f2', 'u1'), ('f3', 'S3')])
+
+    >>> grades_dtype = [('Name', (np.str_, 10)), ('Marks', np.float64),
+    ...                 ('GradeLevel', np.int32)]
+    >>> grades_array = np.array([('Sam', 33.3, 3), ('Mike', 44.4, 5),
+    ...                         ('Aadi', 66.6, 6)], dtype=grades_dtype)
+    >>> np.rec.fromstring(grades_array.tobytes(), dtype=grades_dtype)
+    rec.array([('Sam', 33.3, 3), ('Mike', 44.4, 5), ('Aadi', 66.6, 6)],
+            dtype=[('Name', '<U10'), ('Marks', '<f8'), ('GradeLevel', '<i4')])
+
+    >>> s = '\x01\x02\x03abc'
+    >>> np.rec.fromstring(s, dtype='u1,u1,u1,S3')
+    Traceback (most recent call last):
+       ...
+    TypeError: a bytes-like object is required, not 'str'
+    """
+
+    if dtype is None and formats is None:
+        raise TypeError("fromstring() needs a 'dtype' or 'formats' argument")
+
+    if dtype is not None:
+        descr = sb.dtype(dtype)
+    else:
+        descr = format_parser(formats, names, titles, aligned, byteorder).dtype
+
+    if descr.hasobject:
+        raise ValueError(
+            f"Cannot create record array for dtype {descr}. "
+             "Arrays containing references are not supported."
+        )
+
+    itemsize = descr.itemsize
+
+    # NumPy 1.19.0, 2020-01-01
+    shape = _deprecate_shape_0_as_None(shape)
+
+    if shape in (None, -1):
+        shape = (len(datastring) - offset) // itemsize
+
+    _array = recarray(shape, descr, buf=datastring, offset=offset)
+    return _array
+
+def get_remaining_size(fd):
+    pos = fd.tell()
+    try:
+        fd.seek(0, 2)
+        return fd.tell() - pos
+    finally:
+        fd.seek(pos, 0)
+
+
+@set_module("numpy.rec")
+def fromfile(fd, dtype=None, shape=None, offset=0, formats=None,
+             names=None, titles=None, aligned=False, byteorder=None):
+    """Create an array from binary file data
+
+    Parameters
+    ----------
+    fd : str or file type
+        If file is a string or a path-like object then that file is opened,
+        else it is assumed to be a file object. The file object must
+        support random access (i.e. it must have tell and seek methods).
+    dtype : data-type, optional
+        valid dtype for all arrays
+    shape : int or tuple of ints, optional
+        shape of each array.
+    offset : int, optional
+        Position in the file to start reading from.
+    formats, names, titles, aligned, byteorder :
+        If `dtype` is ``None``, these arguments are passed to
+        `numpy.format_parser` to construct a dtype. See that function for
+        detailed documentation
+
+    Returns
+    -------
+    np.recarray
+        record array consisting of data enclosed in file.
+
+    Examples
+    --------
+    >>> from tempfile import TemporaryFile
+    >>> a = np.empty(10,dtype='f8,i4,S5')
+    >>> a[5] = (0.5,10,'abcde')
+    >>>
+    >>> fd=TemporaryFile()
+    >>> a = a.view(a.dtype.newbyteorder('<'))
+    >>> a.tofile(fd)
+    >>>
+    >>> _ = fd.seek(0)
+    >>> r=np.rec.fromfile(fd, formats='f8,i4,S5', shape=10,
+    ... byteorder='<')
+    >>> print(r[5])
+    (0.5, 10, b'abcde')
+    >>> r.shape
+    (10,)
+    """
+
+    if dtype is None and formats is None:
+        raise TypeError("fromfile() needs a 'dtype' or 'formats' argument")
+
+    # NumPy 1.19.0, 2020-01-01
+    shape = _deprecate_shape_0_as_None(shape)
+
+    if shape is None:
+        shape = (-1,)
+    elif isinstance(shape, int):
+        shape = (shape,)
+
+    if hasattr(fd, 'readinto'):
+        # GH issue 2504. fd supports io.RawIOBase or io.BufferedIOBase
+        # interface. Example of fd: gzip, BytesIO, BufferedReader
+        # file already opened
+        ctx = nullcontext(fd)
+    else:
+        # open file
+        ctx = open(os.fspath(fd), 'rb')
+
+    with ctx as fd:
+        if offset > 0:
+            fd.seek(offset, 1)
+        size = get_remaining_size(fd)
+
+        if dtype is not None:
+            descr = sb.dtype(dtype)
+        else:
+            descr = format_parser(
+                formats, names, titles, aligned, byteorder
+            ).dtype
+
+        if descr.hasobject:
+            raise ValueError(
+                f"Cannot create record array for dtype {descr}. "
+                "Arrays containing references are not supported."
+            )
+
+        itemsize = descr.itemsize
+
+        shapeprod = sb.array(shape).prod(dtype=nt.intp)
+        shapesize = shapeprod * itemsize
+        if shapesize < 0:
+            shape = list(shape)
+            shape[shape.index(-1)] = size // -shapesize
+            shape = tuple(shape)
+            shapeprod = sb.array(shape).prod(dtype=nt.intp)
+
+        nbytes = shapeprod * itemsize
+
+        if nbytes > size:
+            raise ValueError(
+                    "Not enough bytes left in file for specified "
+                    "shape and type."
+                )
+
+        # create the array
+        _array = recarray(shape, descr)
+        nbytesread = fd.readinto(_array.data)
+        if nbytesread != nbytes:
+            raise OSError("Didn't read as many bytes as expected")
+
+    return _array
+
+
+@set_module("numpy.rec")
+def array(obj, dtype=None, shape=None, offset=0, strides=None, formats=None,
+          names=None, titles=None, aligned=False, byteorder=None, copy=True):
+    """
+    Construct a record array from a wide-variety of objects.
+
+    A general-purpose record array constructor that dispatches to the
+    appropriate `recarray` creation function based on the inputs (see Notes).
+
+    Parameters
+    ----------
+    obj : any
+        Input object. See Notes for details on how various input types are
+        treated.
+    dtype : data-type, optional
+        Valid dtype for array.
+    shape : int or tuple of ints, optional
+        Shape of each array.
+    offset : int, optional
+        Position in the file or buffer to start reading from.
+    strides : tuple of ints, optional
+        Buffer (`buf`) is interpreted according to these strides (strides
+        define how many bytes each array element, row, column, etc.
+        occupy in memory).
+    formats, names, titles, aligned, byteorder :
+        If `dtype` is ``None``, these arguments are passed to
+        `numpy.format_parser` to construct a dtype. See that function for
+        detailed documentation.
+    copy : bool, optional
+        Whether to copy the input object (True), or to use a reference instead.
+        This option only applies when the input is an ndarray or recarray.
+        Defaults to True.
+
+    Returns
+    -------
+    np.recarray
+        Record array created from the specified object.
+
+    Notes
+    -----
+    If `obj` is ``None``, then call the `~numpy.recarray` constructor. If
+    `obj` is a string, then call the `fromstring` constructor. If `obj` is a
+    list or a tuple, then if the first object is an `~numpy.ndarray`, call
+    `fromarrays`, otherwise call `fromrecords`. If `obj` is a
+    `~numpy.recarray`, then make a copy of the data in the recarray
+    (if ``copy=True``) and use the new formats, names, and titles. If `obj`
+    is a file, then call `fromfile`. Finally, if obj is an `ndarray`, then
+    return ``obj.view(recarray)``, making a copy of the data if ``copy=True``.
+
+    Examples
+    --------
+    >>> a = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    >>> a
+    array([[1, 2, 3],
+           [4, 5, 6],
+           [7, 8, 9]])
+
+    >>> np.rec.array(a)
+    rec.array([[1, 2, 3],
+               [4, 5, 6],
+               [7, 8, 9]],
+              dtype=int64)
+
+    >>> b = [(1, 1), (2, 4), (3, 9)]
+    >>> c = np.rec.array(b, formats = ['i2', 'f2'], names = ('x', 'y'))
+    >>> c
+    rec.array([(1, 1.), (2, 4.), (3, 9.)],
+              dtype=[('x', '<i2'), ('y', '<f2')])
+
+    >>> c.x
+    array([1, 2, 3], dtype=int16)
+
+    >>> c.y
+    array([1.,  4.,  9.], dtype=float16)
+
+    >>> r = np.rec.array(['abc','def'], names=['col1','col2'])
+    >>> print(r.col1)
+    abc
+
+    >>> r.col1
+    array('abc', dtype='<U3')
+
+    >>> r.col2
+    array('def', dtype='<U3')
+    """
+
+    if ((isinstance(obj, (type(None), str)) or hasattr(obj, 'readinto')) and
+           formats is None and dtype is None):
+        raise ValueError("Must define formats (or dtype) if object is "
+                         "None, string, or an open file")
+
+    kwds = {}
+    if dtype is not None:
+        dtype = sb.dtype(dtype)
+    elif formats is not None:
+        dtype = format_parser(formats, names, titles,
+                              aligned, byteorder).dtype
+    else:
+        kwds = {'formats': formats,
+                'names': names,
+                'titles': titles,
+                'aligned': aligned,
+                'byteorder': byteorder
+                }
+
+    if obj is None:
+        if shape is None:
+            raise ValueError("Must define a shape if obj is None")
+        return recarray(shape, dtype, buf=obj, offset=offset, strides=strides)
+
+    elif isinstance(obj, bytes):
+        return fromstring(obj, dtype, shape=shape, offset=offset, **kwds)
+
+    elif isinstance(obj, (list, tuple)):
+        if isinstance(obj[0], (tuple, list)):
+            return fromrecords(obj, dtype=dtype, shape=shape, **kwds)
+        else:
+            return fromarrays(obj, dtype=dtype, shape=shape, **kwds)
+
+    elif isinstance(obj, recarray):
+        if dtype is not None and (obj.dtype != dtype):
+            new = obj.view(dtype)
+        else:
+            new = obj
+        if copy:
+            new = new.copy()
+        return new
+
+    elif hasattr(obj, 'readinto'):
+        return fromfile(obj, dtype=dtype, shape=shape, offset=offset)
+
+    elif isinstance(obj, ndarray):
+        if dtype is not None and (obj.dtype != dtype):
+            new = obj.view(dtype)
+        else:
+            new = obj
+        if copy:
+            new = new.copy()
+        return new.view(recarray)
+
+    else:
+        interface = getattr(obj, "__array_interface__", None)
+        if interface is None or not isinstance(interface, dict):
+            raise ValueError("Unknown input type")
+        obj = sb.array(obj)
+        if dtype is not None and (obj.dtype != dtype):
+            obj = obj.view(dtype)
+        return obj.view(recarray)

v12x/pylib/numpy/_core/shape_base.py

@@ -0,0 +1,996 @@
+__all__ = ['atleast_1d', 'atleast_2d', 'atleast_3d', 'block', 'hstack',
+           'stack', 'unstack', 'vstack']
+
+import functools
+import itertools
+import operator
+
+from . import fromnumeric as _from_nx, numeric as _nx, overrides
+from .multiarray import array, asanyarray, normalize_axis_index
+
+array_function_dispatch = functools.partial(
+    overrides.array_function_dispatch, module='numpy')
+
+
+def _atleast_1d_dispatcher(*arys):
+    return arys
+
+
+@array_function_dispatch(_atleast_1d_dispatcher)
+def atleast_1d(*arys):
+    """
+    Convert inputs to arrays with at least one dimension.
+
+    Scalar inputs are converted to 1-dimensional arrays, whilst
+    higher-dimensional inputs are preserved.
+
+    Parameters
+    ----------
+    arys1, arys2, ... : array_like
+        One or more input arrays.
+
+    Returns
+    -------
+    ret : ndarray
+        An array, or tuple of arrays, each with ``a.ndim >= 1``.
+        Copies are made only if necessary.
+
+    See Also
+    --------
+    atleast_2d, atleast_3d
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.atleast_1d(1.0)
+    array([1.])
+
+    >>> x = np.arange(9.0).reshape(3,3)
+    >>> np.atleast_1d(x)
+    array([[0., 1., 2.],
+           [3., 4., 5.],
+           [6., 7., 8.]])
+    >>> np.atleast_1d(x) is x
+    True
+
+    >>> np.atleast_1d(1, [3, 4])
+    (array([1]), array([3, 4]))
+
+    """
+    if len(arys) == 1:
+        result = asanyarray(arys[0])
+        if result.ndim == 0:
+            result = result.reshape(1)
+        return result
+    res = []
+    for ary in arys:
+        result = asanyarray(ary)
+        if result.ndim == 0:
+            result = result.reshape(1)
+        res.append(result)
+    return tuple(res)
+
+
+def _atleast_2d_dispatcher(*arys):
+    return arys
+
+
+@array_function_dispatch(_atleast_2d_dispatcher)
+def atleast_2d(*arys):
+    """
+    View inputs as arrays with at least two dimensions.
+
+    Parameters
+    ----------
+    arys1, arys2, ... : array_like
+        One or more array-like sequences.  Non-array inputs are converted
+        to arrays.  Arrays that already have two or more dimensions are
+        preserved.
+
+    Returns
+    -------
+    res, res2, ... : ndarray
+        An array, or tuple of arrays, each with ``a.ndim >= 2``.
+        Copies are avoided where possible, and views with two or more
+        dimensions are returned.
+
+    See Also
+    --------
+    atleast_1d, atleast_3d
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.atleast_2d(3.0)
+    array([[3.]])
+
+    >>> x = np.arange(3.0)
+    >>> np.atleast_2d(x)
+    array([[0., 1., 2.]])
+    >>> np.atleast_2d(x).base is x
+    True
+
+    >>> np.atleast_2d(1, [1, 2], [[1, 2]])
+    (array([[1]]), array([[1, 2]]), array([[1, 2]]))
+
+    """
+    res = []
+    for ary in arys:
+        ary = asanyarray(ary)
+        if ary.ndim == 0:
+            result = ary.reshape(1, 1)
+        elif ary.ndim == 1:
+            result = ary[_nx.newaxis, :]
+        else:
+            result = ary
+        res.append(result)
+    if len(res) == 1:
+        return res[0]
+    else:
+        return tuple(res)
+
+
+def _atleast_3d_dispatcher(*arys):
+    return arys
+
+
+@array_function_dispatch(_atleast_3d_dispatcher)
+def atleast_3d(*arys):
+    """
+    View inputs as arrays with at least three dimensions.
+
+    Parameters
+    ----------
+    arys1, arys2, ... : array_like
+        One or more array-like sequences.  Non-array inputs are converted to
+        arrays.  Arrays that already have three or more dimensions are
+        preserved.
+
+    Returns
+    -------
+    res1, res2, ... : ndarray
+        An array, or tuple of arrays, each with ``a.ndim >= 3``.  Copies are
+        avoided where possible, and views with three or more dimensions are
+        returned.  For example, a 1-D array of shape ``(N,)`` becomes a view
+        of shape ``(1, N, 1)``, and a 2-D array of shape ``(M, N)`` becomes a
+        view of shape ``(M, N, 1)``.
+
+    See Also
+    --------
+    atleast_1d, atleast_2d
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.atleast_3d(3.0)
+    array([[[3.]]])
+
+    >>> x = np.arange(3.0)
+    >>> np.atleast_3d(x).shape
+    (1, 3, 1)
+
+    >>> x = np.arange(12.0).reshape(4,3)
+    >>> np.atleast_3d(x).shape
+    (4, 3, 1)
+    >>> np.atleast_3d(x).base is x.base  # x is a reshape, so not base itself
+    True
+
+    >>> for arr in np.atleast_3d([1, 2], [[1, 2]], [[[1, 2]]]):
+    ...     print(arr, arr.shape) # doctest: +SKIP
+    ...
+    [[[1]
+      [2]]] (1, 2, 1)
+    [[[1]
+      [2]]] (1, 2, 1)
+    [[[1 2]]] (1, 1, 2)
+
+    """
+    res = []
+    for ary in arys:
+        ary = asanyarray(ary)
+        if ary.ndim == 0:
+            result = ary.reshape(1, 1, 1)
+        elif ary.ndim == 1:
+            result = ary[_nx.newaxis, :, _nx.newaxis]
+        elif ary.ndim == 2:
+            result = ary[:, :, _nx.newaxis]
+        else:
+            result = ary
+        res.append(result)
+    if len(res) == 1:
+        return res[0]
+    else:
+        return tuple(res)
+
+
+def _arrays_for_stack_dispatcher(arrays):
+    if not hasattr(arrays, "__getitem__"):
+        raise TypeError('arrays to stack must be passed as a "sequence" type '
+                        'such as list or tuple.')
+
+    return tuple(arrays)
+
+
+def _vhstack_dispatcher(tup, *, dtype=None, casting=None):
+    return _arrays_for_stack_dispatcher(tup)
+
+
+@array_function_dispatch(_vhstack_dispatcher)
+def vstack(tup, *, dtype=None, casting="same_kind"):
+    """
+    Stack arrays in sequence vertically (row wise).
+
+    This is equivalent to concatenation along the first axis after 1-D arrays
+    of shape `(N,)` have been reshaped to `(1,N)`. Rebuilds arrays divided by
+    `vsplit`.
+
+    This function makes most sense for arrays with up to 3 dimensions. For
+    instance, for pixel-data with a height (first axis), width (second axis),
+    and r/g/b channels (third axis). The functions `concatenate`, `stack` and
+    `block` provide more general stacking and concatenation operations.
+
+    Parameters
+    ----------
+    tup : sequence of ndarrays
+        The arrays must have the same shape along all but the first axis.
+        1-D arrays must have the same length. In the case of a single
+        array_like input, it will be treated as a sequence of arrays; i.e.,
+        each element along the zeroth axis is treated as a separate array.
+
+    dtype : str or dtype
+        If provided, the destination array will have this dtype. Cannot be
+        provided together with `out`.
+
+        .. versionadded:: 1.24
+
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+        Controls what kind of data casting may occur. Defaults to 'same_kind'.
+
+        .. versionadded:: 1.24
+
+    Returns
+    -------
+    stacked : ndarray
+        The array formed by stacking the given arrays, will be at least 2-D.
+
+    See Also
+    --------
+    concatenate : Join a sequence of arrays along an existing axis.
+    stack : Join a sequence of arrays along a new axis.
+    block : Assemble an nd-array from nested lists of blocks.
+    hstack : Stack arrays in sequence horizontally (column wise).
+    dstack : Stack arrays in sequence depth wise (along third axis).
+    column_stack : Stack 1-D arrays as columns into a 2-D array.
+    vsplit : Split an array into multiple sub-arrays vertically (row-wise).
+    unstack : Split an array into a tuple of sub-arrays along an axis.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array([1, 2, 3])
+    >>> b = np.array([4, 5, 6])
+    >>> np.vstack((a,b))
+    array([[1, 2, 3],
+           [4, 5, 6]])
+
+    >>> a = np.array([[1], [2], [3]])
+    >>> b = np.array([[4], [5], [6]])
+    >>> np.vstack((a,b))
+    array([[1],
+           [2],
+           [3],
+           [4],
+           [5],
+           [6]])
+
+    """
+    arrs = atleast_2d(*tup)
+    if not isinstance(arrs, tuple):
+        arrs = (arrs,)
+    return _nx.concatenate(arrs, 0, dtype=dtype, casting=casting)
+
+
+@array_function_dispatch(_vhstack_dispatcher)
+def hstack(tup, *, dtype=None, casting="same_kind"):
+    """
+    Stack arrays in sequence horizontally (column wise).
+
+    This is equivalent to concatenation along the second axis, except for 1-D
+    arrays where it concatenates along the first axis. Rebuilds arrays divided
+    by `hsplit`.
+
+    This function makes most sense for arrays with up to 3 dimensions. For
+    instance, for pixel-data with a height (first axis), width (second axis),
+    and r/g/b channels (third axis). The functions `concatenate`, `stack` and
+    `block` provide more general stacking and concatenation operations.
+
+    Parameters
+    ----------
+    tup : sequence of ndarrays
+        The arrays must have the same shape along all but the second axis,
+        except 1-D arrays which can be any length. In the case of a single
+        array_like input, it will be treated as a sequence of arrays; i.e.,
+        each element along the zeroth axis is treated as a separate array.
+
+    dtype : str or dtype
+        If provided, the destination array will have this dtype. Cannot be
+        provided together with `out`.
+
+        .. versionadded:: 1.24
+
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+        Controls what kind of data casting may occur. Defaults to 'same_kind'.
+
+        .. versionadded:: 1.24
+
+    Returns
+    -------
+    stacked : ndarray
+        The array formed by stacking the given arrays.
+
+    See Also
+    --------
+    concatenate : Join a sequence of arrays along an existing axis.
+    stack : Join a sequence of arrays along a new axis.
+    block : Assemble an nd-array from nested lists of blocks.
+    vstack : Stack arrays in sequence vertically (row wise).
+    dstack : Stack arrays in sequence depth wise (along third axis).
+    column_stack : Stack 1-D arrays as columns into a 2-D array.
+    hsplit : Split an array into multiple sub-arrays
+             horizontally (column-wise).
+    unstack : Split an array into a tuple of sub-arrays along an axis.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array((1,2,3))
+    >>> b = np.array((4,5,6))
+    >>> np.hstack((a,b))
+    array([1, 2, 3, 4, 5, 6])
+    >>> a = np.array([[1],[2],[3]])
+    >>> b = np.array([[4],[5],[6]])
+    >>> np.hstack((a,b))
+    array([[1, 4],
+           [2, 5],
+           [3, 6]])
+
+    """
+    arrs = atleast_1d(*tup)
+    if not isinstance(arrs, tuple):
+        arrs = (arrs,)
+    # As a special case, dimension 0 of 1-dimensional arrays is "horizontal"
+    if arrs and arrs[0].ndim == 1:
+        return _nx.concatenate(arrs, 0, dtype=dtype, casting=casting)
+    else:
+        return _nx.concatenate(arrs, 1, dtype=dtype, casting=casting)
+
+
+def _stack_dispatcher(arrays, axis=None, out=None, *,
+                      dtype=None, casting=None):
+    arrays = _arrays_for_stack_dispatcher(arrays)
+    if out is not None:
+        # optimize for the typical case where only arrays is provided
+        arrays = list(arrays)
+        arrays.append(out)
+    return arrays
+
+
+@array_function_dispatch(_stack_dispatcher)
+def stack(arrays, axis=0, out=None, *, dtype=None, casting="same_kind"):
+    """
+    Join a sequence of arrays along a new axis.
+
+    The ``axis`` parameter specifies the index of the new axis in the
+    dimensions of the result. For example, if ``axis=0`` it will be the first
+    dimension and if ``axis=-1`` it will be the last dimension.
+
+    Parameters
+    ----------
+    arrays : sequence of ndarrays
+        Each array must have the same shape. In the case of a single ndarray
+        array_like input, it will be treated as a sequence of arrays; i.e.,
+        each element along the zeroth axis is treated as a separate array.
+
+    axis : int, optional
+        The axis in the result array along which the input arrays are stacked.
+
+    out : ndarray, optional
+        If provided, the destination to place the result. The shape must be
+        correct, matching that of what stack would have returned if no
+        out argument were specified.
+
+    dtype : str or dtype
+        If provided, the destination array will have this dtype. Cannot be
+        provided together with `out`.
+
+        .. versionadded:: 1.24
+
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+        Controls what kind of data casting may occur. Defaults to 'same_kind'.
+
+        .. versionadded:: 1.24
+
+
+    Returns
+    -------
+    stacked : ndarray
+        The stacked array has one more dimension than the input arrays.
+
+    See Also
+    --------
+    concatenate : Join a sequence of arrays along an existing axis.
+    block : Assemble an nd-array from nested lists of blocks.
+    split : Split array into a list of multiple sub-arrays of equal size.
+    unstack : Split an array into a tuple of sub-arrays along an axis.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> rng = np.random.default_rng()
+    >>> arrays = [rng.normal(size=(3,4)) for _ in range(10)]
+    >>> np.stack(arrays, axis=0).shape
+    (10, 3, 4)
+
+    >>> np.stack(arrays, axis=1).shape
+    (3, 10, 4)
+
+    >>> np.stack(arrays, axis=2).shape
+    (3, 4, 10)
+
+    >>> a = np.array([1, 2, 3])
+    >>> b = np.array([4, 5, 6])
+    >>> np.stack((a, b))
+    array([[1, 2, 3],
+           [4, 5, 6]])
+
+    >>> np.stack((a, b), axis=-1)
+    array([[1, 4],
+           [2, 5],
+           [3, 6]])
+
+    """
+    arrays = [asanyarray(arr) for arr in arrays]
+    if not arrays:
+        raise ValueError('need at least one array to stack')
+
+    shapes = {arr.shape for arr in arrays}
+    if len(shapes) != 1:
+        raise ValueError('all input arrays must have the same shape')
+
+    result_ndim = arrays[0].ndim + 1
+    axis = normalize_axis_index(axis, result_ndim)
+
+    sl = (slice(None),) * axis + (_nx.newaxis,)
+    expanded_arrays = [arr[sl] for arr in arrays]
+    return _nx.concatenate(expanded_arrays, axis=axis, out=out,
+                           dtype=dtype, casting=casting)
+
+def _unstack_dispatcher(x, /, *, axis=None):
+    return (x,)
+
+@array_function_dispatch(_unstack_dispatcher)
+def unstack(x, /, *, axis=0):
+    """
+    Split an array into a sequence of arrays along the given axis.
+
+    The ``axis`` parameter specifies the dimension along which the array will
+    be split. For example, if ``axis=0`` (the default) it will be the first
+    dimension and if ``axis=-1`` it will be the last dimension.
+
+    The result is a tuple of arrays split along ``axis``.
+
+    .. versionadded:: 2.1.0
+
+    Parameters
+    ----------
+    x : ndarray
+        The array to be unstacked.
+    axis : int, optional
+        Axis along which the array will be split. Default: ``0``.
+
+    Returns
+    -------
+    unstacked : tuple of ndarrays
+        The unstacked arrays.
+
+    See Also
+    --------
+    stack : Join a sequence of arrays along a new axis.
+    concatenate : Join a sequence of arrays along an existing axis.
+    block : Assemble an nd-array from nested lists of blocks.
+    split : Split array into a list of multiple sub-arrays of equal size.
+
+    Notes
+    -----
+    ``unstack`` serves as the reverse operation of :py:func:`stack`, i.e.,
+    ``stack(unstack(x, axis=axis), axis=axis) == x``.
+
+    This function is equivalent to ``tuple(np.moveaxis(x, axis, 0))``, since
+    iterating on an array iterates along the first axis.
+
+    Examples
+    --------
+    >>> arr = np.arange(24).reshape((2, 3, 4))
+    >>> np.unstack(arr)
+    (array([[ 0,  1,  2,  3],
+            [ 4,  5,  6,  7],
+            [ 8,  9, 10, 11]]),
+     array([[12, 13, 14, 15],
+            [16, 17, 18, 19],
+            [20, 21, 22, 23]]))
+    >>> np.unstack(arr, axis=1)
+    (array([[ 0,  1,  2,  3],
+            [12, 13, 14, 15]]),
+     array([[ 4,  5,  6,  7],
+            [16, 17, 18, 19]]),
+     array([[ 8,  9, 10, 11],
+            [20, 21, 22, 23]]))
+    >>> arr2 = np.stack(np.unstack(arr, axis=1), axis=1)
+    >>> arr2.shape
+    (2, 3, 4)
+    >>> np.all(arr == arr2)
+    np.True_
+
+    """
+    if x.ndim == 0:
+        raise ValueError("Input array must be at least 1-d.")
+    return tuple(_nx.moveaxis(x, axis, 0))
+
+
+# Internal functions to eliminate the overhead of repeated dispatch in one of
+# the two possible paths inside np.block.
+# Use getattr to protect against __array_function__ being disabled.
+_size = getattr(_from_nx.size, '__wrapped__', _from_nx.size)
+_ndim = getattr(_from_nx.ndim, '__wrapped__', _from_nx.ndim)
+_concatenate = getattr(_from_nx.concatenate,
+                       '__wrapped__', _from_nx.concatenate)
+
+
+def _block_format_index(index):
+    """
+    Convert a list of indices ``[0, 1, 2]`` into ``"arrays[0][1][2]"``.
+    """
+    idx_str = ''.join(f'[{i}]' for i in index if i is not None)
+    return 'arrays' + idx_str
+
+
+def _block_check_depths_match(arrays, parent_index=[]):
+    """
+    Recursive function checking that the depths of nested lists in `arrays`
+    all match. Mismatch raises a ValueError as described in the block
+    docstring below.
+
+    The entire index (rather than just the depth) needs to be calculated
+    for each innermost list, in case an error needs to be raised, so that
+    the index of the offending list can be printed as part of the error.
+
+    Parameters
+    ----------
+    arrays : nested list of arrays
+        The arrays to check
+    parent_index : list of int
+        The full index of `arrays` within the nested lists passed to
+        `_block_check_depths_match` at the top of the recursion.
+
+    Returns
+    -------
+    first_index : list of int
+        The full index of an element from the bottom of the nesting in
+        `arrays`. If any element at the bottom is an empty list, this will
+        refer to it, and the last index along the empty axis will be None.
+    max_arr_ndim : int
+        The maximum of the ndims of the arrays nested in `arrays`.
+    final_size: int
+        The number of elements in the final array. This is used the motivate
+        the choice of algorithm used using benchmarking wisdom.
+
+    """
+    if isinstance(arrays, tuple):
+        # not strictly necessary, but saves us from:
+        #  - more than one way to do things - no point treating tuples like
+        #    lists
+        #  - horribly confusing behaviour that results when tuples are
+        #    treated like ndarray
+        raise TypeError(
+            f'{_block_format_index(parent_index)} is a tuple. '
+            'Only lists can be used to arrange blocks, and np.block does '
+            'not allow implicit conversion from tuple to ndarray.'
+        )
+    elif isinstance(arrays, list) and len(arrays) > 0:
+        idxs_ndims = (_block_check_depths_match(arr, parent_index + [i])
+                      for i, arr in enumerate(arrays))
+
+        first_index, max_arr_ndim, final_size = next(idxs_ndims)
+        for index, ndim, size in idxs_ndims:
+            final_size += size
+            if ndim > max_arr_ndim:
+                max_arr_ndim = ndim
+            if len(index) != len(first_index):
+                raise ValueError(
+                    "List depths are mismatched. First element was at "
+                    f"depth {len(first_index)}, but there is an element at "
+                    f"depth {len(index)} ({_block_format_index(index)})"
+                )
+            # propagate our flag that indicates an empty list at the bottom
+            if index[-1] is None:
+                first_index = index
+
+        return first_index, max_arr_ndim, final_size
+    elif isinstance(arrays, list) and len(arrays) == 0:
+        # We've 'bottomed out' on an empty list
+        return parent_index + [None], 0, 0
+    else:
+        # We've 'bottomed out' - arrays is either a scalar or an array
+        size = _size(arrays)
+        return parent_index, _ndim(arrays), size
+
+
+def _atleast_nd(a, ndim):
+    # Ensures `a` has at least `ndim` dimensions by prepending
+    # ones to `a.shape` as necessary
+    return array(a, ndmin=ndim, copy=None, subok=True)
+
+
+def _accumulate(values):
+    return list(itertools.accumulate(values))
+
+
+def _concatenate_shapes(shapes, axis):
+    """Given array shapes, return the resulting shape and slices prefixes.
+
+    These help in nested concatenation.
+
+    Returns
+    -------
+    shape: tuple of int
+        This tuple satisfies::
+
+            shape, _ = _concatenate_shapes([arr.shape for shape in arrs], axis)
+            shape == concatenate(arrs, axis).shape
+
+    slice_prefixes: tuple of (slice(start, end), )
+        For a list of arrays being concatenated, this returns the slice
+        in the larger array at axis that needs to be sliced into.
+
+        For example, the following holds::
+
+            ret = concatenate([a, b, c], axis)
+            _, (sl_a, sl_b, sl_c) = concatenate_slices([a, b, c], axis)
+
+            ret[(slice(None),) * axis + sl_a] == a
+            ret[(slice(None),) * axis + sl_b] == b
+            ret[(slice(None),) * axis + sl_c] == c
+
+        These are called slice prefixes since they are used in the recursive
+        blocking algorithm to compute the left-most slices during the
+        recursion. Therefore, they must be prepended to rest of the slice
+        that was computed deeper in the recursion.
+
+        These are returned as tuples to ensure that they can quickly be added
+        to existing slice tuple without creating a new tuple every time.
+
+    """
+    # Cache a result that will be reused.
+    shape_at_axis = [shape[axis] for shape in shapes]
+
+    # Take a shape, any shape
+    first_shape = shapes[0]
+    first_shape_pre = first_shape[:axis]
+    first_shape_post = first_shape[axis + 1:]
+
+    if any(shape[:axis] != first_shape_pre or
+           shape[axis + 1:] != first_shape_post for shape in shapes):
+        raise ValueError(
+            f'Mismatched array shapes in block along axis {axis}.')
+
+    shape = (first_shape_pre + (sum(shape_at_axis),) + first_shape[axis + 1:])
+
+    offsets_at_axis = _accumulate(shape_at_axis)
+    slice_prefixes = [(slice(start, end),)
+                      for start, end in zip([0] + offsets_at_axis,
+                                            offsets_at_axis)]
+    return shape, slice_prefixes
+
+
+def _block_info_recursion(arrays, max_depth, result_ndim, depth=0):
+    """
+    Returns the shape of the final array, along with a list
+    of slices and a list of arrays that can be used for assignment inside the
+    new array
+
+    Parameters
+    ----------
+    arrays : nested list of arrays
+        The arrays to check
+    max_depth : list of int
+        The number of nested lists
+    result_ndim : int
+        The number of dimensions in thefinal array.
+
+    Returns
+    -------
+    shape : tuple of int
+        The shape that the final array will take on.
+    slices: list of tuple of slices
+        The slices into the full array required for assignment. These are
+        required to be prepended with ``(Ellipsis, )`` to obtain to correct
+        final index.
+    arrays: list of ndarray
+        The data to assign to each slice of the full array
+
+    """
+    if depth < max_depth:
+        shapes, slices, arrays = zip(
+            *[_block_info_recursion(arr, max_depth, result_ndim, depth + 1)
+              for arr in arrays])
+
+        axis = result_ndim - max_depth + depth
+        shape, slice_prefixes = _concatenate_shapes(shapes, axis)
+
+        # Prepend the slice prefix and flatten the slices
+        slices = [slice_prefix + the_slice
+                  for slice_prefix, inner_slices in zip(slice_prefixes, slices)
+                  for the_slice in inner_slices]
+
+        # Flatten the array list
+        arrays = functools.reduce(operator.add, arrays)
+
+        return shape, slices, arrays
+    else:
+        # We've 'bottomed out' - arrays is either a scalar or an array
+        # type(arrays) is not list
+        # Return the slice and the array inside a list to be consistent with
+        # the recursive case.
+        arr = _atleast_nd(arrays, result_ndim)
+        return arr.shape, [()], [arr]
+
+
+def _block(arrays, max_depth, result_ndim, depth=0):
+    """
+    Internal implementation of block based on repeated concatenation.
+    `arrays` is the argument passed to
+    block. `max_depth` is the depth of nested lists within `arrays` and
+    `result_ndim` is the greatest of the dimensions of the arrays in
+    `arrays` and the depth of the lists in `arrays` (see block docstring
+    for details).
+    """
+    if depth < max_depth:
+        arrs = [_block(arr, max_depth, result_ndim, depth + 1)
+                for arr in arrays]
+        return _concatenate(arrs, axis=-(max_depth - depth))
+    else:
+        # We've 'bottomed out' - arrays is either a scalar or an array
+        # type(arrays) is not list
+        return _atleast_nd(arrays, result_ndim)
+
+
+def _block_dispatcher(arrays):
+    # Use type(...) is list to match the behavior of np.block(), which special
+    # cases list specifically rather than allowing for generic iterables or
+    # tuple. Also, we know that list.__array_function__ will never exist.
+    if isinstance(arrays, list):
+        for subarrays in arrays:
+            yield from _block_dispatcher(subarrays)
+    else:
+        yield arrays
+
+
+@array_function_dispatch(_block_dispatcher)
+def block(arrays):
+    """
+    Assemble an nd-array from nested lists of blocks.
+
+    Blocks in the innermost lists are concatenated (see `concatenate`) along
+    the last dimension (-1), then these are concatenated along the
+    second-last dimension (-2), and so on until the outermost list is reached.
+
+    Blocks can be of any dimension, but will not be broadcasted using
+    the normal rules. Instead, leading axes of size 1 are inserted,
+    to make ``block.ndim`` the same for all blocks. This is primarily useful
+    for working with scalars, and means that code like ``np.block([v, 1])``
+    is valid, where ``v.ndim == 1``.
+
+    When the nested list is two levels deep, this allows block matrices to be
+    constructed from their components.
+
+    Parameters
+    ----------
+    arrays : nested list of array_like or scalars (but not tuples)
+        If passed a single ndarray or scalar (a nested list of depth 0), this
+        is returned unmodified (and not copied).
+
+        Elements shapes must match along the appropriate axes (without
+        broadcasting), but leading 1s will be prepended to the shape as
+        necessary to make the dimensions match.
+
+    Returns
+    -------
+    block_array : ndarray
+        The array assembled from the given blocks.
+
+        The dimensionality of the output is equal to the greatest of:
+
+        * the dimensionality of all the inputs
+        * the depth to which the input list is nested
+
+    Raises
+    ------
+    ValueError
+        * If list depths are mismatched - for instance, ``[[a, b], c]`` is
+          illegal, and should be spelt ``[[a, b], [c]]``
+        * If lists are empty - for instance, ``[[a, b], []]``
+
+    See Also
+    --------
+    concatenate : Join a sequence of arrays along an existing axis.
+    stack : Join a sequence of arrays along a new axis.
+    vstack : Stack arrays in sequence vertically (row wise).
+    hstack : Stack arrays in sequence horizontally (column wise).
+    dstack : Stack arrays in sequence depth wise (along third axis).
+    column_stack : Stack 1-D arrays as columns into a 2-D array.
+    vsplit : Split an array into multiple sub-arrays vertically (row-wise).
+    unstack : Split an array into a tuple of sub-arrays along an axis.
+
+    Notes
+    -----
+    When called with only scalars, ``np.block`` is equivalent to an ndarray
+    call. So ``np.block([[1, 2], [3, 4]])`` is equivalent to
+    ``np.array([[1, 2], [3, 4]])``.
+
+    This function does not enforce that the blocks lie on a fixed grid.
+    ``np.block([[a, b], [c, d]])`` is not restricted to arrays of the form::
+
+        AAAbb
+        AAAbb
+        cccDD
+
+    But is also allowed to produce, for some ``a, b, c, d``::
+
+        AAAbb
+        AAAbb
+        cDDDD
+
+    Since concatenation happens along the last axis first, `block` is *not*
+    capable of producing the following directly::
+
+        AAAbb
+        cccbb
+        cccDD
+
+    Matlab's "square bracket stacking", ``[A, B, ...; p, q, ...]``, is
+    equivalent to ``np.block([[A, B, ...], [p, q, ...]])``.
+
+    Examples
+    --------
+    The most common use of this function is to build a block matrix:
+
+    >>> import numpy as np
+    >>> A = np.eye(2) * 2
+    >>> B = np.eye(3) * 3
+    >>> np.block([
+    ...     [A,               np.zeros((2, 3))],
+    ...     [np.ones((3, 2)), B               ]
+    ... ])
+    array([[2., 0., 0., 0., 0.],
+           [0., 2., 0., 0., 0.],
+           [1., 1., 3., 0., 0.],
+           [1., 1., 0., 3., 0.],
+           [1., 1., 0., 0., 3.]])
+
+    With a list of depth 1, `block` can be used as `hstack`:
+
+    >>> np.block([1, 2, 3])              # hstack([1, 2, 3])
+    array([1, 2, 3])
+
+    >>> a = np.array([1, 2, 3])
+    >>> b = np.array([4, 5, 6])
+    >>> np.block([a, b, 10])             # hstack([a, b, 10])
+    array([ 1,  2,  3,  4,  5,  6, 10])
+
+    >>> A = np.ones((2, 2), int)
+    >>> B = 2 * A
+    >>> np.block([A, B])                 # hstack([A, B])
+    array([[1, 1, 2, 2],
+           [1, 1, 2, 2]])
+
+    With a list of depth 2, `block` can be used in place of `vstack`:
+
+    >>> a = np.array([1, 2, 3])
+    >>> b = np.array([4, 5, 6])
+    >>> np.block([[a], [b]])             # vstack([a, b])
+    array([[1, 2, 3],
+           [4, 5, 6]])
+
+    >>> A = np.ones((2, 2), int)
+    >>> B = 2 * A
+    >>> np.block([[A], [B]])             # vstack([A, B])
+    array([[1, 1],
+           [1, 1],
+           [2, 2],
+           [2, 2]])
+
+    It can also be used in place of `atleast_1d` and `atleast_2d`:
+
+    >>> a = np.array(0)
+    >>> b = np.array([1])
+    >>> np.block([a])                    # atleast_1d(a)
+    array([0])
+    >>> np.block([b])                    # atleast_1d(b)
+    array([1])
+
+    >>> np.block([[a]])                  # atleast_2d(a)
+    array([[0]])
+    >>> np.block([[b]])                  # atleast_2d(b)
+    array([[1]])
+
+
+    """
+    arrays, list_ndim, result_ndim, final_size = _block_setup(arrays)
+
+    # It was found through benchmarking that making an array of final size
+    # around 256x256 was faster by straight concatenation on a
+    # i7-7700HQ processor and dual channel ram 2400MHz.
+    # It didn't seem to matter heavily on the dtype used.
+    #
+    # A 2D array using repeated concatenation requires 2 copies of the array.
+    #
+    # The fastest algorithm will depend on the ratio of CPU power to memory
+    # speed.
+    # One can monitor the results of the benchmark
+    # https://pv.github.io/numpy-bench/#bench_shape_base.Block2D.time_block2d
+    # to tune this parameter until a C version of the `_block_info_recursion`
+    # algorithm is implemented which would likely be faster than the python
+    # version.
+    if list_ndim * final_size > (2 * 512 * 512):
+        return _block_slicing(arrays, list_ndim, result_ndim)
+    else:
+        return _block_concatenate(arrays, list_ndim, result_ndim)
+
+
+# These helper functions are mostly used for testing.
+# They allow us to write tests that directly call `_block_slicing`
+# or `_block_concatenate` without blocking large arrays to force the wisdom
+# to trigger the desired path.
+def _block_setup(arrays):
+    """
+    Returns
+    (`arrays`, list_ndim, result_ndim, final_size)
+    """
+    bottom_index, arr_ndim, final_size = _block_check_depths_match(arrays)
+    list_ndim = len(bottom_index)
+    if bottom_index and bottom_index[-1] is None:
+        raise ValueError(
+            f'List at {_block_format_index(bottom_index)} cannot be empty'
+        )
+    result_ndim = max(arr_ndim, list_ndim)
+    return arrays, list_ndim, result_ndim, final_size
+
+
+def _block_slicing(arrays, list_ndim, result_ndim):
+    shape, slices, arrays = _block_info_recursion(
+        arrays, list_ndim, result_ndim)
+    dtype = _nx.result_type(*[arr.dtype for arr in arrays])
+
+    # Test preferring F only in the case that all input arrays are F
+    F_order = all(arr.flags['F_CONTIGUOUS'] for arr in arrays)
+    C_order = all(arr.flags['C_CONTIGUOUS'] for arr in arrays)
+    order = 'F' if F_order and not C_order else 'C'
+    result = _nx.empty(shape=shape, dtype=dtype, order=order)
+    # Note: In a c implementation, the function
+    # PyArray_CreateMultiSortedStridePerm could be used for more advanced
+    # guessing of the desired order.
+
+    for the_slice, arr in zip(slices, arrays):
+        result[(Ellipsis,) + the_slice] = arr
+    return result
+
+
+def _block_concatenate(arrays, list_ndim, result_ndim):
+    result = _block(arrays, list_ndim, result_ndim)
+    if list_ndim == 0:
+        # Catch an edge case where _block returns a view because
+        # `arrays` is a single numpy array and not a list of numpy arrays.
+        # This might copy scalars or lists twice, but this isn't a likely
+        # usecase for those interested in performance
+        result = result.copy()
+    return result

v12x/pylib/numpy/_core/strings.py

@@ -0,0 +1,1813 @@
+"""
+This module contains a set of functions for vectorized string
+operations.
+"""
+
+import functools
+import sys
+
+import numpy as np
+from numpy import (
+    add,
+    equal,
+    greater,
+    greater_equal,
+    less,
+    less_equal,
+    multiply as _multiply_ufunc,
+    not_equal,
+)
+from numpy._core.multiarray import _vec_string
+from numpy._core.overrides import array_function_dispatch, set_module
+from numpy._core.umath import (
+    _center,
+    _expandtabs,
+    _expandtabs_length,
+    _ljust,
+    _lstrip_chars,
+    _lstrip_whitespace,
+    _partition,
+    _partition_index,
+    _replace,
+    _rjust,
+    _rpartition,
+    _rpartition_index,
+    _rstrip_chars,
+    _rstrip_whitespace,
+    _slice,
+    _strip_chars,
+    _strip_whitespace,
+    _zfill,
+    count as _count_ufunc,
+    endswith as _endswith_ufunc,
+    find as _find_ufunc,
+    index as _index_ufunc,
+    isalnum,
+    isalpha,
+    isdecimal,
+    isdigit,
+    islower,
+    isnumeric,
+    isspace,
+    istitle,
+    isupper,
+    rfind as _rfind_ufunc,
+    rindex as _rindex_ufunc,
+    startswith as _startswith_ufunc,
+    str_len,
+)
+
+
+def _override___module__():
+    for ufunc in [
+        isalnum, isalpha, isdecimal, isdigit, islower, isnumeric, isspace,
+        istitle, isupper, str_len,
+    ]:
+        ufunc.__module__ = "numpy.strings"
+        ufunc.__qualname__ = ufunc.__name__
+
+
+_override___module__()
+
+
+__all__ = [
+    # UFuncs
+    "equal", "not_equal", "less", "less_equal", "greater", "greater_equal",
+    "add", "multiply", "isalpha", "isdigit", "isspace", "isalnum", "islower",
+    "isupper", "istitle", "isdecimal", "isnumeric", "str_len", "find",
+    "rfind", "index", "rindex", "count", "startswith", "endswith", "lstrip",
+    "rstrip", "strip", "replace", "expandtabs", "center", "ljust", "rjust",
+    "zfill", "partition", "rpartition", "slice",
+
+    # _vec_string - Will gradually become ufuncs as well
+    "upper", "lower", "swapcase", "capitalize", "title",
+
+    # _vec_string - Will probably not become ufuncs
+    "mod", "decode", "encode", "translate",
+
+    # Removed from namespace until behavior has been crystallized
+    # "join", "split", "rsplit", "splitlines",
+]
+
+
+MAX = np.iinfo(np.int64).max
+
+array_function_dispatch = functools.partial(
+    array_function_dispatch, module='numpy.strings')
+
+
+def _get_num_chars(a):
+    """
+    Helper function that returns the number of characters per field in
+    a string or unicode array.  This is to abstract out the fact that
+    for a unicode array this is itemsize / 4.
+    """
+    if issubclass(a.dtype.type, np.str_):
+        return a.itemsize // 4
+    return a.itemsize
+
+
+def _to_bytes_or_str_array(result, output_dtype_like):
+    """
+    Helper function to cast a result back into an array
+    with the appropriate dtype if an object array must be used
+    as an intermediary.
+    """
+    output_dtype_like = np.asarray(output_dtype_like)
+    if result.size == 0:
+        # Calling asarray & tolist in an empty array would result
+        # in losing shape information
+        return result.astype(output_dtype_like.dtype)
+    ret = np.asarray(result.tolist())
+    if isinstance(output_dtype_like.dtype, np.dtypes.StringDType):
+        return ret.astype(type(output_dtype_like.dtype))
+    return ret.astype(type(output_dtype_like.dtype)(_get_num_chars(ret)))
+
+
+def _clean_args(*args):
+    """
+    Helper function for delegating arguments to Python string
+    functions.
+
+    Many of the Python string operations that have optional arguments
+    do not use 'None' to indicate a default value.  In these cases,
+    we need to remove all None arguments, and those following them.
+    """
+    newargs = []
+    for chk in args:
+        if chk is None:
+            break
+        newargs.append(chk)
+    return newargs
+
+
+def _multiply_dispatcher(a, i):
+    return (a,)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_multiply_dispatcher)
+def multiply(a, i):
+    """
+    Return (a * i), that is string multiple concatenation,
+    element-wise.
+
+    Values in ``i`` of less than 0 are treated as 0 (which yields an
+    empty string).
+
+    Parameters
+    ----------
+    a : array_like, with ``StringDType``, ``bytes_`` or ``str_`` dtype
+
+    i : array_like, with any integer dtype
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(["a", "b", "c"])
+    >>> np.strings.multiply(a, 3)
+    array(['aaa', 'bbb', 'ccc'], dtype='<U3')
+    >>> i = np.array([1, 2, 3])
+    >>> np.strings.multiply(a, i)
+    array(['a', 'bb', 'ccc'], dtype='<U3')
+    >>> np.strings.multiply(np.array(['a']), i)
+    array(['a', 'aa', 'aaa'], dtype='<U3')
+    >>> a = np.array(['a', 'b', 'c', 'd', 'e', 'f']).reshape((2, 3))
+    >>> np.strings.multiply(a, 3)
+    array([['aaa', 'bbb', 'ccc'],
+           ['ddd', 'eee', 'fff']], dtype='<U3')
+    >>> np.strings.multiply(a, i)
+    array([['a', 'bb', 'ccc'],
+           ['d', 'ee', 'fff']], dtype='<U3')
+
+    """
+    a = np.asanyarray(a)
+
+    i = np.asanyarray(i)
+    if not np.issubdtype(i.dtype, np.integer):
+        raise TypeError(f"unsupported type {i.dtype} for operand 'i'")
+    i = np.maximum(i, 0)
+
+    # delegate to stringdtype loops that also do overflow checking
+    if a.dtype.char == "T":
+        return a * i
+
+    a_len = str_len(a)
+
+    # Ensure we can do a_len * i without overflow.
+    if np.any(a_len > sys.maxsize / np.maximum(i, 1)):
+        raise OverflowError("Overflow encountered in string multiply")
+
+    buffersizes = a_len * i
+    out_dtype = f"{a.dtype.char}{buffersizes.max()}"
+    out = np.empty_like(a, shape=buffersizes.shape, dtype=out_dtype)
+    return _multiply_ufunc(a, i, out=out)
+
+
+def _mod_dispatcher(a, values):
+    return (a, values)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_mod_dispatcher)
+def mod(a, values):
+    """
+    Return (a % i), that is pre-Python 2.6 string formatting
+    (interpolation), element-wise for a pair of array_likes of str
+    or unicode.
+
+    Parameters
+    ----------
+    a : array_like, with ``bytes_`` or ``str_`` dtype
+
+    values : array_like of values
+       These values will be element-wise interpolated into the string.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(["NumPy is a %s library"])
+    >>> np.strings.mod(a, values=["Python"])
+    array(['NumPy is a Python library'], dtype='<U25')
+
+    >>> a = np.array([b'%d bytes', b'%d bits'])
+    >>> values = np.array([8, 64])
+    >>> np.strings.mod(a, values)
+    array([b'8 bytes', b'64 bits'], dtype='|S7')
+
+    """
+    return _to_bytes_or_str_array(
+        _vec_string(a, np.object_, '__mod__', (values,)), a)
+
+
+@set_module("numpy.strings")
+def find(a, sub, start=0, end=None):
+    """
+    For each element, return the lowest index in the string where
+    substring ``sub`` is found, such that ``sub`` is contained in the
+    range [``start``, ``end``).
+
+    Parameters
+    ----------
+    a : array_like, with ``StringDType``, ``bytes_`` or ``str_`` dtype
+
+    sub : array_like, with ``bytes_`` or ``str_`` dtype
+        The substring to search for.
+
+    start, end : array_like, with any integer dtype
+        The range to look in, interpreted as in slice notation.
+
+    Returns
+    -------
+    y : ndarray
+        Output array of ints
+
+    See Also
+    --------
+    str.find
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(["NumPy is a Python library"])
+    >>> np.strings.find(a, "Python")
+    array([11])
+
+    """
+    end = end if end is not None else MAX
+    return _find_ufunc(a, sub, start, end)
+
+
+@set_module("numpy.strings")
+def rfind(a, sub, start=0, end=None):
+    """
+    For each element, return the highest index in the string where
+    substring ``sub`` is found, such that ``sub`` is contained in the
+    range [``start``, ``end``).
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    sub : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        The substring to search for.
+
+    start, end : array_like, with any integer dtype
+        The range to look in, interpreted as in slice notation.
+
+    Returns
+    -------
+    y : ndarray
+        Output array of ints
+
+    See Also
+    --------
+    str.rfind
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(["Computer Science"])
+    >>> np.strings.rfind(a, "Science", start=0, end=None)
+    array([9])
+    >>> np.strings.rfind(a, "Science", start=0, end=8)
+    array([-1])
+    >>> b = np.array(["Computer Science", "Science"])
+    >>> np.strings.rfind(b, "Science", start=0, end=None)
+    array([9, 0])
+
+    """
+    end = end if end is not None else MAX
+    return _rfind_ufunc(a, sub, start, end)
+
+
+@set_module("numpy.strings")
+def index(a, sub, start=0, end=None):
+    """
+    Like `find`, but raises :exc:`ValueError` when the substring is not found.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    sub : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    start, end : array_like, with any integer dtype, optional
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ints.
+
+    See Also
+    --------
+    find, str.index
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(["Computer Science"])
+    >>> np.strings.index(a, "Science", start=0, end=None)
+    array([9])
+
+    """
+    end = end if end is not None else MAX
+    return _index_ufunc(a, sub, start, end)
+
+
+@set_module("numpy.strings")
+def rindex(a, sub, start=0, end=None):
+    """
+    Like `rfind`, but raises :exc:`ValueError` when the substring `sub` is
+    not found.
+
+    Parameters
+    ----------
+    a : array-like, with ``bytes_`` or ``str_`` dtype
+
+    sub : array-like, with ``bytes_`` or ``str_`` dtype
+
+    start, end : array-like, with any integer dtype, optional
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ints.
+
+    See Also
+    --------
+    rfind, str.rindex
+
+    Examples
+    --------
+    >>> a = np.array(["Computer Science"])
+    >>> np.strings.rindex(a, "Science", start=0, end=None)
+    array([9])
+
+    """
+    end = end if end is not None else MAX
+    return _rindex_ufunc(a, sub, start, end)
+
+
+@set_module("numpy.strings")
+def count(a, sub, start=0, end=None):
+    """
+    Returns an array with the number of non-overlapping occurrences of
+    substring ``sub`` in the range [``start``, ``end``).
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    sub : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+       The substring to search for.
+
+    start, end : array_like, with any integer dtype
+        The range to look in, interpreted as in slice notation.
+
+    Returns
+    -------
+    y : ndarray
+        Output array of ints
+
+    See Also
+    --------
+    str.count
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array(['aAaAaA', '  aA  ', 'abBABba'])
+    >>> c
+    array(['aAaAaA', '  aA  ', 'abBABba'], dtype='<U7')
+    >>> np.strings.count(c, 'A')
+    array([3, 1, 1])
+    >>> np.strings.count(c, 'aA')
+    array([3, 1, 0])
+    >>> np.strings.count(c, 'A', start=1, end=4)
+    array([2, 1, 1])
+    >>> np.strings.count(c, 'A', start=1, end=3)
+    array([1, 0, 0])
+
+    """
+    end = end if end is not None else MAX
+    return _count_ufunc(a, sub, start, end)
+
+
+@set_module("numpy.strings")
+def startswith(a, prefix, start=0, end=None):
+    """
+    Returns a boolean array which is `True` where the string element
+    in ``a`` starts with ``prefix``, otherwise `False`.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    prefix : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    start, end : array_like, with any integer dtype
+        With ``start``, test beginning at that position. With ``end``,
+        stop comparing at that position.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of bools
+
+    See Also
+    --------
+    str.startswith
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> s = np.array(['foo', 'bar'])
+    >>> s
+    array(['foo', 'bar'], dtype='<U3')
+    >>> np.strings.startswith(s, 'fo')
+    array([True,  False])
+    >>> np.strings.startswith(s, 'o', start=1, end=2)
+    array([True,  False])
+
+    """
+    end = end if end is not None else MAX
+    return _startswith_ufunc(a, prefix, start, end)
+
+
+@set_module("numpy.strings")
+def endswith(a, suffix, start=0, end=None):
+    """
+    Returns a boolean array which is `True` where the string element
+    in ``a`` ends with ``suffix``, otherwise `False`.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    suffix : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    start, end : array_like, with any integer dtype
+        With ``start``, test beginning at that position. With ``end``,
+        stop comparing at that position.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of bools
+
+    See Also
+    --------
+    str.endswith
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> s = np.array(['foo', 'bar'])
+    >>> s
+    array(['foo', 'bar'], dtype='<U3')
+    >>> np.strings.endswith(s, 'ar')
+    array([False,  True])
+    >>> np.strings.endswith(s, 'a', start=1, end=2)
+    array([False,  True])
+
+    """
+    end = end if end is not None else MAX
+    return _endswith_ufunc(a, suffix, start, end)
+
+
+def _code_dispatcher(a, encoding=None, errors=None):
+    return (a,)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_code_dispatcher)
+def decode(a, encoding=None, errors=None):
+    r"""
+    Calls :meth:`bytes.decode` element-wise.
+
+    The set of available codecs comes from the Python standard library,
+    and may be extended at runtime.  For more information, see the
+    :mod:`codecs` module.
+
+    Parameters
+    ----------
+    a : array_like, with ``bytes_`` dtype
+
+    encoding : str, optional
+       The name of an encoding
+
+    errors : str, optional
+       Specifies how to handle encoding errors
+
+    Returns
+    -------
+    out : ndarray
+
+    See Also
+    --------
+    :py:meth:`bytes.decode`
+
+    Notes
+    -----
+    The type of the result will depend on the encoding specified.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array([b'\x81\xc1\x81\xc1\x81\xc1', b'@@\x81\xc1@@',
+    ...               b'\x81\x82\xc2\xc1\xc2\x82\x81'])
+    >>> c
+    array([b'\x81\xc1\x81\xc1\x81\xc1', b'@@\x81\xc1@@',
+           b'\x81\x82\xc2\xc1\xc2\x82\x81'], dtype='|S7')
+    >>> np.strings.decode(c, encoding='cp037')
+    array(['aAaAaA', '  aA  ', 'abBABba'], dtype='<U7')
+
+    """
+    return _to_bytes_or_str_array(
+        _vec_string(a, np.object_, 'decode', _clean_args(encoding, errors)),
+        np.str_(''))
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_code_dispatcher)
+def encode(a, encoding=None, errors=None):
+    """
+    Calls :meth:`str.encode` element-wise.
+
+    The set of available codecs comes from the Python standard library,
+    and may be extended at runtime. For more information, see the
+    :mod:`codecs` module.
+
+    Parameters
+    ----------
+    a : array_like, with ``StringDType`` or ``str_`` dtype
+
+    encoding : str, optional
+       The name of an encoding
+
+    errors : str, optional
+       Specifies how to handle encoding errors
+
+    Returns
+    -------
+    out : ndarray
+
+    See Also
+    --------
+    str.encode
+
+    Notes
+    -----
+    The type of the result will depend on the encoding specified.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(['aAaAaA', '  aA  ', 'abBABba'])
+    >>> np.strings.encode(a, encoding='cp037')
+    array([b'\x81\xc1\x81\xc1\x81\xc1', b'@@\x81\xc1@@',
+       b'\x81\x82\xc2\xc1\xc2\x82\x81'], dtype='|S7')
+
+    """
+    return _to_bytes_or_str_array(
+        _vec_string(a, np.object_, 'encode', _clean_args(encoding, errors)),
+        np.bytes_(b''))
+
+
+def _expandtabs_dispatcher(a, tabsize=None):
+    return (a,)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_expandtabs_dispatcher)
+def expandtabs(a, tabsize=8):
+    """
+    Return a copy of each string element where all tab characters are
+    replaced by one or more spaces.
+
+    Calls :meth:`str.expandtabs` element-wise.
+
+    Return a copy of each string element where all tab characters are
+    replaced by one or more spaces, depending on the current column
+    and the given `tabsize`. The column number is reset to zero after
+    each newline occurring in the string. This doesn't understand other
+    non-printing characters or escape sequences.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array
+    tabsize : int, optional
+        Replace tabs with `tabsize` number of spaces.  If not given defaults
+        to 8 spaces.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input type
+
+    See Also
+    --------
+    str.expandtabs
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(['\t\tHello\tworld'])
+    >>> np.strings.expandtabs(a, tabsize=4)  # doctest: +SKIP
+    array(['        Hello   world'], dtype='<U21')  # doctest: +SKIP
+
+    """
+    a = np.asanyarray(a)
+    tabsize = np.asanyarray(tabsize)
+
+    if a.dtype.char == "T":
+        return _expandtabs(a, tabsize)
+
+    buffersizes = _expandtabs_length(a, tabsize)
+    out_dtype = f"{a.dtype.char}{buffersizes.max()}"
+    out = np.empty_like(a, shape=buffersizes.shape, dtype=out_dtype)
+    return _expandtabs(a, tabsize, out=out)
+
+
+def _just_dispatcher(a, width, fillchar=None):
+    return (a,)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_just_dispatcher)
+def center(a, width, fillchar=' '):
+    """
+    Return a copy of `a` with its elements centered in a string of
+    length `width`.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    width : array_like, with any integer dtype
+        The length of the resulting strings, unless ``width < str_len(a)``.
+    fillchar : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Optional padding character to use (default is space).
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.center
+
+    Notes
+    -----
+    While it is possible for ``a`` and ``fillchar`` to have different dtypes,
+    passing a non-ASCII character in ``fillchar`` when ``a`` is of dtype "S"
+    is not allowed, and a ``ValueError`` is raised.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array(['a1b2','1b2a','b2a1','2a1b']); c
+    array(['a1b2', '1b2a', 'b2a1', '2a1b'], dtype='<U4')
+    >>> np.strings.center(c, width=9)
+    array(['   a1b2  ', '   1b2a  ', '   b2a1  ', '   2a1b  '], dtype='<U9')
+    >>> np.strings.center(c, width=9, fillchar='*')
+    array(['***a1b2**', '***1b2a**', '***b2a1**', '***2a1b**'], dtype='<U9')
+    >>> np.strings.center(c, width=1)
+    array(['a1b2', '1b2a', 'b2a1', '2a1b'], dtype='<U4')
+
+    """
+    width = np.asanyarray(width)
+
+    if not np.issubdtype(width.dtype, np.integer):
+        raise TypeError(f"unsupported type {width.dtype} for operand 'width'")
+
+    a = np.asanyarray(a)
+    fillchar = np.asanyarray(fillchar)
+
+    if np.any(str_len(fillchar) != 1):
+        raise TypeError(
+            "The fill character must be exactly one character long")
+
+    if np.result_type(a, fillchar).char == "T":
+        return _center(a, width, fillchar)
+
+    fillchar = fillchar.astype(a.dtype, copy=False)
+    width = np.maximum(str_len(a), width)
+    out_dtype = f"{a.dtype.char}{width.max()}"
+    shape = np.broadcast_shapes(a.shape, width.shape, fillchar.shape)
+    out = np.empty_like(a, shape=shape, dtype=out_dtype)
+
+    return _center(a, width, fillchar, out=out)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_just_dispatcher)
+def ljust(a, width, fillchar=' '):
+    """
+    Return an array with the elements of `a` left-justified in a
+    string of length `width`.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    width : array_like, with any integer dtype
+        The length of the resulting strings, unless ``width < str_len(a)``.
+    fillchar : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Optional character to use for padding (default is space).
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.ljust
+
+    Notes
+    -----
+    While it is possible for ``a`` and ``fillchar`` to have different dtypes,
+    passing a non-ASCII character in ``fillchar`` when ``a`` is of dtype "S"
+    is not allowed, and a ``ValueError`` is raised.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array(['aAaAaA', '  aA  ', 'abBABba'])
+    >>> np.strings.ljust(c, width=3)
+    array(['aAaAaA', '  aA  ', 'abBABba'], dtype='<U7')
+    >>> np.strings.ljust(c, width=9)
+    array(['aAaAaA   ', '  aA     ', 'abBABba  '], dtype='<U9')
+
+    """
+    width = np.asanyarray(width)
+    if not np.issubdtype(width.dtype, np.integer):
+        raise TypeError(f"unsupported type {width.dtype} for operand 'width'")
+
+    a = np.asanyarray(a)
+    fillchar = np.asanyarray(fillchar)
+
+    if np.any(str_len(fillchar) != 1):
+        raise TypeError(
+            "The fill character must be exactly one character long")
+
+    if np.result_type(a, fillchar).char == "T":
+        return _ljust(a, width, fillchar)
+
+    fillchar = fillchar.astype(a.dtype, copy=False)
+    width = np.maximum(str_len(a), width)
+    shape = np.broadcast_shapes(a.shape, width.shape, fillchar.shape)
+    out_dtype = f"{a.dtype.char}{width.max()}"
+    out = np.empty_like(a, shape=shape, dtype=out_dtype)
+
+    return _ljust(a, width, fillchar, out=out)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_just_dispatcher)
+def rjust(a, width, fillchar=' '):
+    """
+    Return an array with the elements of `a` right-justified in a
+    string of length `width`.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    width : array_like, with any integer dtype
+        The length of the resulting strings, unless ``width < str_len(a)``.
+    fillchar : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Optional padding character to use (default is space).
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.rjust
+
+    Notes
+    -----
+    While it is possible for ``a`` and ``fillchar`` to have different dtypes,
+    passing a non-ASCII character in ``fillchar`` when ``a`` is of dtype "S"
+    is not allowed, and a ``ValueError`` is raised.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(['aAaAaA', '  aA  ', 'abBABba'])
+    >>> np.strings.rjust(a, width=3)
+    array(['aAaAaA', '  aA  ', 'abBABba'], dtype='<U7')
+    >>> np.strings.rjust(a, width=9)
+    array(['   aAaAaA', '     aA  ', '  abBABba'], dtype='<U9')
+
+    """
+    width = np.asanyarray(width)
+    if not np.issubdtype(width.dtype, np.integer):
+        raise TypeError(f"unsupported type {width.dtype} for operand 'width'")
+
+    a = np.asanyarray(a)
+    fillchar = np.asanyarray(fillchar)
+
+    if np.any(str_len(fillchar) != 1):
+        raise TypeError(
+            "The fill character must be exactly one character long")
+
+    if np.result_type(a, fillchar).char == "T":
+        return _rjust(a, width, fillchar)
+
+    fillchar = fillchar.astype(a.dtype, copy=False)
+    width = np.maximum(str_len(a), width)
+    shape = np.broadcast_shapes(a.shape, width.shape, fillchar.shape)
+    out_dtype = f"{a.dtype.char}{width.max()}"
+    out = np.empty_like(a, shape=shape, dtype=out_dtype)
+
+    return _rjust(a, width, fillchar, out=out)
+
+
+def _zfill_dispatcher(a, width):
+    return (a,)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_zfill_dispatcher)
+def zfill(a, width):
+    """
+    Return the numeric string left-filled with zeros. A leading
+    sign prefix (``+``/``-``) is handled by inserting the padding
+    after the sign character rather than before.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    width : array_like, with any integer dtype
+        Width of string to left-fill elements in `a`.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input type
+
+    See Also
+    --------
+    str.zfill
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.strings.zfill(['1', '-1', '+1'], 3)
+    array(['001', '-01', '+01'], dtype='<U3')
+
+    """
+    width = np.asanyarray(width)
+    if not np.issubdtype(width.dtype, np.integer):
+        raise TypeError(f"unsupported type {width.dtype} for operand 'width'")
+
+    a = np.asanyarray(a)
+
+    if a.dtype.char == "T":
+        return _zfill(a, width)
+
+    width = np.maximum(str_len(a), width)
+    shape = np.broadcast_shapes(a.shape, width.shape)
+    out_dtype = f"{a.dtype.char}{width.max()}"
+    out = np.empty_like(a, shape=shape, dtype=out_dtype)
+    return _zfill(a, width, out=out)
+
+
+@set_module("numpy.strings")
+def lstrip(a, chars=None):
+    """
+    For each element in `a`, return a copy with the leading characters
+    removed.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+    chars : scalar with the same dtype as ``a``, optional
+       The ``chars`` argument is a string specifying the set of
+       characters to be removed. If ``None``, the ``chars``
+       argument defaults to removing whitespace. The ``chars`` argument
+       is not a prefix or suffix; rather, all combinations of its
+       values are stripped.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.lstrip
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array(['aAaAaA', '  aA  ', 'abBABba'])
+    >>> c
+    array(['aAaAaA', '  aA  ', 'abBABba'], dtype='<U7')
+    # The 'a' variable is unstripped from c[1] because of leading whitespace.
+    >>> np.strings.lstrip(c, 'a')
+    array(['AaAaA', '  aA  ', 'bBABba'], dtype='<U7')
+    >>> np.strings.lstrip(c, 'A') # leaves c unchanged
+    array(['aAaAaA', '  aA  ', 'abBABba'], dtype='<U7')
+    >>> (np.strings.lstrip(c, ' ') == np.strings.lstrip(c, '')).all()
+    np.False_
+    >>> (np.strings.lstrip(c, ' ') == np.strings.lstrip(c)).all()
+    np.True_
+
+    """
+    if chars is None:
+        return _lstrip_whitespace(a)
+    return _lstrip_chars(a, chars)
+
+
+@set_module("numpy.strings")
+def rstrip(a, chars=None):
+    """
+    For each element in `a`, return a copy with the trailing characters
+    removed.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+    chars : scalar with the same dtype as ``a``, optional
+       The ``chars`` argument is a string specifying the set of
+       characters to be removed. If ``None``, the ``chars``
+       argument defaults to removing whitespace. The ``chars`` argument
+       is not a prefix or suffix; rather, all combinations of its
+       values are stripped.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.rstrip
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array(['aAaAaA', 'abBABba'])
+    >>> c
+    array(['aAaAaA', 'abBABba'], dtype='<U7')
+    >>> np.strings.rstrip(c, 'a')
+    array(['aAaAaA', 'abBABb'], dtype='<U7')
+    >>> np.strings.rstrip(c, 'A')
+    array(['aAaAa', 'abBABba'], dtype='<U7')
+
+    """
+    if chars is None:
+        return _rstrip_whitespace(a)
+    return _rstrip_chars(a, chars)
+
+
+@set_module("numpy.strings")
+def strip(a, chars=None):
+    """
+    For each element in `a`, return a copy with the leading and
+    trailing characters removed.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+    chars : scalar with the same dtype as ``a``, optional
+       The ``chars`` argument is a string specifying the set of
+       characters to be removed. If ``None``, the ``chars``
+       argument defaults to removing whitespace. The ``chars`` argument
+       is not a prefix or suffix; rather, all combinations of its
+       values are stripped.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.strip
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array(['aAaAaA', '  aA  ', 'abBABba'])
+    >>> c
+    array(['aAaAaA', '  aA  ', 'abBABba'], dtype='<U7')
+    >>> np.strings.strip(c)
+    array(['aAaAaA', 'aA', 'abBABba'], dtype='<U7')
+    # 'a' unstripped from c[1] because of leading whitespace.
+    >>> np.strings.strip(c, 'a')
+    array(['AaAaA', '  aA  ', 'bBABb'], dtype='<U7')
+    # 'A' unstripped from c[1] because of trailing whitespace.
+    >>> np.strings.strip(c, 'A')
+    array(['aAaAa', '  aA  ', 'abBABba'], dtype='<U7')
+
+    """
+    if chars is None:
+        return _strip_whitespace(a)
+    return _strip_chars(a, chars)
+
+
+def _unary_op_dispatcher(a):
+    return (a,)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_unary_op_dispatcher)
+def upper(a):
+    """
+    Return an array with the elements converted to uppercase.
+
+    Calls :meth:`str.upper` element-wise.
+
+    For 8-bit strings, this method is locale-dependent.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.upper
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array(['a1b c', '1bca', 'bca1']); c
+    array(['a1b c', '1bca', 'bca1'], dtype='<U5')
+    >>> np.strings.upper(c)
+    array(['A1B C', '1BCA', 'BCA1'], dtype='<U5')
+
+    """
+    a_arr = np.asarray(a)
+    return _vec_string(a_arr, a_arr.dtype, 'upper')
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_unary_op_dispatcher)
+def lower(a):
+    """
+    Return an array with the elements converted to lowercase.
+
+    Call :meth:`str.lower` element-wise.
+
+    For 8-bit strings, this method is locale-dependent.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.lower
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array(['A1B C', '1BCA', 'BCA1']); c
+    array(['A1B C', '1BCA', 'BCA1'], dtype='<U5')
+    >>> np.strings.lower(c)
+    array(['a1b c', '1bca', 'bca1'], dtype='<U5')
+
+    """
+    a_arr = np.asarray(a)
+    return _vec_string(a_arr, a_arr.dtype, 'lower')
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_unary_op_dispatcher)
+def swapcase(a):
+    """
+    Return element-wise a copy of the string with
+    uppercase characters converted to lowercase and vice versa.
+
+    Calls :meth:`str.swapcase` element-wise.
+
+    For 8-bit strings, this method is locale-dependent.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.swapcase
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c=np.array(['a1B c','1b Ca','b Ca1','cA1b'],'S5'); c
+    array(['a1B c', '1b Ca', 'b Ca1', 'cA1b'],
+        dtype='|S5')
+    >>> np.strings.swapcase(c)
+    array(['A1b C', '1B cA', 'B cA1', 'Ca1B'],
+        dtype='|S5')
+
+    """
+    a_arr = np.asarray(a)
+    return _vec_string(a_arr, a_arr.dtype, 'swapcase')
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_unary_op_dispatcher)
+def capitalize(a):
+    """
+    Return a copy of ``a`` with only the first character of each element
+    capitalized.
+
+    Calls :meth:`str.capitalize` element-wise.
+
+    For byte strings, this method is locale-dependent.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array of strings to capitalize.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.capitalize
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c = np.array(['a1b2','1b2a','b2a1','2a1b'],'S4'); c
+    array(['a1b2', '1b2a', 'b2a1', '2a1b'],
+        dtype='|S4')
+    >>> np.strings.capitalize(c)
+    array(['A1b2', '1b2a', 'B2a1', '2a1b'],
+        dtype='|S4')
+
+    """
+    a_arr = np.asarray(a)
+    return _vec_string(a_arr, a_arr.dtype, 'capitalize')
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_unary_op_dispatcher)
+def title(a):
+    """
+    Return element-wise title cased version of string or unicode.
+
+    Title case words start with uppercase characters, all remaining cased
+    characters are lowercase.
+
+    Calls :meth:`str.title` element-wise.
+
+    For 8-bit strings, this method is locale-dependent.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.title
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> c=np.array(['a1b c','1b ca','b ca1','ca1b'],'S5'); c
+    array(['a1b c', '1b ca', 'b ca1', 'ca1b'],
+        dtype='|S5')
+    >>> np.strings.title(c)
+    array(['A1B C', '1B Ca', 'B Ca1', 'Ca1B'],
+        dtype='|S5')
+
+    """
+    a_arr = np.asarray(a)
+    return _vec_string(a_arr, a_arr.dtype, 'title')
+
+
+def _replace_dispatcher(a, old, new, count=None):
+    return (a,)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_replace_dispatcher)
+def replace(a, old, new, count=-1):
+    """
+    For each element in ``a``, return a copy of the string with
+    occurrences of substring ``old`` replaced by ``new``.
+
+    Parameters
+    ----------
+    a : array_like, with ``bytes_`` or ``str_`` dtype
+
+    old, new : array_like, with ``bytes_`` or ``str_`` dtype
+
+    count : array_like, with ``int_`` dtype
+        If the optional argument ``count`` is given, only the first
+        ``count`` occurrences are replaced.
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.replace
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(["That is a mango", "Monkeys eat mangos"])
+    >>> np.strings.replace(a, 'mango', 'banana')
+    array(['That is a banana', 'Monkeys eat bananas'], dtype='<U19')
+
+    >>> a = np.array(["The dish is fresh", "This is it"])
+    >>> np.strings.replace(a, 'is', 'was')
+    array(['The dwash was fresh', 'Thwas was it'], dtype='<U19')
+
+    """
+    count = np.asanyarray(count)
+    if not np.issubdtype(count.dtype, np.integer):
+        raise TypeError(f"unsupported type {count.dtype} for operand 'count'")
+
+    arr = np.asanyarray(a)
+    old_dtype = getattr(old, 'dtype', None)
+    old = np.asanyarray(old)
+    new_dtype = getattr(new, 'dtype', None)
+    new = np.asanyarray(new)
+
+    if np.result_type(arr, old, new).char == "T":
+        return _replace(arr, old, new, count)
+
+    a_dt = arr.dtype
+    old = old.astype(old_dtype or a_dt.char, copy=False)
+    new = new.astype(new_dtype or a_dt.char, copy=False)
+    max_int64 = np.iinfo(np.int64).max
+    counts = _count_ufunc(arr, old, 0, max_int64)
+    counts = np.where(count < 0, counts, np.minimum(counts, count))
+    buffersizes = str_len(arr) + counts * (str_len(new) - str_len(old))
+    out_dtype = f"{arr.dtype.char}{buffersizes.max()}"
+    out = np.empty_like(arr, shape=buffersizes.shape, dtype=out_dtype)
+
+    return _replace(arr, old, new, counts, out=out)
+
+
+def _join_dispatcher(sep, seq):
+    return (sep, seq)
+
+
+@array_function_dispatch(_join_dispatcher)
+def _join(sep, seq):
+    """
+    Return a string which is the concatenation of the strings in the
+    sequence `seq`.
+
+    Calls :meth:`str.join` element-wise.
+
+    Parameters
+    ----------
+    sep : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+    seq : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input types
+
+    See Also
+    --------
+    str.join
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> np.strings.join('-', 'osd')  # doctest: +SKIP
+    array('o-s-d', dtype='<U5')  # doctest: +SKIP
+
+    >>> np.strings.join(['-', '.'], ['ghc', 'osd'])  # doctest: +SKIP
+    array(['g-h-c', 'o.s.d'], dtype='<U5')  # doctest: +SKIP
+
+    """
+    return _to_bytes_or_str_array(
+        _vec_string(sep, np.object_, 'join', (seq,)), seq)
+
+
+def _split_dispatcher(a, sep=None, maxsplit=None):
+    return (a,)
+
+
+@array_function_dispatch(_split_dispatcher)
+def _split(a, sep=None, maxsplit=None):
+    """
+    For each element in `a`, return a list of the words in the
+    string, using `sep` as the delimiter string.
+
+    Calls :meth:`str.split` element-wise.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    sep : str or unicode, optional
+       If `sep` is not specified or None, any whitespace string is a
+       separator.
+
+    maxsplit : int, optional
+        If `maxsplit` is given, at most `maxsplit` splits are done.
+
+    Returns
+    -------
+    out : ndarray
+        Array of list objects
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.array("Numpy is nice!")
+    >>> np.strings.split(x, " ")  # doctest: +SKIP
+    array(list(['Numpy', 'is', 'nice!']), dtype=object)  # doctest: +SKIP
+
+    >>> np.strings.split(x, " ", 1)  # doctest: +SKIP
+    array(list(['Numpy', 'is nice!']), dtype=object)  # doctest: +SKIP
+
+    See Also
+    --------
+    str.split, rsplit
+
+    """
+    # This will return an array of lists of different sizes, so we
+    # leave it as an object array
+    return _vec_string(
+        a, np.object_, 'split', [sep] + _clean_args(maxsplit))
+
+
+@array_function_dispatch(_split_dispatcher)
+def _rsplit(a, sep=None, maxsplit=None):
+    """
+    For each element in `a`, return a list of the words in the
+    string, using `sep` as the delimiter string.
+
+    Calls :meth:`str.rsplit` element-wise.
+
+    Except for splitting from the right, `rsplit`
+    behaves like `split`.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    sep : str or unicode, optional
+        If `sep` is not specified or None, any whitespace string
+        is a separator.
+    maxsplit : int, optional
+        If `maxsplit` is given, at most `maxsplit` splits are done,
+        the rightmost ones.
+
+    Returns
+    -------
+    out : ndarray
+        Array of list objects
+
+    See Also
+    --------
+    str.rsplit, split
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(['aAaAaA', 'abBABba'])
+    >>> np.strings.rsplit(a, 'A')  # doctest: +SKIP
+    array([list(['a', 'a', 'a', '']),  # doctest: +SKIP
+           list(['abB', 'Bba'])], dtype=object)  # doctest: +SKIP
+
+    """
+    # This will return an array of lists of different sizes, so we
+    # leave it as an object array
+    return _vec_string(
+        a, np.object_, 'rsplit', [sep] + _clean_args(maxsplit))
+
+
+def _splitlines_dispatcher(a, keepends=None):
+    return (a,)
+
+
+@array_function_dispatch(_splitlines_dispatcher)
+def _splitlines(a, keepends=None):
+    """
+    For each element in `a`, return a list of the lines in the
+    element, breaking at line boundaries.
+
+    Calls :meth:`str.splitlines` element-wise.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+
+    keepends : bool, optional
+        Line breaks are not included in the resulting list unless
+        keepends is given and true.
+
+    Returns
+    -------
+    out : ndarray
+        Array of list objects
+
+    See Also
+    --------
+    str.splitlines
+
+    Examples
+    --------
+    >>> np.char.splitlines("first line\\nsecond line")
+    array(list(['first line', 'second line']), dtype=object)
+    >>> a = np.array(["first\\nsecond", "third\\nfourth"])
+    >>> np.char.splitlines(a)
+    array([list(['first', 'second']), list(['third', 'fourth'])], dtype=object)
+
+    """
+    return _vec_string(
+        a, np.object_, 'splitlines', _clean_args(keepends))
+
+
+def _partition_dispatcher(a, sep):
+    return (a,)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_partition_dispatcher)
+def partition(a, sep):
+    """
+    Partition each element in ``a`` around ``sep``.
+
+    For each element in ``a``, split the element at the first
+    occurrence of ``sep``, and return a 3-tuple containing the part
+    before the separator, the separator itself, and the part after
+    the separator. If the separator is not found, the first item of
+    the tuple will contain the whole string, and the second and third
+    ones will be the empty string.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array
+    sep : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Separator to split each string element in ``a``.
+
+    Returns
+    -------
+    out : 3-tuple:
+        - array with ``StringDType``, ``bytes_`` or ``str_`` dtype with the
+          part before the separator
+        - array with ``StringDType``, ``bytes_`` or ``str_`` dtype with the
+          separator
+        - array with ``StringDType``, ``bytes_`` or ``str_`` dtype with the
+          part after the separator
+
+    See Also
+    --------
+    str.partition
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.array(["Numpy is nice!"])
+    >>> np.strings.partition(x, " ")
+    (array(['Numpy'], dtype='<U5'),
+     array([' '], dtype='<U1'),
+     array(['is nice!'], dtype='<U8'))
+
+    """
+    a = np.asanyarray(a)
+    sep = np.asanyarray(sep)
+
+    if np.result_type(a, sep).char == "T":
+        return _partition(a, sep)
+
+    sep = sep.astype(a.dtype.char, copy=False)
+    pos = _find_ufunc(a, sep, 0, MAX)
+    a_len = str_len(a)
+    sep_len = str_len(sep)
+
+    not_found = pos < 0
+    buffersizes1 = np.where(not_found, a_len, pos)
+    buffersizes3 = np.where(not_found, 0, a_len - pos - sep_len)
+
+    out_dtype = ",".join([f"{a.dtype.char}{n}" for n in (
+        buffersizes1.max(),
+        1 if np.all(not_found) else sep_len.max(),
+        buffersizes3.max(),
+    )])
+    shape = np.broadcast_shapes(a.shape, sep.shape)
+    out = np.empty_like(a, shape=shape, dtype=out_dtype)
+    return _partition_index(a, sep, pos, out=(out["f0"], out["f1"], out["f2"]))
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_partition_dispatcher)
+def rpartition(a, sep):
+    """
+    Partition (split) each element around the right-most separator.
+
+    For each element in ``a``, split the element at the last
+    occurrence of ``sep``, and return a 3-tuple containing the part
+    before the separator, the separator itself, and the part after
+    the separator. If the separator is not found, the third item of
+    the tuple will contain the whole string, and the first and second
+    ones will be the empty string.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array
+    sep : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Separator to split each string element in ``a``.
+
+    Returns
+    -------
+    out : 3-tuple:
+        - array with ``StringDType``, ``bytes_`` or ``str_`` dtype with the
+          part before the separator
+        - array with ``StringDType``, ``bytes_`` or ``str_`` dtype with the
+          separator
+        - array with ``StringDType``, ``bytes_`` or ``str_`` dtype with the
+          part after the separator
+
+    See Also
+    --------
+    str.rpartition
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(['aAaAaA', '  aA  ', 'abBABba'])
+    >>> np.strings.rpartition(a, 'A')
+    (array(['aAaAa', '  a', 'abB'], dtype='<U5'),
+     array(['A', 'A', 'A'], dtype='<U1'),
+     array(['', '  ', 'Bba'], dtype='<U3'))
+
+    """
+    a = np.asanyarray(a)
+    sep = np.asanyarray(sep)
+
+    if np.result_type(a, sep).char == "T":
+        return _rpartition(a, sep)
+
+    sep = sep.astype(a.dtype.char, copy=False)
+    pos = _rfind_ufunc(a, sep, 0, MAX)
+    a_len = str_len(a)
+    sep_len = str_len(sep)
+
+    not_found = pos < 0
+    buffersizes1 = np.where(not_found, 0, pos)
+    buffersizes3 = np.where(not_found, a_len, a_len - pos - sep_len)
+
+    out_dtype = ",".join([f"{a.dtype.char}{n}" for n in (
+        buffersizes1.max(),
+        1 if np.all(not_found) else sep_len.max(),
+        buffersizes3.max(),
+    )])
+    shape = np.broadcast_shapes(a.shape, sep.shape)
+    out = np.empty_like(a, shape=shape, dtype=out_dtype)
+    return _rpartition_index(
+        a, sep, pos, out=(out["f0"], out["f1"], out["f2"]))
+
+
+def _translate_dispatcher(a, table, deletechars=None):
+    return (a,)
+
+
+@set_module("numpy.strings")
+@array_function_dispatch(_translate_dispatcher)
+def translate(a, table, deletechars=None):
+    """
+    For each element in `a`, return a copy of the string where all
+    characters occurring in the optional argument `deletechars` are
+    removed, and the remaining characters have been mapped through the
+    given translation table.
+
+    Calls :meth:`str.translate` element-wise.
+
+    Parameters
+    ----------
+    a : array-like, with ``bytes_`` or ``str_`` dtype
+
+    table : str of length 256
+
+    deletechars : str
+
+    Returns
+    -------
+    out : ndarray
+        Output array of str or unicode, depending on input type
+
+    See Also
+    --------
+    str.translate
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(['a1b c', '1bca', 'bca1'])
+    >>> table = a[0].maketrans('abc', '123')
+    >>> deletechars = ' '
+    >>> np.char.translate(a, table, deletechars)
+    array(['112 3', '1231', '2311'], dtype='<U5')
+
+    """
+    a_arr = np.asarray(a)
+    if issubclass(a_arr.dtype.type, np.str_):
+        return _vec_string(
+            a_arr, a_arr.dtype, 'translate', (table,))
+    else:
+        return _vec_string(
+            a_arr,
+            a_arr.dtype,
+            'translate',
+            [table] + _clean_args(deletechars)
+        )
+
+@set_module("numpy.strings")
+def slice(a, start=None, stop=np._NoValue, step=None, /):
+    """
+    Slice the strings in `a` by slices specified by `start`, `stop`, `step`.
+    Like in the regular Python `slice` object, if only `start` is
+    specified then it is interpreted as the `stop`.
+
+    Parameters
+    ----------
+    a : array-like, with ``StringDType``, ``bytes_``, or ``str_`` dtype
+        Input array
+
+    start : None, an integer or an array of integers
+        The start of the slice, broadcasted to `a`'s shape
+
+    stop : None, an integer or an array of integers
+        The end of the slice, broadcasted to `a`'s shape
+
+    step : None, an integer or an array of integers
+        The step for the slice, broadcasted to `a`'s shape
+
+    Returns
+    -------
+    out : ndarray
+        Output array of ``StringDType``, ``bytes_`` or ``str_`` dtype,
+        depending on input type
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> a = np.array(['hello', 'world'])
+    >>> np.strings.slice(a, 2)
+    array(['he', 'wo'], dtype='<U5')
+
+    >>> np.strings.slice(a, 2, None)
+    array(['llo', 'rld'], dtype='<U5')
+
+    >>> np.strings.slice(a, 1, 5, 2)
+    array(['el', 'ol'], dtype='<U5')
+
+    One can specify different start/stop/step for different array entries:
+
+    >>> np.strings.slice(a, np.array([1, 2]), np.array([4, 5]))
+    array(['ell', 'rld'], dtype='<U5')
+
+    Negative slices have the same meaning as in regular Python:
+
+    >>> b = np.array(['hello world', 'γεια σου κόσμε', '你好世界', '👋 🌍'],
+    ...              dtype=np.dtypes.StringDType())
+    >>> np.strings.slice(b, -2)
+    array(['hello wor', 'γεια σου κόσ', '你好', '👋'], dtype=StringDType())
+
+    >>> np.strings.slice(b, -2, None)
+    array(['ld', 'με', '世界', ' 🌍'], dtype=StringDType())
+
+    >>> np.strings.slice(b, [3, -10, 2, -3], [-1, -2, -1, 3])
+    array(['lo worl', ' σου κόσ', '世', '👋 🌍'], dtype=StringDType())
+
+    >>> np.strings.slice(b, None, None, -1)
+    array(['dlrow olleh', 'εμσόκ υοσ αιεγ', '界世好你', '🌍 👋'],
+          dtype=StringDType())
+
+    """
+    # Just like in the construction of a regular slice object, if only start
+    # is specified then start will become stop, see logic in slice_new.
+    if stop is np._NoValue:
+        stop = start
+        start = None
+
+    # adjust start, stop, step to be integers, see logic in PySlice_Unpack
+    if step is None:
+        step = 1
+    step = np.asanyarray(step)
+    if not np.issubdtype(step.dtype, np.integer):
+        raise TypeError(f"unsupported type {step.dtype} for operand 'step'")
+    if np.any(step == 0):
+        raise ValueError("slice step cannot be zero")
+
+    if start is None:
+        start = np.where(step < 0, np.iinfo(np.intp).max, 0)
+
+    if stop is None:
+        stop = np.where(step < 0, np.iinfo(np.intp).min, np.iinfo(np.intp).max)
+
+    return _slice(a, start, stop, step)

v12x/pylib/numpy/_core/tests/_locales.py

@@ -0,0 +1,72 @@
+"""Provide class for testing in French locale
+
+"""
+import locale
+import sys
+
+import pytest
+
+__ALL__ = ['CommaDecimalPointLocale']
+
+
+def find_comma_decimal_point_locale():
+    """See if platform has a decimal point as comma locale.
+
+    Find a locale that uses a comma instead of a period as the
+    decimal point.
+
+    Returns
+    -------
+    old_locale: str
+        Locale when the function was called.
+    new_locale: {str, None)
+        First French locale found, None if none found.
+
+    """
+    if sys.platform == 'win32':
+        locales = ['FRENCH']
+    else:
+        locales = ['fr_FR', 'fr_FR.UTF-8', 'fi_FI', 'fi_FI.UTF-8']
+
+    old_locale = locale.getlocale(locale.LC_NUMERIC)
+    new_locale = None
+    try:
+        for loc in locales:
+            try:
+                locale.setlocale(locale.LC_NUMERIC, loc)
+                new_locale = loc
+                break
+            except locale.Error:
+                pass
+    finally:
+        locale.setlocale(locale.LC_NUMERIC, locale=old_locale)
+    return old_locale, new_locale
+
+
+class CommaDecimalPointLocale:
+    """Sets LC_NUMERIC to a locale with comma as decimal point.
+
+    Classes derived from this class have setup and teardown methods that run
+    tests with locale.LC_NUMERIC set to a locale where commas (',') are used as
+    the decimal point instead of periods ('.'). On exit the locale is restored
+    to the initial locale. It also serves as context manager with the same
+    effect. If no such locale is available, the test is skipped.
+
+    """
+    (cur_locale, tst_locale) = find_comma_decimal_point_locale()
+
+    def setup_method(self):
+        if self.tst_locale is None:
+            pytest.skip("No French locale available")
+        locale.setlocale(locale.LC_NUMERIC, locale=self.tst_locale)
+
+    def teardown_method(self):
+        locale.setlocale(locale.LC_NUMERIC, locale=self.cur_locale)
+
+    def __enter__(self):
+        if self.tst_locale is None:
+            pytest.skip("No French locale available")
+        locale.setlocale(locale.LC_NUMERIC, locale=self.tst_locale)
+
+    def __exit__(self, type, value, traceback):
+        locale.setlocale(locale.LC_NUMERIC, locale=self.cur_locale)

v12x/pylib/numpy/_core/tests/_natype.py

@@ -0,0 +1,144 @@
+# Vendored implementation of pandas.NA, adapted from pandas/_libs/missing.pyx
+#
+# This is vendored to avoid adding pandas as a test dependency.
+
+__all__ = ["pd_NA"]
+
+import numbers
+
+import numpy as np
+
+
+def _create_binary_propagating_op(name, is_divmod=False):
+    is_cmp = name.strip("_") in ["eq", "ne", "le", "lt", "ge", "gt"]
+
+    def method(self, other):
+        if (
+            other is pd_NA
+            or isinstance(other, (str, bytes, numbers.Number, np.bool))
+            or (isinstance(other, np.ndarray) and not other.shape)
+        ):
+            # Need the other.shape clause to handle NumPy scalars,
+            # since we do a setitem on `out` below, which
+            # won't work for NumPy scalars.
+            if is_divmod:
+                return pd_NA, pd_NA
+            else:
+                return pd_NA
+
+        elif isinstance(other, np.ndarray):
+            out = np.empty(other.shape, dtype=object)
+            out[:] = pd_NA
+
+            if is_divmod:
+                return out, out.copy()
+            else:
+                return out
+
+        elif is_cmp and isinstance(other, (np.datetime64, np.timedelta64)):
+            return pd_NA
+
+        elif isinstance(other, np.datetime64):
+            if name in ["__sub__", "__rsub__"]:
+                return pd_NA
+
+        elif isinstance(other, np.timedelta64):
+            if name in ["__sub__", "__rsub__", "__add__", "__radd__"]:
+                return pd_NA
+
+        return NotImplemented
+
+    method.__name__ = name
+    return method
+
+
+def _create_unary_propagating_op(name: str):
+    def method(self):
+        return pd_NA
+
+    method.__name__ = name
+    return method
+
+
+class NAType:
+    def __repr__(self) -> str:
+        return "<NA>"
+
+    def __format__(self, format_spec) -> str:
+        try:
+            return self.__repr__().__format__(format_spec)
+        except ValueError:
+            return self.__repr__()
+
+    def __bool__(self):
+        raise TypeError("boolean value of NA is ambiguous")
+
+    def __hash__(self):
+        return 2**61 - 1
+
+    def __reduce__(self):
+        return "pd_NA"
+
+    # Binary arithmetic and comparison ops -> propagate
+
+    __add__ = _create_binary_propagating_op("__add__")
+    __radd__ = _create_binary_propagating_op("__radd__")
+    __sub__ = _create_binary_propagating_op("__sub__")
+    __rsub__ = _create_binary_propagating_op("__rsub__")
+    __mul__ = _create_binary_propagating_op("__mul__")
+    __rmul__ = _create_binary_propagating_op("__rmul__")
+    __matmul__ = _create_binary_propagating_op("__matmul__")
+    __rmatmul__ = _create_binary_propagating_op("__rmatmul__")
+    __truediv__ = _create_binary_propagating_op("__truediv__")
+    __rtruediv__ = _create_binary_propagating_op("__rtruediv__")
+    __floordiv__ = _create_binary_propagating_op("__floordiv__")
+    __rfloordiv__ = _create_binary_propagating_op("__rfloordiv__")
+    __mod__ = _create_binary_propagating_op("__mod__")
+    __rmod__ = _create_binary_propagating_op("__rmod__")
+    __divmod__ = _create_binary_propagating_op("__divmod__", is_divmod=True)
+    __rdivmod__ = _create_binary_propagating_op("__rdivmod__", is_divmod=True)
+    # __lshift__ and __rshift__ are not implemented
+
+    __eq__ = _create_binary_propagating_op("__eq__")
+    __ne__ = _create_binary_propagating_op("__ne__")
+    __le__ = _create_binary_propagating_op("__le__")
+    __lt__ = _create_binary_propagating_op("__lt__")
+    __gt__ = _create_binary_propagating_op("__gt__")
+    __ge__ = _create_binary_propagating_op("__ge__")
+
+    # Unary ops
+
+    __neg__ = _create_unary_propagating_op("__neg__")
+    __pos__ = _create_unary_propagating_op("__pos__")
+    __abs__ = _create_unary_propagating_op("__abs__")
+    __invert__ = _create_unary_propagating_op("__invert__")
+
+    # Logical ops using Kleene logic
+
+    def __and__(self, other):
+        if other is False:
+            return False
+        elif other is True or other is pd_NA:
+            return pd_NA
+        return NotImplemented
+
+    __rand__ = __and__
+
+    def __or__(self, other):
+        if other is True:
+            return True
+        elif other is False or other is pd_NA:
+            return pd_NA
+        return NotImplemented
+
+    __ror__ = __or__
+
+    def __xor__(self, other):
+        if other is False or other is True or other is pd_NA:
+            return pd_NA
+        return NotImplemented
+
+    __rxor__ = __xor__
+
+
+pd_NA = NAType()

v12x/pylib/numpy/_core/tests/examples/cython/setup.py

@@ -0,0 +1,39 @@
+"""
+Provide python-space access to the functions exposed in numpy/__init__.pxd
+for testing.
+"""
+
+import os
+
+import Cython
+from Cython.Build import cythonize
+from distutils.core import setup
+from setuptools.extension import Extension
+
+import numpy as np
+from numpy._utils import _pep440
+
+macros = [
+    ("NPY_NO_DEPRECATED_API", 0),
+    # Require 1.25+ to test datetime additions
+    ("NPY_TARGET_VERSION", "NPY_2_0_API_VERSION"),
+]
+
+checks = Extension(
+    "checks",
+    sources=[os.path.join('.', "checks.pyx")],
+    include_dirs=[np.get_include()],
+    define_macros=macros,
+)
+
+extensions = [checks]
+
+compiler_directives = {}
+if _pep440.parse(Cython.__version__) >= _pep440.parse("3.1.0a0"):
+    compiler_directives['freethreading_compatible'] = True
+
+setup(
+    ext_modules=cythonize(
+        extensions,
+        compiler_directives=compiler_directives)
+)

v12x/pylib/numpy/_core/tests/examples/limited_api/setup.py

@@ -0,0 +1,24 @@
+"""
+Build an example package using the limited Python C API.
+"""
+
+import os
+
+from setuptools import Extension, setup
+
+import numpy as np
+
+macros = [("NPY_NO_DEPRECATED_API", 0), ("Py_LIMITED_API", "0x03060000")]
+
+limited_api = Extension(
+    "limited_api",
+    sources=[os.path.join('.', "limited_api.c")],
+    include_dirs=[np.get_include()],
+    define_macros=macros,
+)
+
+extensions = [limited_api]
+
+setup(
+    ext_modules=extensions
+)

v12x/pylib/numpy/_core/tests/test__exceptions.py

@@ -0,0 +1,90 @@
+"""
+Tests of the ._exceptions module. Primarily for exercising the __str__ methods.
+"""
+
+import pickle
+
+import pytest
+
+import numpy as np
+from numpy.exceptions import AxisError
+
+_ArrayMemoryError = np._core._exceptions._ArrayMemoryError
+_UFuncNoLoopError = np._core._exceptions._UFuncNoLoopError
+
+class TestArrayMemoryError:
+    def test_pickling(self):
+        """ Test that _ArrayMemoryError can be pickled """
+        error = _ArrayMemoryError((1023,), np.dtype(np.uint8))
+        res = pickle.loads(pickle.dumps(error))
+        assert res._total_size == error._total_size
+
+    def test_str(self):
+        e = _ArrayMemoryError((1023,), np.dtype(np.uint8))
+        str(e)  # not crashing is enough
+
+    # testing these properties is easier than testing the full string repr
+    def test__size_to_string(self):
+        """ Test e._size_to_string """
+        f = _ArrayMemoryError._size_to_string
+        Ki = 1024
+        assert f(0) == '0 bytes'
+        assert f(1) == '1 bytes'
+        assert f(1023) == '1023 bytes'
+        assert f(Ki) == '1.00 KiB'
+        assert f(Ki + 1) == '1.00 KiB'
+        assert f(10 * Ki) == '10.0 KiB'
+        assert f(int(999.4 * Ki)) == '999. KiB'
+        assert f(int(1023.4 * Ki)) == '1023. KiB'
+        assert f(int(1023.5 * Ki)) == '1.00 MiB'
+        assert f(Ki * Ki) == '1.00 MiB'
+
+        # 1023.9999 Mib should round to 1 GiB
+        assert f(int(Ki * Ki * Ki * 0.9999)) == '1.00 GiB'
+        assert f(Ki * Ki * Ki * Ki * Ki * Ki) == '1.00 EiB'
+        # larger than sys.maxsize, adding larger prefixes isn't going to help
+        # anyway.
+        assert f(Ki * Ki * Ki * Ki * Ki * Ki * 123456) == '123456. EiB'
+
+    def test__total_size(self):
+        """ Test e._total_size """
+        e = _ArrayMemoryError((1,), np.dtype(np.uint8))
+        assert e._total_size == 1
+
+        e = _ArrayMemoryError((2, 4), np.dtype((np.uint64, 16)))
+        assert e._total_size == 1024
+
+
+class TestUFuncNoLoopError:
+    def test_pickling(self):
+        """ Test that _UFuncNoLoopError can be pickled """
+        assert isinstance(pickle.dumps(_UFuncNoLoopError), bytes)
+
+
+@pytest.mark.parametrize("args", [
+    (2, 1, None),
+    (2, 1, "test_prefix"),
+    ("test message",),
+])
+class TestAxisError:
+    def test_attr(self, args):
+        """Validate attribute types."""
+        exc = AxisError(*args)
+        if len(args) == 1:
+            assert exc.axis is None
+            assert exc.ndim is None
+        else:
+            axis, ndim, *_ = args
+            assert exc.axis == axis
+            assert exc.ndim == ndim
+
+    def test_pickling(self, args):
+        """Test that `AxisError` can be pickled."""
+        exc = AxisError(*args)
+        exc2 = pickle.loads(pickle.dumps(exc))
+
+        assert type(exc) is type(exc2)
+        for name in ("axis", "ndim", "args"):
+            attr1 = getattr(exc, name)
+            attr2 = getattr(exc2, name)
+            assert attr1 == attr2, name

v12x/pylib/numpy/_core/tests/test_abc.py

@@ -0,0 +1,54 @@
+import numbers
+
+import numpy as np
+from numpy._core.numerictypes import sctypes
+from numpy.testing import assert_
+
+
+class TestABC:
+    def test_abstract(self):
+        assert_(issubclass(np.number, numbers.Number))
+
+        assert_(issubclass(np.inexact, numbers.Complex))
+        assert_(issubclass(np.complexfloating, numbers.Complex))
+        assert_(issubclass(np.floating, numbers.Real))
+
+        assert_(issubclass(np.integer, numbers.Integral))
+        assert_(issubclass(np.signedinteger, numbers.Integral))
+        assert_(issubclass(np.unsignedinteger, numbers.Integral))
+
+    def test_floats(self):
+        for t in sctypes['float']:
+            assert_(isinstance(t(), numbers.Real),
+                    f"{t.__name__} is not instance of Real")
+            assert_(issubclass(t, numbers.Real),
+                    f"{t.__name__} is not subclass of Real")
+            assert_(not isinstance(t(), numbers.Rational),
+                    f"{t.__name__} is instance of Rational")
+            assert_(not issubclass(t, numbers.Rational),
+                    f"{t.__name__} is subclass of Rational")
+
+    def test_complex(self):
+        for t in sctypes['complex']:
+            assert_(isinstance(t(), numbers.Complex),
+                    f"{t.__name__} is not instance of Complex")
+            assert_(issubclass(t, numbers.Complex),
+                    f"{t.__name__} is not subclass of Complex")
+            assert_(not isinstance(t(), numbers.Real),
+                    f"{t.__name__} is instance of Real")
+            assert_(not issubclass(t, numbers.Real),
+                    f"{t.__name__} is subclass of Real")
+
+    def test_int(self):
+        for t in sctypes['int']:
+            assert_(isinstance(t(), numbers.Integral),
+                    f"{t.__name__} is not instance of Integral")
+            assert_(issubclass(t, numbers.Integral),
+                    f"{t.__name__} is not subclass of Integral")
+
+    def test_uint(self):
+        for t in sctypes['uint']:
+            assert_(isinstance(t(), numbers.Integral),
+                    f"{t.__name__} is not instance of Integral")
+            assert_(issubclass(t, numbers.Integral),
+                    f"{t.__name__} is not subclass of Integral")

v12x/pylib/numpy/_core/tests/test_api.py

@@ -0,0 +1,668 @@
+import sys
+
+import pytest
+
+import numpy as np
+import numpy._core.umath as ncu
+from numpy._core._rational_tests import rational, rational2
+from numpy.lib import stride_tricks
+from numpy.testing import (
+    HAS_REFCOUNT,
+    assert_,
+    assert_array_equal,
+    assert_equal,
+    assert_raises,
+)
+
+
+def test_array_array():
+    tobj = type(object)
+    ones11 = np.ones((1, 1), np.float64)
+    tndarray = type(ones11)
+    # Test is_ndarray
+    assert_equal(np.array(ones11, dtype=np.float64), ones11)
+    if HAS_REFCOUNT:
+        old_refcount = sys.getrefcount(tndarray)
+        np.array(ones11)
+        assert_equal(old_refcount, sys.getrefcount(tndarray))
+
+    # test None
+    assert_equal(np.array(None, dtype=np.float64),
+                 np.array(np.nan, dtype=np.float64))
+    if HAS_REFCOUNT:
+        old_refcount = sys.getrefcount(tobj)
+        np.array(None, dtype=np.float64)
+        assert_equal(old_refcount, sys.getrefcount(tobj))
+
+    # test scalar
+    assert_equal(np.array(1.0, dtype=np.float64),
+                 np.ones((), dtype=np.float64))
+    if HAS_REFCOUNT:
+        old_refcount = sys.getrefcount(np.float64)
+        np.array(np.array(1.0, dtype=np.float64), dtype=np.float64)
+        assert_equal(old_refcount, sys.getrefcount(np.float64))
+
+    # test string
+    S2 = np.dtype((bytes, 2))
+    S3 = np.dtype((bytes, 3))
+    S5 = np.dtype((bytes, 5))
+    assert_equal(np.array(b"1.0", dtype=np.float64),
+                 np.ones((), dtype=np.float64))
+    assert_equal(np.array(b"1.0").dtype, S3)
+    assert_equal(np.array(b"1.0", dtype=bytes).dtype, S3)
+    assert_equal(np.array(b"1.0", dtype=S2), np.array(b"1."))
+    assert_equal(np.array(b"1", dtype=S5), np.ones((), dtype=S5))
+
+    # test string
+    U2 = np.dtype((str, 2))
+    U3 = np.dtype((str, 3))
+    U5 = np.dtype((str, 5))
+    assert_equal(np.array("1.0", dtype=np.float64),
+                 np.ones((), dtype=np.float64))
+    assert_equal(np.array("1.0").dtype, U3)
+    assert_equal(np.array("1.0", dtype=str).dtype, U3)
+    assert_equal(np.array("1.0", dtype=U2), np.array("1."))
+    assert_equal(np.array("1", dtype=U5), np.ones((), dtype=U5))
+
+    builtins = getattr(__builtins__, '__dict__', __builtins__)
+    assert_(hasattr(builtins, 'get'))
+
+    # test memoryview
+    dat = np.array(memoryview(b'1.0'), dtype=np.float64)
+    assert_equal(dat, [49.0, 46.0, 48.0])
+    assert_(dat.dtype.type is np.float64)
+
+    dat = np.array(memoryview(b'1.0'))
+    assert_equal(dat, [49, 46, 48])
+    assert_(dat.dtype.type is np.uint8)
+
+    # test array interface
+    a = np.array(100.0, dtype=np.float64)
+    o = type("o", (object,),
+             {"__array_interface__": a.__array_interface__})
+    assert_equal(np.array(o, dtype=np.float64), a)
+
+    # test array_struct interface
+    a = np.array([(1, 4.0, 'Hello'), (2, 6.0, 'World')],
+                 dtype=[('f0', int), ('f1', float), ('f2', str)])
+    o = type("o", (object,),
+             {"__array_struct__": a.__array_struct__})
+    # wasn't what I expected... is np.array(o) supposed to equal a ?
+    # instead we get an array([...], dtype=">V18")
+    assert_equal(bytes(np.array(o).data), bytes(a.data))
+
+    # test __array__
+    def custom__array__(self, dtype=None, copy=None):
+        return np.array(100.0, dtype=dtype, copy=copy)
+
+    o = type("o", (object,), {"__array__": custom__array__})()
+    assert_equal(np.array(o, dtype=np.float64), np.array(100.0, np.float64))
+
+    # test recursion
+    nested = 1.5
+    for i in range(ncu.MAXDIMS):
+        nested = [nested]
+
+    # no error
+    np.array(nested)
+
+    # Exceeds recursion limit
+    assert_raises(ValueError, np.array, [nested], dtype=np.float64)
+
+    # Try with lists...
+    # float32
+    assert_equal(np.array([None] * 10, dtype=np.float32),
+                 np.full((10,), np.nan, dtype=np.float32))
+    assert_equal(np.array([[None]] * 10, dtype=np.float32),
+                 np.full((10, 1), np.nan, dtype=np.float32))
+    assert_equal(np.array([[None] * 10], dtype=np.float32),
+                 np.full((1, 10), np.nan, dtype=np.float32))
+    assert_equal(np.array([[None] * 10] * 10, dtype=np.float32),
+                 np.full((10, 10), np.nan, dtype=np.float32))
+    # float64
+    assert_equal(np.array([None] * 10, dtype=np.float64),
+                 np.full((10,), np.nan, dtype=np.float64))
+    assert_equal(np.array([[None]] * 10, dtype=np.float64),
+                 np.full((10, 1), np.nan, dtype=np.float64))
+    assert_equal(np.array([[None] * 10], dtype=np.float64),
+                 np.full((1, 10), np.nan, dtype=np.float64))
+    assert_equal(np.array([[None] * 10] * 10, dtype=np.float64),
+                 np.full((10, 10), np.nan, dtype=np.float64))
+
+    assert_equal(np.array([1.0] * 10, dtype=np.float64),
+                 np.ones((10,), dtype=np.float64))
+    assert_equal(np.array([[1.0]] * 10, dtype=np.float64),
+                 np.ones((10, 1), dtype=np.float64))
+    assert_equal(np.array([[1.0] * 10], dtype=np.float64),
+                 np.ones((1, 10), dtype=np.float64))
+    assert_equal(np.array([[1.0] * 10] * 10, dtype=np.float64),
+                 np.ones((10, 10), dtype=np.float64))
+
+    # Try with tuples
+    assert_equal(np.array((None,) * 10, dtype=np.float64),
+                 np.full((10,), np.nan, dtype=np.float64))
+    assert_equal(np.array([(None,)] * 10, dtype=np.float64),
+                 np.full((10, 1), np.nan, dtype=np.float64))
+    assert_equal(np.array([(None,) * 10], dtype=np.float64),
+                 np.full((1, 10), np.nan, dtype=np.float64))
+    assert_equal(np.array([(None,) * 10] * 10, dtype=np.float64),
+                 np.full((10, 10), np.nan, dtype=np.float64))
+
+    assert_equal(np.array((1.0,) * 10, dtype=np.float64),
+                 np.ones((10,), dtype=np.float64))
+    assert_equal(np.array([(1.0,)] * 10, dtype=np.float64),
+                 np.ones((10, 1), dtype=np.float64))
+    assert_equal(np.array([(1.0,) * 10], dtype=np.float64),
+                 np.ones((1, 10), dtype=np.float64))
+    assert_equal(np.array([(1.0,) * 10] * 10, dtype=np.float64),
+                 np.ones((10, 10), dtype=np.float64))
+
+
+@pytest.mark.skipif(not HAS_REFCOUNT, reason="Python lacks refcounts")
+def test___array___refcount():
+    class MyArray:
+        def __init__(self, dtype):
+            self.val = np.array(-1, dtype=dtype)
+
+        def __array__(self, dtype=None, copy=None):
+            return self.val.__array__(dtype=dtype, copy=copy)
+
+    # test all possible scenarios:
+    # dtype(none | same | different) x copy(true | false | none)
+    dt = np.dtype(np.int32)
+    old_refcount = sys.getrefcount(dt)
+    np.array(MyArray(dt))
+    assert_equal(old_refcount, sys.getrefcount(dt))
+    np.array(MyArray(dt), dtype=dt)
+    assert_equal(old_refcount, sys.getrefcount(dt))
+    np.array(MyArray(dt), copy=None)
+    assert_equal(old_refcount, sys.getrefcount(dt))
+    np.array(MyArray(dt), dtype=dt, copy=None)
+    assert_equal(old_refcount, sys.getrefcount(dt))
+    dt2 = np.dtype(np.int16)
+    old_refcount2 = sys.getrefcount(dt2)
+    np.array(MyArray(dt), dtype=dt2)
+    assert_equal(old_refcount2, sys.getrefcount(dt2))
+    np.array(MyArray(dt), dtype=dt2, copy=None)
+    assert_equal(old_refcount2, sys.getrefcount(dt2))
+    with pytest.raises(ValueError):
+        np.array(MyArray(dt), dtype=dt2, copy=False)
+    assert_equal(old_refcount2, sys.getrefcount(dt2))
+
+
+@pytest.mark.parametrize("rat_cls", [rational, rational2])
+@pytest.mark.parametrize("array", [True, False])
+def test_array_impossible_casts(array, rat_cls):
+    # All builtin types can be forcibly cast, at least theoretically,
+    # but user dtypes cannot necessarily.
+    rt = rat_cls(1, 2)
+    if array:
+        rt = np.array(rt)
+    with assert_raises(TypeError):
+        np.array(rt, dtype="M8")
+
+
+def test_array_astype():
+    a = np.arange(6, dtype='f4').reshape(2, 3)
+    # Default behavior: allows unsafe casts, keeps memory layout,
+    #                   always copies.
+    b = a.astype('i4')
+    assert_equal(a, b)
+    assert_equal(b.dtype, np.dtype('i4'))
+    assert_equal(a.strides, b.strides)
+    b = a.T.astype('i4')
+    assert_equal(a.T, b)
+    assert_equal(b.dtype, np.dtype('i4'))
+    assert_equal(a.T.strides, b.strides)
+    b = a.astype('f4')
+    assert_equal(a, b)
+    assert_(not (a is b))
+
+    # copy=False parameter skips a copy
+    b = a.astype('f4', copy=False)
+    assert_(a is b)
+
+    # order parameter allows overriding of the memory layout,
+    # forcing a copy if the layout is wrong
+    b = a.astype('f4', order='F', copy=False)
+    assert_equal(a, b)
+    assert_(not (a is b))
+    assert_(b.flags.f_contiguous)
+
+    b = a.astype('f4', order='C', copy=False)
+    assert_equal(a, b)
+    assert_(a is b)
+    assert_(b.flags.c_contiguous)
+
+    # casting parameter allows catching bad casts
+    b = a.astype('c8', casting='safe')
+    assert_equal(a, b)
+    assert_equal(b.dtype, np.dtype('c8'))
+
+    assert_raises(TypeError, a.astype, 'i4', casting='safe')
+
+    # subok=False passes through a non-subclassed array
+    b = a.astype('f4', subok=0, copy=False)
+    assert_(a is b)
+
+    class MyNDArray(np.ndarray):
+        pass
+
+    a = np.array([[0, 1, 2], [3, 4, 5]], dtype='f4').view(MyNDArray)
+
+    # subok=True passes through a subclass
+    b = a.astype('f4', subok=True, copy=False)
+    assert_(a is b)
+
+    # subok=True is default, and creates a subtype on a cast
+    b = a.astype('i4', copy=False)
+    assert_equal(a, b)
+    assert_equal(type(b), MyNDArray)
+
+    # subok=False never returns a subclass
+    b = a.astype('f4', subok=False, copy=False)
+    assert_equal(a, b)
+    assert_(not (a is b))
+    assert_(type(b) is not MyNDArray)
+
+    # Make sure converting from string object to fixed length string
+    # does not truncate.
+    a = np.array([b'a' * 100], dtype='O')
+    b = a.astype('S')
+    assert_equal(a, b)
+    assert_equal(b.dtype, np.dtype('S100'))
+    a = np.array(['a' * 100], dtype='O')
+    b = a.astype('U')
+    assert_equal(a, b)
+    assert_equal(b.dtype, np.dtype('U100'))
+
+    # Same test as above but for strings shorter than 64 characters
+    a = np.array([b'a' * 10], dtype='O')
+    b = a.astype('S')
+    assert_equal(a, b)
+    assert_equal(b.dtype, np.dtype('S10'))
+    a = np.array(['a' * 10], dtype='O')
+    b = a.astype('U')
+    assert_equal(a, b)
+    assert_equal(b.dtype, np.dtype('U10'))
+
+    a = np.array(123456789012345678901234567890, dtype='O').astype('S')
+    assert_array_equal(a, np.array(b'1234567890' * 3, dtype='S30'))
+    a = np.array(123456789012345678901234567890, dtype='O').astype('U')
+    assert_array_equal(a, np.array('1234567890' * 3, dtype='U30'))
+
+    a = np.array([123456789012345678901234567890], dtype='O').astype('S')
+    assert_array_equal(a, np.array(b'1234567890' * 3, dtype='S30'))
+    a = np.array([123456789012345678901234567890], dtype='O').astype('U')
+    assert_array_equal(a, np.array('1234567890' * 3, dtype='U30'))
+
+    a = np.array(123456789012345678901234567890, dtype='S')
+    assert_array_equal(a, np.array(b'1234567890' * 3, dtype='S30'))
+    a = np.array(123456789012345678901234567890, dtype='U')
+    assert_array_equal(a, np.array('1234567890' * 3, dtype='U30'))
+
+    a = np.array('a\u0140', dtype='U')
+    b = np.ndarray(buffer=a, dtype='uint32', shape=2)
+    assert_(b.size == 2)
+
+    a = np.array([1000], dtype='i4')
+    assert_raises(TypeError, a.astype, 'S1', casting='safe')
+
+    a = np.array(1000, dtype='i4')
+    assert_raises(TypeError, a.astype, 'U1', casting='safe')
+
+    # gh-24023
+    assert_raises(TypeError, a.astype)
+
+@pytest.mark.parametrize("dt", ["S", "U"])
+def test_array_astype_to_string_discovery_empty(dt):
+    # See also gh-19085
+    arr = np.array([""], dtype=object)
+    # Note, the itemsize is the `0 -> 1` logic, which should change.
+    # The important part the test is rather that it does not error.
+    assert arr.astype(dt).dtype.itemsize == np.dtype(f"{dt}1").itemsize
+
+    # check the same thing for `np.can_cast` (since it accepts arrays)
+    assert np.can_cast(arr, dt, casting="unsafe")
+    assert not np.can_cast(arr, dt, casting="same_kind")
+    # as well as for the object as a descriptor:
+    assert np.can_cast("O", dt, casting="unsafe")
+
+@pytest.mark.parametrize("dt", ["d", "f", "S13", "U32"])
+def test_array_astype_to_void(dt):
+    dt = np.dtype(dt)
+    arr = np.array([], dtype=dt)
+    assert arr.astype("V").dtype.itemsize == dt.itemsize
+
+def test_object_array_astype_to_void():
+    # This is different to `test_array_astype_to_void` as object arrays
+    # are inspected.  The default void is "V8" (8 is the length of double)
+    arr = np.array([], dtype="O").astype("V")
+    assert arr.dtype == "V8"
+
+@pytest.mark.parametrize("t",
+    np._core.sctypes['uint'] +
+    np._core.sctypes['int'] +
+    np._core.sctypes['float']
+)
+def test_array_astype_warning(t):
+    # test ComplexWarning when casting from complex to float or int
+    a = np.array(10, dtype=np.complex128)
+    pytest.warns(np.exceptions.ComplexWarning, a.astype, t)
+
+@pytest.mark.parametrize(["dtype", "out_dtype"],
+        [(np.bytes_, np.bool),
+         (np.str_, np.bool),
+         (np.dtype("S10,S9"), np.dtype("?,?")),
+         # The following also checks unaligned unicode access:
+         (np.dtype("S7,U9"), np.dtype("?,?"))])
+def test_string_to_boolean_cast(dtype, out_dtype):
+    # Only the last two (empty) strings are falsy (the `\0` is stripped):
+    arr = np.array(
+            ["10", "10\0\0\0", "0\0\0", "0", "False", " ", "", "\0"],
+            dtype=dtype)
+    expected = np.array(
+            [True, True, True, True, True, True, False, False],
+            dtype=out_dtype)
+    assert_array_equal(arr.astype(out_dtype), expected)
+    # As it's similar, check that nonzero behaves the same (structs are
+    # nonzero if all entries are)
+    assert_array_equal(np.nonzero(arr), np.nonzero(expected))
+
+@pytest.mark.parametrize("str_type", [str, bytes, np.str_])
+@pytest.mark.parametrize("scalar_type",
+        [np.complex64, np.complex128, np.clongdouble])
+def test_string_to_complex_cast(str_type, scalar_type):
+    value = scalar_type(b"1+3j")
+    assert scalar_type(value) == 1 + 3j
+    assert np.array([value], dtype=object).astype(scalar_type)[()] == 1 + 3j
+    assert np.array(value).astype(scalar_type)[()] == 1 + 3j
+    arr = np.zeros(1, dtype=scalar_type)
+    arr[0] = value
+    assert arr[0] == 1 + 3j
+
+@pytest.mark.parametrize("dtype", np.typecodes["AllFloat"])
+def test_none_to_nan_cast(dtype):
+    # Note that at the time of writing this test, the scalar constructors
+    # reject None
+    arr = np.zeros(1, dtype=dtype)
+    arr[0] = None
+    assert np.isnan(arr)[0]
+    assert np.isnan(np.array(None, dtype=dtype))[()]
+    assert np.isnan(np.array([None], dtype=dtype))[0]
+    assert np.isnan(np.array(None).astype(dtype))[()]
+
+def test_copyto_fromscalar():
+    a = np.arange(6, dtype='f4').reshape(2, 3)
+
+    # Simple copy
+    np.copyto(a, 1.5)
+    assert_equal(a, 1.5)
+    np.copyto(a.T, 2.5)
+    assert_equal(a, 2.5)
+
+    # Where-masked copy
+    mask = np.array([[0, 1, 0], [0, 0, 1]], dtype='?')
+    np.copyto(a, 3.5, where=mask)
+    assert_equal(a, [[2.5, 3.5, 2.5], [2.5, 2.5, 3.5]])
+    mask = np.array([[0, 1], [1, 1], [1, 0]], dtype='?')
+    np.copyto(a.T, 4.5, where=mask)
+    assert_equal(a, [[2.5, 4.5, 4.5], [4.5, 4.5, 3.5]])
+
+def test_copyto():
+    a = np.arange(6, dtype='i4').reshape(2, 3)
+
+    # Simple copy
+    np.copyto(a, [[3, 1, 5], [6, 2, 1]])
+    assert_equal(a, [[3, 1, 5], [6, 2, 1]])
+
+    # Overlapping copy should work
+    np.copyto(a[:, :2], a[::-1, 1::-1])
+    assert_equal(a, [[2, 6, 5], [1, 3, 1]])
+
+    # Defaults to 'same_kind' casting
+    assert_raises(TypeError, np.copyto, a, 1.5)
+
+    # Force a copy with 'unsafe' casting, truncating 1.5 to 1
+    np.copyto(a, 1.5, casting='unsafe')
+    assert_equal(a, 1)
+
+    # Copying with a mask
+    np.copyto(a, 3, where=[True, False, True])
+    assert_equal(a, [[3, 1, 3], [3, 1, 3]])
+
+    # Casting rule still applies with a mask
+    assert_raises(TypeError, np.copyto, a, 3.5, where=[True, False, True])
+
+    # Lists of integer 0's and 1's is ok too
+    np.copyto(a, 4.0, casting='unsafe', where=[[0, 1, 1], [1, 0, 0]])
+    assert_equal(a, [[3, 4, 4], [4, 1, 3]])
+
+    # Overlapping copy with mask should work
+    np.copyto(a[:, :2], a[::-1, 1::-1], where=[[0, 1], [1, 1]])
+    assert_equal(a, [[3, 4, 4], [4, 3, 3]])
+
+    # 'dst' must be an array
+    assert_raises(TypeError, np.copyto, [1, 2, 3], [2, 3, 4])
+
+
+def test_copyto_overlapping_where_false_no_leak():
+    # gh-31968: overlapping copyto with scalar where=False used to leak the
+    # overlap temp (missing Py_DECREF on the early-return path). No refcount
+    # assertion is made here; a leak sanitizer build is expected to catch
+    # the regression.
+    a = np.arange(36, dtype=object).reshape(6, 6)
+    original = a.copy()
+    np.copyto(a, a[::-1, :], where=False)
+    # where=False must write nothing
+    assert_array_equal(a, original)
+
+
+def test_copyto_cast_safety():
+    with pytest.raises(TypeError):
+        np.copyto(np.arange(3), 3., casting="safe")
+
+    # Can put integer and float scalars safely (and equiv):
+    np.copyto(np.arange(3), 3, casting="equiv")
+    np.copyto(np.arange(3.), 3., casting="equiv")
+    # And also with less precision safely:
+    np.copyto(np.arange(3, dtype="uint8"), 3, casting="safe")
+    np.copyto(np.arange(3., dtype="float32"), 3., casting="safe")
+
+    # But not equiv:
+    with pytest.raises(TypeError):
+        np.copyto(np.arange(3, dtype="uint8"), 3, casting="equiv")
+
+    with pytest.raises(TypeError):
+        np.copyto(np.arange(3., dtype="float32"), 3., casting="equiv")
+
+    # As a special thing, object is equiv currently:
+    np.copyto(np.arange(3, dtype=object), 3, casting="equiv")
+
+    # The following raises an overflow error/gives a warning but not
+    # type error (due to casting), though:
+    with pytest.raises(OverflowError):
+        np.copyto(np.arange(3), 2**80, casting="safe")
+
+    with pytest.warns(RuntimeWarning):
+        np.copyto(np.arange(3, dtype=np.float32), 2e300, casting="safe")
+
+
+def test_copyto_permute():
+    # test explicit overflow case
+    pad = 500
+    l = [True] * pad + [True, True, True, True]
+    r = np.zeros(len(l) - pad)
+    d = np.ones(len(l) - pad)
+    mask = np.array(l)[pad:]
+    np.copyto(r, d, where=mask[::-1])
+
+    # test all permutation of possible masks, 9 should be sufficient for
+    # current 4 byte unrolled code
+    power = 9
+    d = np.ones(power)
+    for i in range(2**power):
+        r = np.zeros(power)
+        l = [(i & x) != 0 for x in range(power)]
+        mask = np.array(l)
+        np.copyto(r, d, where=mask)
+        assert_array_equal(r == 1, l)
+        assert_equal(r.sum(), sum(l))
+
+        r = np.zeros(power)
+        np.copyto(r, d, where=mask[::-1])
+        assert_array_equal(r == 1, l[::-1])
+        assert_equal(r.sum(), sum(l))
+
+        r = np.zeros(power)
+        np.copyto(r[::2], d[::2], where=mask[::2])
+        assert_array_equal(r[::2] == 1, l[::2])
+        assert_equal(r[::2].sum(), sum(l[::2]))
+
+        r = np.zeros(power)
+        np.copyto(r[::2], d[::2], where=mask[::-2])
+        assert_array_equal(r[::2] == 1, l[::-2])
+        assert_equal(r[::2].sum(), sum(l[::-2]))
+
+        for c in [0xFF, 0x7F, 0x02, 0x10]:
+            r = np.zeros(power)
+            mask = np.array(l)
+            imask = np.array(l).view(np.uint8)
+            imask[mask != 0] = c
+            np.copyto(r, d, where=mask)
+            assert_array_equal(r == 1, l)
+            assert_equal(r.sum(), sum(l))
+
+    r = np.zeros(power)
+    np.copyto(r, d, where=True)
+    assert_equal(r.sum(), r.size)
+    r = np.ones(power)
+    d = np.zeros(power)
+    np.copyto(r, d, where=False)
+    assert_equal(r.sum(), r.size)
+
+def test_copy_order():
+    a = np.arange(24).reshape(2, 1, 3, 4)
+    b = a.copy(order='F')
+    c = np.arange(24).reshape(2, 1, 4, 3).swapaxes(2, 3)
+
+    def check_copy_result(x, y, ccontig, fcontig, strides=False):
+        assert_(not (x is y))
+        assert_equal(x, y)
+        assert_equal(res.flags.c_contiguous, ccontig)
+        assert_equal(res.flags.f_contiguous, fcontig)
+
+    # Validate the initial state of a, b, and c
+    assert_(a.flags.c_contiguous)
+    assert_(not a.flags.f_contiguous)
+    assert_(not b.flags.c_contiguous)
+    assert_(b.flags.f_contiguous)
+    assert_(not c.flags.c_contiguous)
+    assert_(not c.flags.f_contiguous)
+
+    # Copy with order='C'
+    res = a.copy(order='C')
+    check_copy_result(res, a, ccontig=True, fcontig=False, strides=True)
+    res = b.copy(order='C')
+    check_copy_result(res, b, ccontig=True, fcontig=False, strides=False)
+    res = c.copy(order='C')
+    check_copy_result(res, c, ccontig=True, fcontig=False, strides=False)
+    res = np.copy(a, order='C')
+    check_copy_result(res, a, ccontig=True, fcontig=False, strides=True)
+    res = np.copy(b, order='C')
+    check_copy_result(res, b, ccontig=True, fcontig=False, strides=False)
+    res = np.copy(c, order='C')
+    check_copy_result(res, c, ccontig=True, fcontig=False, strides=False)
+
+    # Copy with order='F'
+    res = a.copy(order='F')
+    check_copy_result(res, a, ccontig=False, fcontig=True, strides=False)
+    res = b.copy(order='F')
+    check_copy_result(res, b, ccontig=False, fcontig=True, strides=True)
+    res = c.copy(order='F')
+    check_copy_result(res, c, ccontig=False, fcontig=True, strides=False)
+    res = np.copy(a, order='F')
+    check_copy_result(res, a, ccontig=False, fcontig=True, strides=False)
+    res = np.copy(b, order='F')
+    check_copy_result(res, b, ccontig=False, fcontig=True, strides=True)
+    res = np.copy(c, order='F')
+    check_copy_result(res, c, ccontig=False, fcontig=True, strides=False)
+
+    # Copy with order='K'
+    res = a.copy(order='K')
+    check_copy_result(res, a, ccontig=True, fcontig=False, strides=True)
+    res = b.copy(order='K')
+    check_copy_result(res, b, ccontig=False, fcontig=True, strides=True)
+    res = c.copy(order='K')
+    check_copy_result(res, c, ccontig=False, fcontig=False, strides=True)
+    res = np.copy(a, order='K')
+    check_copy_result(res, a, ccontig=True, fcontig=False, strides=True)
+    res = np.copy(b, order='K')
+    check_copy_result(res, b, ccontig=False, fcontig=True, strides=True)
+    res = np.copy(c, order='K')
+    check_copy_result(res, c, ccontig=False, fcontig=False, strides=True)
+
+def test_contiguous_flags():
+    a = np.ones((4, 4, 1))[::2, :, :]
+    a = stride_tricks.as_strided(a, strides=a.strides[:2] + (-123,))
+    b = np.ones((2, 2, 1, 2, 2)).swapaxes(3, 4)
+
+    def check_contig(a, ccontig, fcontig):
+        assert_(a.flags.c_contiguous == ccontig)
+        assert_(a.flags.f_contiguous == fcontig)
+
+    # Check if new arrays are correct:
+    check_contig(a, False, False)
+    check_contig(b, False, False)
+    check_contig(np.empty((2, 2, 0, 2, 2)), True, True)
+    check_contig(np.array([[[1], [2]]], order='F'), True, True)
+    check_contig(np.empty((2, 2)), True, False)
+    check_contig(np.empty((2, 2), order='F'), False, True)
+
+    # Check that np.array creates correct contiguous flags:
+    check_contig(np.array(a, copy=None), False, False)
+    check_contig(np.array(a, copy=None, order='C'), True, False)
+    check_contig(np.array(a, ndmin=4, copy=None, order='F'), False, True)
+
+    # Check slicing update of flags and :
+    check_contig(a[0], True, True)
+    check_contig(a[None, ::4, ..., None], True, True)
+    check_contig(b[0, 0, ...], False, True)
+    check_contig(b[:, :, 0:0, :, :], True, True)
+
+    # Test ravel and squeeze.
+    check_contig(a.ravel(), True, True)
+    check_contig(np.ones((1, 3, 1)).squeeze(), True, True)
+
+def test_broadcast_arrays():
+    # Test user defined dtypes
+    dtype = 'u4,u4,u4'
+    a = np.array([(1, 2, 3)], dtype=dtype)
+    b = np.array([(1, 2, 3), (4, 5, 6), (7, 8, 9)], dtype=dtype)
+    result = np.broadcast_arrays(a, b)
+    assert_equal(result[0], np.array([(1, 2, 3), (1, 2, 3), (1, 2, 3)], dtype=dtype))
+    assert_equal(result[1], np.array([(1, 2, 3), (4, 5, 6), (7, 8, 9)], dtype=dtype))
+
+@pytest.mark.parametrize(["shape", "fill_value", "expected_output"],
+        [((2, 2), [5.0,  6.0], np.array([[5.0, 6.0], [5.0, 6.0]])),
+         ((3, 2), [1.0,  2.0], np.array([[1.0, 2.0], [1.0, 2.0], [1.0,  2.0]]))])
+def test_full_from_list(shape, fill_value, expected_output):
+    output = np.full(shape, fill_value)
+    assert_equal(output, expected_output)
+
+def test_astype_copyflag():
+    # test the various copyflag options
+    arr = np.arange(10, dtype=np.intp)
+
+    res_true = arr.astype(np.intp, copy=True)
+    assert not np.shares_memory(arr, res_true)
+
+    res_false = arr.astype(np.intp, copy=False)
+    assert np.shares_memory(arr, res_false)
+
+    res_false_float = arr.astype(np.float64, copy=False)
+    assert not np.shares_memory(arr, res_false_float)
+
+    # _CopyMode enum isn't allowed
+    assert_raises(ValueError, arr.astype, np.float64,
+                  copy=np._CopyMode.NEVER)

v12x/pylib/numpy/_core/tests/test_argparse.py

@@ -0,0 +1,90 @@
+"""
+Tests for the private NumPy argument parsing functionality.
+They mainly exists to ensure good test coverage without having to try the
+weirder cases on actual numpy functions but test them in one place.
+
+The test function is defined in C to be equivalent to (errors may not always
+match exactly, and could be adjusted):
+
+    def func(arg1, /, arg2, *, arg3):
+        i = integer(arg1)  # reproducing the 'i' parsing in Python.
+        return None
+"""
+
+import threading
+
+import pytest
+
+import numpy as np
+from numpy._core._multiarray_tests import (
+    argparse_example_function as func,
+    threaded_argparse_example_function as thread_func,
+)
+from numpy.testing import IS_WASM
+
+
+@pytest.mark.skipif(IS_WASM, reason="wasm doesn't have support for threads")
+def test_thread_safe_argparse_cache():
+    b = threading.Barrier(8)
+
+    def call_thread_func():
+        b.wait()
+        thread_func(arg1=3, arg2=None)
+
+    tasks = [threading.Thread(target=call_thread_func) for _ in range(8)]
+    [t.start() for t in tasks]
+    [t.join() for t in tasks]
+
+
+def test_invalid_integers():
+    with pytest.raises(TypeError,
+            match="integer argument expected, got float"):
+        func(1.)
+    with pytest.raises(OverflowError):
+        func(2**100)
+
+
+def test_missing_arguments():
+    with pytest.raises(TypeError,
+            match="missing required positional argument 0"):
+        func()
+    with pytest.raises(TypeError,
+            match="missing required positional argument 0"):
+        func(arg2=1, arg3=4)
+    with pytest.raises(TypeError,
+            match=r"missing required argument \'arg2\' \(pos 1\)"):
+        func(1, arg3=5)
+
+
+def test_too_many_positional():
+    # the second argument is positional but can be passed as keyword.
+    with pytest.raises(TypeError,
+            match="takes from 2 to 3 positional arguments but 4 were given"):
+        func(1, 2, 3, 4)
+
+
+def test_multiple_values():
+    with pytest.raises(TypeError,
+            match=r"given by name \('arg2'\) and position \(position 1\)"):
+        func(1, 2, arg2=3)
+
+
+def test_string_fallbacks():
+    # We can (currently?) use numpy strings to test the "slow" fallbacks
+    # that should normally not be taken due to string interning.
+    arg2 = np.str_("arg2")
+    missing_arg = np.str_("missing_arg")
+    func(1, **{arg2: 3})
+    with pytest.raises(TypeError,
+            match="got an unexpected keyword argument 'missing_arg'"):
+        func(2, **{missing_arg: 3})
+
+
+def test_too_many_arguments_method_forwarding():
+    # Not directly related to the standard argument parsing, but we sometimes
+    # forward methods to Python: arr.mean() calls np._core._methods._mean()
+    # This adds code coverage for this `npy_forward_method`.
+    arr = np.arange(3)
+    args = range(1000)
+    with pytest.raises(TypeError):
+        arr.mean(*args)

v12x/pylib/numpy/_core/tests/test_array_api_info.py

@@ -0,0 +1,113 @@
+import pytest
+
+import numpy as np
+
+info = np.__array_namespace_info__()
+
+
+def test_capabilities():
+    caps = info.capabilities()
+    assert caps["boolean indexing"] is True
+    assert caps["data-dependent shapes"] is True
+
+    # This will be added in the 2024.12 release of the array API standard.
+
+    # assert caps["max rank"] == 64
+    # np.zeros((1,)*64)
+    # with pytest.raises(ValueError):
+    #     np.zeros((1,)*65)
+
+
+def test_default_device():
+    assert info.default_device() == "cpu" == np.asarray(0).device
+
+
+def test_default_dtypes():
+    dtypes = info.default_dtypes()
+    assert dtypes["real floating"] == np.float64 == np.asarray(0.0).dtype
+    assert dtypes["complex floating"] == np.complex128 == \
+        np.asarray(0.0j).dtype
+    assert dtypes["integral"] == np.intp == np.asarray(0).dtype
+    assert dtypes["indexing"] == np.intp == np.argmax(np.zeros(10)).dtype
+
+    with pytest.raises(ValueError, match="Device not understood"):
+        info.default_dtypes(device="gpu")
+
+
+def test_dtypes_all():
+    dtypes = info.dtypes()
+    assert dtypes == {
+        "bool": np.bool_,
+        "int8": np.int8,
+        "int16": np.int16,
+        "int32": np.int32,
+        "int64": np.int64,
+        "uint8": np.uint8,
+        "uint16": np.uint16,
+        "uint32": np.uint32,
+        "uint64": np.uint64,
+        "float32": np.float32,
+        "float64": np.float64,
+        "complex64": np.complex64,
+        "complex128": np.complex128,
+    }
+
+
+dtype_categories = {
+    "bool": {"bool": np.bool_},
+    "signed integer": {
+        "int8": np.int8,
+        "int16": np.int16,
+        "int32": np.int32,
+        "int64": np.int64,
+    },
+    "unsigned integer": {
+        "uint8": np.uint8,
+        "uint16": np.uint16,
+        "uint32": np.uint32,
+        "uint64": np.uint64,
+    },
+    "integral": ("signed integer", "unsigned integer"),
+    "real floating": {"float32": np.float32, "float64": np.float64},
+    "complex floating": {"complex64": np.complex64, "complex128":
+                         np.complex128},
+    "numeric": ("integral", "real floating", "complex floating"),
+}
+
+
+@pytest.mark.parametrize("kind", dtype_categories)
+def test_dtypes_kind(kind):
+    expected = dtype_categories[kind]
+    if isinstance(expected, tuple):
+        assert info.dtypes(kind=kind) == info.dtypes(kind=expected)
+    else:
+        assert info.dtypes(kind=kind) == expected
+
+
+def test_dtypes_tuple():
+    dtypes = info.dtypes(kind=("bool", "integral"))
+    assert dtypes == {
+        "bool": np.bool_,
+        "int8": np.int8,
+        "int16": np.int16,
+        "int32": np.int32,
+        "int64": np.int64,
+        "uint8": np.uint8,
+        "uint16": np.uint16,
+        "uint32": np.uint32,
+        "uint64": np.uint64,
+    }
+
+
+def test_dtypes_invalid_kind():
+    with pytest.raises(ValueError, match="unsupported kind"):
+        info.dtypes(kind="invalid")
+
+
+def test_dtypes_invalid_device():
+    with pytest.raises(ValueError, match="Device not understood"):
+        info.dtypes(device="gpu")
+
+
+def test_devices():
+    assert info.devices() == ("cpu",)

v12x/pylib/numpy/_core/tests/test_array_coercion.py

@@ -0,0 +1,943 @@
+"""
+Tests for array coercion, mainly through testing `np.array` results directly.
+Note that other such tests exist, e.g., in `test_api.py` and many corner-cases
+are tested (sometimes indirectly) elsewhere.
+"""
+
+from itertools import permutations, product
+
+import pytest
+from pytest import param
+
+import numpy as np
+import numpy._core._multiarray_umath as ncu
+from numpy._core._rational_tests import rational, rational2
+from numpy.testing import IS_64BIT, assert_array_equal
+
+
+def arraylikes():
+    """Test parameters for functions converting an array into various array-likes."""
+
+    params = []
+
+    # base array:
+    def ndarray(a):
+        return a
+
+    params.append(param(ndarray, id="ndarray"))
+
+    # subclass:
+    class MyArr(np.ndarray):
+        pass
+
+    def subclass(a):
+        return a.view(MyArr)
+
+    params.append(subclass)
+
+    class _SequenceLike:
+        # Older NumPy versions, sometimes cared whether a protocol array was
+        # also _SequenceLike.  This shouldn't matter, but keep it for now
+        # for __array__ and not the others.
+        def __len__(self):
+            raise TypeError
+
+        def __getitem__(self, _, /):
+            raise TypeError
+
+    # Array-interface
+    class ArrayDunder(_SequenceLike):
+        def __init__(self, a):
+            self.a = a
+
+        def __array__(self, dtype=None, copy=None):
+            if dtype is None:
+                return self.a
+            return self.a.astype(dtype)
+
+    params.append(param(ArrayDunder, id="__array__"))
+
+    # memory-view
+    params.append(param(memoryview, id="memoryview"))
+
+    # Array-interface
+    class ArrayInterface:
+        def __init__(self, a):
+            self.a = a  # need to hold on to keep interface valid
+            self.__array_interface__ = a.__array_interface__
+
+    params.append(param(ArrayInterface, id="__array_interface__"))
+
+    # Array-Struct
+    class ArrayStruct:
+        def __init__(self, a):
+            self.a = a  # need to hold on to keep struct valid
+            self.__array_struct__ = a.__array_struct__
+
+    params.append(param(ArrayStruct, id="__array_struct__"))
+
+    return params
+
+
+def scalar_instances(times=True, extended_precision=True, user_dtype=True):
+    # Hard-coded list of scalar instances.
+    # Floats:
+    yield param(np.sqrt(np.float16(5)), id="float16")
+    yield param(np.sqrt(np.float32(5)), id="float32")
+    yield param(np.sqrt(np.float64(5)), id="float64")
+    if extended_precision:
+        yield param(np.sqrt(np.longdouble(5)), id="longdouble")
+
+    # Complex:
+    yield param(np.sqrt(np.complex64(2 + 3j)), id="complex64")
+    yield param(np.sqrt(np.complex128(2 + 3j)), id="complex128")
+    if extended_precision:
+        yield param(np.sqrt(np.clongdouble(2 + 3j)), id="clongdouble")
+
+    # Bool:
+    yield param(np.bool(0), id="bool")
+
+    # Integers:
+    yield param(np.int8(2), id="int8")
+    yield param(np.int16(2), id="int16")
+    yield param(np.int32(2), id="int32")
+    yield param(np.int64(2), id="int64")
+
+    yield param(np.uint8(2), id="uint8")
+    yield param(np.uint16(2), id="uint16")
+    yield param(np.uint32(2), id="uint32")
+    yield param(np.uint64(2), id="uint64")
+
+    # Rational:
+    if user_dtype:
+        yield param(rational(1, 2), id="rational")
+        yield param(rational2(1, 2), id="rational2")
+
+    # Cannot create a structured void scalar directly:
+    structured = np.array([(1, 3)], "i,i")[0]
+    assert isinstance(structured, np.void)
+    assert structured.dtype == np.dtype("i,i")
+    yield param(structured, id="structured")
+
+    if times:
+        # Datetimes and timedelta
+        yield param(np.timedelta64(2, "ns"), id="timedelta64[ns]")
+        yield param(np.timedelta64(23, "s"), id="timedelta64[s]")
+        yield param(np.timedelta64("NaT", "s"), id="timedelta64[s](NaT)")
+
+        yield param(np.datetime64("NaT", "D"), id="datetime64[D](NaT)")
+        yield param(np.datetime64("2020-06-07 12:43", "ms"), id="datetime64[ms]")
+
+    # Strings and unstructured void:
+    yield param(np.bytes_(b"1234"), id="bytes")
+    yield param(np.str_("2345"), id="unicode")
+    yield param(np.void(b"4321"), id="unstructured_void")
+
+
+def is_parametric_dtype(dtype):
+    """Returns True if the dtype is a parametric legacy dtype (itemsize
+    is 0, or a datetime without units)
+    """
+    if dtype.itemsize == 0:
+        return True
+    if issubclass(dtype.type, (np.datetime64, np.timedelta64)):
+        if dtype.name.endswith("64"):
+            # Generic time units
+            return True
+    return False
+
+
+class TestStringDiscovery:
+    @pytest.mark.parametrize("obj",
+            [object(), 1.2, 10**43, None, "string"],
+            ids=["object", "1.2", "10**43", "None", "string"])
+    def test_basic_stringlength(self, obj):
+        length = len(str(obj))
+        expected = np.dtype(f"S{length}")
+
+        assert np.array(obj, dtype="S").dtype == expected
+        assert np.array([obj], dtype="S").dtype == expected
+
+        # A nested array is also discovered correctly
+        arr = np.array(obj, dtype="O")
+        assert np.array(arr, dtype="S").dtype == expected
+        # Also if we use the dtype class
+        assert np.array(arr, dtype=type(expected)).dtype == expected
+        # Check that .astype() behaves identical
+        assert arr.astype("S").dtype == expected
+        # The DType class is accepted by `.astype()`
+        assert arr.astype(type(np.dtype("S"))).dtype == expected
+
+    @pytest.mark.parametrize("obj",
+            [object(), 1.2, 10**43, None, "string"],
+            ids=["object", "1.2", "10**43", "None", "string"])
+    def test_nested_arrays_stringlength(self, obj):
+        length = len(str(obj))
+        expected = np.dtype(f"S{length}")
+        arr = np.array(obj, dtype="O")
+        assert np.array([arr, arr], dtype="S").dtype == expected
+
+    @pytest.mark.parametrize("arraylike", arraylikes())
+    def test_unpack_first_level(self, arraylike):
+        # We unpack exactly one level of array likes
+        obj = np.array([None])
+        obj[0] = np.array(1.2)
+        # the length of the included item, not of the float dtype
+        length = len(str(obj[0]))
+        expected = np.dtype(f"S{length}")
+
+        obj = arraylike(obj)
+        # casting to string usually calls str(obj)
+        arr = np.array([obj], dtype="S")
+        assert arr.shape == (1, 1)
+        assert arr.dtype == expected
+
+
+class TestScalarDiscovery:
+    def test_void_special_case(self):
+        # Void dtypes with structures discover tuples as elements
+        arr = np.array((1, 2, 3), dtype="i,i,i")
+        assert arr.shape == ()
+        arr = np.array([(1, 2, 3)], dtype="i,i,i")
+        assert arr.shape == (1,)
+
+    def test_char_special_case(self):
+        arr = np.array("string", dtype="c")
+        assert arr.shape == (6,)
+        assert arr.dtype.char == "c"
+        arr = np.array(["string"], dtype="c")
+        assert arr.shape == (1, 6)
+        assert arr.dtype.char == "c"
+
+    def test_char_special_case_deep(self):
+        # Check that the character special case errors correctly if the
+        # array is too deep:
+        nested = ["string"]  # 2 dimensions (due to string being sequence)
+        for i in range(ncu.MAXDIMS - 2):
+            nested = [nested]
+
+        arr = np.array(nested, dtype='c')
+        assert arr.shape == (1,) * (ncu.MAXDIMS - 1) + (6,)
+        with pytest.raises(ValueError):
+            np.array([nested], dtype="c")
+
+    def test_unknown_object(self):
+        arr = np.array(object())
+        assert arr.shape == ()
+        assert arr.dtype == np.dtype("O")
+
+    @pytest.mark.parametrize("scalar", list(scalar_instances()))
+    def test_scalar(self, scalar):
+        arr = np.array(scalar)
+        assert arr.shape == ()
+        assert arr.dtype == scalar.dtype
+
+        arr = np.array([[scalar, scalar]])
+        assert arr.shape == (1, 2)
+        assert arr.dtype == scalar.dtype
+
+    # Additionally to string this test also runs into a corner case
+    # with datetime promotion (the difference is the promotion order).
+    @pytest.mark.filterwarnings("ignore:Promotion of numbers:FutureWarning")
+    def test_scalar_promotion(self):
+        for sc1, sc2 in product(scalar_instances(), scalar_instances()):
+            sc1, sc2 = sc1.values[0], sc2.values[0]
+            # test all combinations:
+            try:
+                arr = np.array([sc1, sc2])
+            except (TypeError, ValueError):
+                # The promotion between two times can fail
+                # XFAIL (ValueError): Some object casts are currently undefined
+                continue
+            assert arr.shape == (2,)
+            try:
+                dt1, dt2 = sc1.dtype, sc2.dtype
+                expected_dtype = np.promote_types(dt1, dt2)
+                assert arr.dtype == expected_dtype
+            except TypeError as e:
+                # Will currently always go to object dtype
+                assert arr.dtype == np.dtype("O")
+
+    @pytest.mark.parametrize("scalar", list(scalar_instances()))
+    def test_scalar_coercion(self, scalar):
+        # This tests various scalar coercion paths, mainly for the numerical
+        # types. It includes some paths not directly related to `np.array`.
+        if isinstance(scalar, np.inexact):
+            # Ensure we have a full-precision number if available
+            scalar = type(scalar)((scalar * 2)**0.5)
+
+        # Use casting from object:
+        arr = np.array(scalar, dtype=object).astype(scalar.dtype)
+
+        # Test various ways to create an array containing this scalar:
+        arr1 = np.array(scalar).reshape(1)
+        arr2 = np.array([scalar])
+        arr3 = np.empty(1, dtype=scalar.dtype)
+        arr3[0] = scalar
+        arr4 = np.empty(1, dtype=scalar.dtype)
+        arr4[:] = [scalar]
+        # All of these methods should yield the same results
+        assert_array_equal(arr, arr1)
+        assert_array_equal(arr, arr2)
+        assert_array_equal(arr, arr3)
+        assert_array_equal(arr, arr4)
+
+    @pytest.mark.filterwarnings("ignore::numpy.exceptions.ComplexWarning")
+    @pytest.mark.parametrize("cast_to", list(scalar_instances()))
+    def test_scalar_coercion_same_as_cast_and_assignment(self, cast_to):
+        """
+        Test that in most cases:
+           * `np.array(scalar, dtype=dtype)`
+           * `np.empty((), dtype=dtype)[()] = scalar`
+           * `np.array(scalar).astype(dtype)`
+        should behave the same.  The only exceptions are parametric dtypes
+        (mainly datetime/timedelta without unit) and void without fields.
+        """
+        dtype = cast_to.dtype  # use to parametrize only the target dtype
+
+        for scalar in scalar_instances(times=False):
+            scalar = scalar.values[0]
+
+            if dtype.type == np.void:
+                if scalar.dtype.fields is not None and dtype.fields is None:
+                    # Here, coercion to "V6" works, but the cast fails.
+                    # Since the types are identical, SETITEM takes care of
+                    # this, but has different rules than the cast.
+                    with pytest.raises(TypeError):
+                        np.array(scalar).astype(dtype)
+                    np.array(scalar, dtype=dtype)
+                    np.array([scalar], dtype=dtype)
+                    continue
+
+            # The main test, we first try to use casting and if it succeeds
+            # continue below testing that things are the same, otherwise
+            # test that the alternative paths at least also fail.
+            try:
+                cast = np.array(scalar).astype(dtype)
+            except (TypeError, ValueError, RuntimeError):
+                # coercion should also raise (error type may change)
+                with pytest.raises(Exception):  # noqa: B017
+                    np.array(scalar, dtype=dtype)
+
+                if (isinstance(scalar, rational) and
+                        np.issubdtype(dtype, np.signedinteger)):
+                    return
+
+                with pytest.raises(Exception):  # noqa: B017
+                    np.array([scalar], dtype=dtype)
+                # assignment should also raise
+                res = np.zeros((), dtype=dtype)
+                with pytest.raises(Exception):  # noqa: B017
+                    res[()] = scalar
+
+                return
+
+            # Non error path:
+            arr = np.array(scalar, dtype=dtype)
+            assert_array_equal(arr, cast)
+            # assignment behaves the same
+            ass = np.zeros((), dtype=dtype)
+            ass[()] = scalar
+            assert_array_equal(ass, cast)
+
+    @pytest.mark.parametrize("pyscalar", [10, 10.32, 10.14j, 10**100])
+    def test_pyscalar_subclasses(self, pyscalar):
+        """NumPy arrays are read/write which means that anything but invariant
+        behaviour is on thin ice.  However, we currently are happy to discover
+        subclasses of Python float, int, complex the same as the base classes.
+        This should potentially be deprecated.
+        """
+        class MyScalar(type(pyscalar)):
+            pass
+
+        res = np.array(MyScalar(pyscalar))
+        expected = np.array(pyscalar)
+        assert_array_equal(res, expected)
+
+    @pytest.mark.parametrize("dtype_char", np.typecodes["All"])
+    def test_default_dtype_instance(self, dtype_char):
+        if dtype_char in "SU":
+            dtype = np.dtype(dtype_char + "1")
+        elif dtype_char == "V":
+            # Legacy behaviour was to use V8. The reason was float64 being the
+            # default dtype and that having 8 bytes.
+            dtype = np.dtype("V8")
+        else:
+            dtype = np.dtype(dtype_char)
+
+        discovered_dtype, _ = ncu._discover_array_parameters([], type(dtype))
+
+        assert discovered_dtype == dtype
+        assert discovered_dtype.itemsize == dtype.itemsize
+
+    @pytest.mark.parametrize("dtype", np.typecodes["Integer"])
+    @pytest.mark.parametrize(["scalar", "error"],
+            [(np.float64(np.nan), ValueError),
+             (np.array(-1).astype(np.ulonglong)[()], OverflowError)])
+    def test_scalar_to_int_coerce_does_not_cast(self, dtype, scalar, error):
+        """
+        Signed integers are currently different in that they do not cast other
+        NumPy scalar, but instead use scalar.__int__(). The hardcoded
+        exception to this rule is `np.array(scalar, dtype=integer)`.
+        """
+        dtype = np.dtype(dtype)
+
+        # This is a special case using casting logic. It warns for the NaN
+        # but allows the cast (giving undefined behaviour).
+        with np.errstate(invalid="ignore"):
+            coerced = np.array(scalar, dtype=dtype)
+            cast = np.array(scalar).astype(dtype)
+        assert_array_equal(coerced, cast)
+
+        # However these fail:
+        with pytest.raises(error):
+            np.array([scalar], dtype=dtype)
+        with pytest.raises(error):
+            cast[()] = scalar
+
+
+class TestTimeScalars:
+    @pytest.mark.parametrize("dtype", [np.int64, np.float32])
+    @pytest.mark.parametrize("scalar",
+            [param(np.timedelta64("NaT", "s"), id="timedelta64[s](NaT)"),
+             param(np.timedelta64(123, "s"), id="timedelta64[s]"),
+             param(np.datetime64("NaT", "D"), id="datetime64[D](NaT)"),
+             param(np.datetime64(1, "D"), id="datetime64[D]")],)
+    def test_coercion_basic(self, dtype, scalar):
+        # Note the `[scalar]` is there because np.array(scalar) uses stricter
+        # `scalar.__int__()` rules for backward compatibility right now.
+        arr = np.array(scalar, dtype=dtype)
+        cast = np.array(scalar).astype(dtype)
+        assert_array_equal(arr, cast)
+
+        ass = np.ones((), dtype=dtype)
+        if issubclass(dtype, np.integer):
+            with pytest.raises(TypeError):
+                # raises, as would np.array([scalar], dtype=dtype), this is
+                # conversion from times, but behaviour of integers.
+                ass[()] = scalar
+        else:
+            ass[()] = scalar
+            assert_array_equal(ass, cast)
+
+    @pytest.mark.parametrize("dtype", [np.int64, np.float32])
+    @pytest.mark.parametrize("value, unit", [param(123, "ns", id="timedelta64[ns]")])
+    def test_coercion_timedelta_convert_to_number(self, dtype, value, unit):
+        # Only "ns" and "generic" timedeltas can be converted to numbers
+        # so these are slightly special.
+        scalar = np.timedelta64(value, unit)
+        arr = np.array(scalar, dtype=dtype)
+        cast = np.array(scalar).astype(dtype)
+        ass = np.ones((), dtype=dtype)
+        ass[()] = scalar  # raises, as would np.array([scalar], dtype=dtype)
+
+        assert_array_equal(arr, cast)
+        assert_array_equal(cast, cast)
+
+    @pytest.mark.parametrize("dtype", [np.int64, np.float32])
+    @pytest.mark.parametrize("value, unit",
+            [param(12, "generic", id="timedelta64[generic]")])
+    def test_coercion_generic_timedelta_convert_to_number(self, dtype, value, unit):
+        with pytest.warns(
+            DeprecationWarning,
+            match="The 'generic' unit for NumPy timedelta is deprecated",
+        ):
+            scalar = np.timedelta64(value, unit)
+            arr = np.array(scalar, dtype=dtype)
+            cast = np.array(scalar).astype(dtype)
+            ass = np.ones((), dtype=dtype)
+            ass[()] = scalar  # raises, as would np.array([scalar], dtype=dtype)
+
+            assert_array_equal(arr, cast)
+            assert_array_equal(cast, cast)
+
+    @pytest.mark.parametrize("dtype", ["S6", "U6"])
+    @pytest.mark.parametrize(["val", "unit"],
+            [param(123, "s", id="[s]"), param(123, "D", id="[D]")])
+    def test_coercion_assignment_datetime(self, val, unit, dtype):
+        # String from datetime64 assignment is currently special cased to
+        # never use casting.  This is because casting will error in this
+        # case, and traditionally in most cases the behaviour is maintained
+        # like this.  (`np.array(scalar, dtype="U6")` would have failed before)
+        # TODO: This discrepancy _should_ be resolved, either by relaxing the
+        #       cast, or by deprecating the first part.
+        scalar = np.datetime64(val, unit)
+        dtype = np.dtype(dtype)
+        cut_string = dtype.type(str(scalar)[:6])
+
+        arr = np.array(scalar, dtype=dtype)
+        assert arr[()] == cut_string
+        ass = np.ones((), dtype=dtype)
+        ass[()] = scalar
+        assert ass[()] == cut_string
+
+        with pytest.raises(RuntimeError):
+            # However, unlike the above assignment using `str(scalar)[:6]`
+            # due to being handled by the string DType and not be casting
+            # the explicit cast fails:
+            np.array(scalar).astype(dtype)
+
+    @pytest.mark.parametrize(["val", "unit"],
+            [param(123, "s", id="[s]"), param(123, "D", id="[D]")])
+    def test_coercion_assignment_timedelta(self, val, unit):
+        scalar = np.timedelta64(val, unit)
+
+        # Unlike datetime64, timedelta allows the unsafe cast:
+        np.array(scalar, dtype="S6")
+        cast = np.array(scalar).astype("S6")
+        ass = np.ones((), dtype="S6")
+        ass[()] = scalar
+        expected = scalar.astype("S")[:6]
+        assert cast[()] == expected
+        assert ass[()] == expected
+
+class TestNested:
+    def test_nested_simple(self):
+        initial = [1.2]
+        nested = initial
+        for i in range(ncu.MAXDIMS - 1):
+            nested = [nested]
+
+        arr = np.array(nested, dtype="float64")
+        assert arr.shape == (1,) * ncu.MAXDIMS
+        with pytest.raises(ValueError):
+            np.array([nested], dtype="float64")
+
+        with pytest.raises(ValueError, match=".*would exceed the maximum"):
+            np.array([nested])  # user must ask for `object` explicitly
+
+        arr = np.array([nested], dtype=object)
+        assert arr.dtype == np.dtype("O")
+        assert arr.shape == (1,) * ncu.MAXDIMS
+        assert arr.item() is initial
+
+    def test_pathological_self_containing(self):
+        # Test that this also works for two nested sequences
+        l = []
+        l.append(l)
+        arr = np.array([l, l, l], dtype=object)
+        assert arr.shape == (3,) + (1,) * (ncu.MAXDIMS - 1)
+
+        # Also check a ragged case:
+        arr = np.array([l, [None], l], dtype=object)
+        assert arr.shape == (3, 1)
+
+    @pytest.mark.parametrize("arraylike", arraylikes())
+    def test_nested_arraylikes(self, arraylike):
+        # We try storing an array like into an array, but the array-like
+        # will have too many dimensions.  This means the shape discovery
+        # decides that the array-like must be treated as an object (a special
+        # case of ragged discovery).  The result will be an array with one
+        # dimension less than the maximum dimensions, and the array being
+        # assigned to it (which does work for object or if `float(arraylike)`
+        # works).
+        initial = arraylike(np.ones((1, 1)))
+
+        nested = initial
+        for i in range(ncu.MAXDIMS - 1):
+            nested = [nested]
+
+        with pytest.raises(ValueError, match=".*would exceed the maximum"):
+            # It will refuse to assign the array into
+            np.array(nested, dtype="float64")
+
+        # If this is object, we end up assigning a (1, 1) array into (1,)
+        # (due to running out of dimensions), this is currently supported but
+        # a special case which is not ideal.
+        arr = np.array(nested, dtype=object)
+        assert arr.shape == (1,) * ncu.MAXDIMS
+        assert arr.item() == np.array(initial).item()
+
+    @pytest.mark.parametrize("arraylike", arraylikes())
+    def test_uneven_depth_ragged(self, arraylike):
+        arr = np.arange(4).reshape((2, 2))
+        arr = arraylike(arr)
+
+        # Array is ragged in the second dimension already:
+        out = np.array([arr, [arr]], dtype=object)
+        assert out.shape == (2,)
+        assert out[0] is arr
+        assert type(out[1]) is list
+
+        # Array is ragged in the third dimension:
+        with pytest.raises(ValueError):
+            # This is a broadcast error during assignment, because
+            # the array shape would be (2, 2, 2) but `arr[0, 0] = arr` fails.
+            np.array([arr, [arr, arr]], dtype=object)
+
+    def test_empty_sequence(self):
+        arr = np.array([[], [1], [[1]]], dtype=object)
+        assert arr.shape == (3,)
+
+        # The empty sequence stops further dimension discovery, so the
+        # result shape will be (0,) which leads to an error during:
+        with pytest.raises(ValueError):
+            np.array([[], np.empty((0, 1))], dtype=object)
+
+    def test_array_of_different_depths(self):
+        # When multiple arrays (or array-likes) are included in a
+        # sequences and have different depth, we currently discover
+        # as many dimensions as they share. (see also gh-17224)
+        arr = np.zeros((3, 2))
+        mismatch_first_dim = np.zeros((1, 2))
+        mismatch_second_dim = np.zeros((3, 3))
+
+        dtype, shape = ncu._discover_array_parameters(
+            [arr, mismatch_second_dim], dtype=np.dtype("O"))
+        assert shape == (2, 3)
+
+        dtype, shape = ncu._discover_array_parameters(
+            [arr, mismatch_first_dim], dtype=np.dtype("O"))
+        assert shape == (2,)
+        # The second case is currently supported because the arrays
+        # can be stored as objects:
+        res = np.asarray([arr, mismatch_first_dim], dtype=np.dtype("O"))
+        assert res[0] is arr
+        assert res[1] is mismatch_first_dim
+
+
+class TestBadSequences:
+    # These are tests for bad objects passed into `np.array`, in general
+    # these have undefined behaviour.  In the old code they partially worked
+    # when now they will fail.  We could (and maybe should) create a copy
+    # of all sequences to be safe against bad-actors.
+
+    def test_growing_list(self):
+        # List to coerce, `mylist` will append to it during coercion
+        obj = []
+
+        class mylist(list):
+            def __len__(self):
+                obj.append([1, 2])
+                return super().__len__()
+
+        obj.append(mylist([1, 2]))
+
+        with pytest.raises(RuntimeError):
+            np.array(obj)
+
+    # Note: We do not test a shrinking list.  These do very evil things
+    #       and the only way to fix them would be to copy all sequences.
+    #       (which may be a real option in the future).
+
+    def test_mutated_list(self):
+        # List to coerce, `mylist` will mutate the first element
+        obj = []
+
+        class mylist(list):
+            def __len__(self):
+                obj[0] = [2, 3]  # replace with a different list.
+                return super().__len__()
+
+        obj.append([2, 3])
+        obj.append(mylist([1, 2]))
+        # Does not crash:
+        np.array(obj)
+
+    def test_replace_0d_array(self):
+        # List to coerce, `mylist` will mutate the first element
+        obj = []
+
+        class baditem:
+            def __len__(self):
+                obj[0][0] = 2  # replace with a different list.
+                raise ValueError("not actually a sequence!")
+
+            def __getitem__(self, _, /):
+                pass
+
+        # Runs into a corner case in the new code, the `array(2)` is cached
+        # so replacing it invalidates the cache.
+        obj.append([np.array(2), baditem()])
+        with pytest.raises(RuntimeError):
+            np.array(obj)
+
+
+class TestArrayLikes:
+    @pytest.mark.parametrize("arraylike", arraylikes())
+    def test_0d_object_special_case(self, arraylike):
+        arr = np.array(0.)
+        obj = arraylike(arr)
+        # A single array-like is always converted:
+        res = np.array(obj, dtype=object)
+        assert_array_equal(arr, res)
+
+        # But a single 0-D nested array-like never:
+        res = np.array([obj], dtype=object)
+        assert res[0] is obj
+
+    @pytest.mark.parametrize("arraylike", arraylikes())
+    @pytest.mark.parametrize("arr", [np.array(0.), np.arange(4)])
+    def test_object_assignment_special_case(self, arraylike, arr):
+        obj = arraylike(arr)
+        empty = np.arange(1, dtype=object)
+        empty[:] = [obj]
+        assert empty[0] is obj
+
+    def test_0d_generic_special_case(self):
+        class ArraySubclass(np.ndarray):
+            def __float__(self):
+                raise TypeError("e.g. quantities raise on this")
+
+        arr = np.array(0.)
+        obj = arr.view(ArraySubclass)
+        res = np.array(obj)
+        # The subclass is simply cast:
+        assert_array_equal(arr, res)
+
+        # If the 0-D array-like is included, __float__ is currently
+        # guaranteed to be used.  We may want to change that, quantities
+        # and masked arrays half make use of this.
+        with pytest.raises(TypeError):
+            np.array([obj])
+
+        # The same holds for memoryview:
+        obj = memoryview(arr)
+        res = np.array(obj)
+        assert_array_equal(arr, res)
+        with pytest.raises(ValueError):
+            # The error type does not matter much here.
+            np.array([obj])
+
+    def test_arraylike_classes(self):
+        # The classes of array-likes should generally be acceptable to be
+        # stored inside a numpy (object) array.  This tests all of the
+        # special attributes (since all are checked during coercion).
+        arr = np.array(np.int64)
+        assert arr[()] is np.int64
+        arr = np.array([np.int64])
+        assert arr[0] is np.int64
+
+        # This also works for properties/unbound methods:
+        class ArrayLike:
+            @property
+            def __array_interface__(self):
+                pass
+
+            @property
+            def __array_struct__(self):
+                pass
+
+            def __array__(self, dtype=None, copy=None):
+                pass
+
+        arr = np.array(ArrayLike)
+        assert arr[()] is ArrayLike
+        arr = np.array([ArrayLike])
+        assert arr[0] is ArrayLike
+
+    @pytest.mark.skipif(not IS_64BIT, reason="Needs 64bit platform")
+    @pytest.mark.thread_unsafe(reason="large slow test in parallel")
+    def test_too_large_array_error_paths(self):
+        """Test the error paths, including for memory leaks"""
+        arr = np.array(0, dtype="uint8")
+        # Guarantees that a contiguous copy won't work:
+        arr = np.broadcast_to(arr, 2**62)
+
+        for i in range(5):
+            # repeat, to ensure caching cannot have an effect:
+            with pytest.raises(MemoryError):
+                np.array(arr)
+            with pytest.raises(MemoryError):
+                np.array([arr])
+
+    @pytest.mark.parametrize("attribute",
+        ["__array_interface__", "__array__", "__array_struct__"])
+    @pytest.mark.parametrize("error", [RecursionError, MemoryError])
+    def test_bad_array_like_attributes(self, attribute, error):
+        # RecursionError and MemoryError are considered fatal. All errors
+        # (except AttributeError) should probably be raised in the future,
+        # but shapely made use of it, so it will require a deprecation.
+
+        class BadInterface:
+            def __getattr__(self, attr):
+                if attr == attribute:
+                    raise error
+                super().__getattr__(attr)
+
+        with pytest.raises(error):
+            np.array(BadInterface())
+
+    @pytest.mark.parametrize("error", [RecursionError, MemoryError])
+    def test_bad_array_like_bad_length(self, error):
+        # RecursionError and MemoryError are considered "critical" in
+        # sequences. We could expand this more generally though. (NumPy 1.20)
+        class BadSequence:
+            def __len__(self):
+                raise error
+
+            def __getitem__(self, _, /):
+                # must have getitem to be a Sequence
+                return 1
+
+        with pytest.raises(error):
+            np.array(BadSequence())
+
+    def test_array_interface_descr_optional(self):
+        # The descr should be optional regression test for gh-27249
+        arr = np.ones(10, dtype="V10")
+        iface = arr.__array_interface__
+        iface.pop("descr")
+
+        class MyClass:
+            __array_interface__ = iface
+
+        assert_array_equal(np.asarray(MyClass), arr)
+
+
+class TestAsArray:
+    """Test expected behaviors of ``asarray``."""
+
+    def test_dtype_identity(self):
+        """Confirm the intended behavior for *dtype* kwarg.
+
+        The result of ``asarray()`` should have the dtype provided through the
+        keyword argument, when used. This forces unique array handles to be
+        produced for unique np.dtype objects, but (for equivalent dtypes), the
+        underlying data (the base object) is shared with the original array
+        object.
+
+        Ref https://github.com/numpy/numpy/issues/1468
+        """
+        int_array = np.array([1, 2, 3], dtype='i')
+        assert np.asarray(int_array) is int_array
+
+        # The character code resolves to the singleton dtype object provided
+        # by the numpy package.
+        assert np.asarray(int_array, dtype='i') is int_array
+
+        # Derive a dtype from n.dtype('i'), but add a metadata object to force
+        # the dtype to be distinct.
+        unequal_type = np.dtype('i', metadata={'spam': True})
+        annotated_int_array = np.asarray(int_array, dtype=unequal_type)
+        assert annotated_int_array is not int_array
+        assert annotated_int_array.base is int_array
+        # Create an equivalent descriptor with a new and distinct dtype
+        # instance.
+        equivalent_requirement = np.dtype('i', metadata={'spam': True})
+        annotated_int_array_alt = np.asarray(annotated_int_array,
+                                             dtype=equivalent_requirement)
+        assert unequal_type == equivalent_requirement
+        assert unequal_type is not equivalent_requirement
+        assert annotated_int_array_alt is not annotated_int_array
+        assert annotated_int_array_alt.dtype is equivalent_requirement
+
+        # Check the same logic for a pair of C types whose equivalence may vary
+        # between computing environments.
+        # Find an equivalent pair.
+        integer_type_codes = ('i', 'l', 'q')
+        integer_dtypes = [np.dtype(code) for code in integer_type_codes]
+        typeA = None
+        typeB = None
+        for typeA, typeB in permutations(integer_dtypes, r=2):
+            if typeA == typeB:
+                assert typeA is not typeB
+                break
+        assert isinstance(typeA, np.dtype) and isinstance(typeB, np.dtype)
+
+        # These ``asarray()`` calls may produce a new view or a copy,
+        # but never the same object.
+        long_int_array = np.asarray(int_array, dtype='l')
+        long_long_int_array = np.asarray(int_array, dtype='q')
+        assert long_int_array is not int_array
+        assert long_long_int_array is not int_array
+        assert np.asarray(long_int_array, dtype='q') is not long_int_array
+        array_a = np.asarray(int_array, dtype=typeA)
+        assert typeA == typeB
+        assert typeA is not typeB
+        assert array_a.dtype is typeA
+        assert array_a is not np.asarray(array_a, dtype=typeB)
+        assert np.asarray(array_a, dtype=typeB).dtype is typeB
+        assert array_a is np.asarray(array_a, dtype=typeB).base
+
+
+class TestSpecialAttributeLookupFailure:
+    # An exception was raised while fetching the attribute
+
+    class WeirdArrayLike:
+        @property
+        def __array__(self, dtype=None, copy=None):
+            raise RuntimeError("oops!")
+
+    class WeirdArrayInterface:
+        @property
+        def __array_interface__(self):
+            raise RuntimeError("oops!")
+
+    def test_deprecated(self):
+        with pytest.raises(RuntimeError):
+            np.array(self.WeirdArrayLike())
+        with pytest.raises(RuntimeError):
+            np.array(self.WeirdArrayInterface())
+
+
+def test_subarray_from_array_construction():
+    # Arrays are more complex, since they "broadcast" on success:
+    arr = np.array([1, 2])
+
+    res = arr.astype("2i")
+    assert_array_equal(res, [[1, 1], [2, 2]])
+
+    res = np.array(arr, dtype="(2,)i")
+
+    assert_array_equal(res, [[1, 1], [2, 2]])
+
+    res = np.array([[(1,), (2,)], arr], dtype="2i")
+    assert_array_equal(res, [[[1, 1], [2, 2]], [[1, 1], [2, 2]]])
+
+    # Also try a multi-dimensional example:
+    arr = np.arange(5 * 2).reshape(5, 2)
+    expected = np.broadcast_to(arr[:, :, np.newaxis, np.newaxis], (5, 2, 2, 2))
+
+    res = arr.astype("(2,2)f")
+    assert_array_equal(res, expected)
+
+    res = np.array(arr, dtype="(2,2)f")
+    assert_array_equal(res, expected)
+
+
+def test_empty_string():
+    # Empty strings are unfortunately often converted to S1 and we need to
+    # make sure we are filling the S1 and not the (possibly) detected S0
+    # result.  This should likely just return S0 and if not maybe the decision
+    # to return S1 should be moved.
+    res = np.array([""] * 10, dtype="S")
+    assert_array_equal(res, np.array("\0", "S1"))
+    assert res.dtype == "S1"
+
+    arr = np.array([""] * 10, dtype=object)
+
+    res = arr.astype("S")
+    assert_array_equal(res, b"")
+    assert res.dtype == "S1"
+
+    res = np.array(arr, dtype="S")
+    assert_array_equal(res, b"")
+    # TODO: This is arguably weird/wrong, but seems old:
+    assert res.dtype == f"S{np.dtype('O').itemsize}"
+
+    res = np.array([[""] * 10, arr], dtype="S")
+    assert_array_equal(res, b"")
+    assert res.shape == (2, 10)
+    assert res.dtype == "S1"
+
+
+@pytest.mark.parametrize("dtype", ["S", "U", object])
+@pytest.mark.parametrize("res_dt,hug_val",
+    [("float16", "1e30"), ("float32", "1e200")])
+def test_string_to_float_coercion_errors(dtype, res_dt, hug_val):
+    # This test primarily tests setitem
+    val = np.array(["3M"], dtype=dtype)[0]  # use the scalar
+
+    with pytest.raises(ValueError):
+        np.array(val, dtype=res_dt)
+
+    val = np.array([hug_val], dtype=dtype)[0]  # use the scalar
+
+    with np.errstate(all="warn"):
+        with pytest.warns(RuntimeWarning):
+            np.array(val, dtype=res_dt)
+
+    with np.errstate(all="raise"):
+        with pytest.raises(FloatingPointError):
+            np.array(val, dtype=res_dt)

v12x/pylib/numpy/_core/tests/test_array_interface.py

@@ -0,0 +1,222 @@
+import sys
+import sysconfig
+
+import pytest
+
+import numpy as np
+from numpy.testing import IS_EDITABLE, IS_WASM, extbuild
+
+
+@pytest.fixture
+def get_module(tmp_path):
+    """ Some codes to generate data and manage temporary buffers use when
+    sharing with numpy via the array interface protocol.
+    """
+    if sys.platform.startswith('cygwin'):
+        pytest.skip('link fails on cygwin')
+    if IS_WASM:
+        pytest.skip("Can't build module inside Wasm")
+    if IS_EDITABLE:
+        pytest.skip("Can't build module for editable install")
+
+    prologue = '''
+        #include <Python.h>
+        #define NPY_NO_DEPRECATED_API NPY_1_7_API_VERSION
+        #include <numpy/arrayobject.h>
+        #include <stdio.h>
+        #include <math.h>
+
+        NPY_NO_EXPORT
+        void delete_array_struct(PyObject *cap) {
+
+            /* get the array interface structure */
+            PyArrayInterface *inter = (PyArrayInterface*)
+                PyCapsule_GetPointer(cap, NULL);
+
+            /* get the buffer by which data was shared */
+            double *ptr = (double*)PyCapsule_GetContext(cap);
+
+            /* for the purposes of the regression test set the elements
+               to nan */
+            for (npy_intp i = 0; i < inter->shape[0]; ++i)
+                ptr[i] = nan("");
+
+            /* free the shared buffer */
+            free(ptr);
+
+            /* free the array interface structure */
+            free(inter->shape);
+            free(inter);
+
+            fprintf(stderr, "delete_array_struct\\ncap = %ld inter = %ld"
+                " ptr = %ld\\n", (long)cap, (long)inter, (long)ptr);
+        }
+        '''
+
+    functions = [
+        ("new_array_struct", "METH_VARARGS", """
+
+            long long n_elem = 0;
+            double value = 0.0;
+
+            if (!PyArg_ParseTuple(args, "Ld", &n_elem, &value)) {
+                Py_RETURN_NONE;
+            }
+
+            /* allocate and initialize the data to share with numpy */
+            long long n_bytes = n_elem*sizeof(double);
+            double *data = (double*)malloc(n_bytes);
+
+            if (!data) {
+                PyErr_Format(PyExc_MemoryError,
+                    "Failed to malloc %lld bytes", n_bytes);
+
+                Py_RETURN_NONE;
+            }
+
+            for (long long i = 0; i < n_elem; ++i) {
+                data[i] = value;
+            }
+
+            /* calculate the shape and stride */
+            int nd = 1;
+
+            npy_intp *ss = (npy_intp*)malloc(2*nd*sizeof(npy_intp));
+            npy_intp *shape = ss;
+            npy_intp *stride = ss + nd;
+
+            shape[0] = n_elem;
+            stride[0] = sizeof(double);
+
+            /* construct the array interface */
+            PyArrayInterface *inter = (PyArrayInterface*)
+                malloc(sizeof(PyArrayInterface));
+
+            memset(inter, 0, sizeof(PyArrayInterface));
+
+            inter->two = 2;
+            inter->nd = nd;
+            inter->typekind = 'f';
+            inter->itemsize = sizeof(double);
+            inter->shape = shape;
+            inter->strides = stride;
+            inter->data = data;
+            inter->flags = NPY_ARRAY_WRITEABLE | NPY_ARRAY_NOTSWAPPED |
+                           NPY_ARRAY_ALIGNED | NPY_ARRAY_C_CONTIGUOUS;
+
+            /* package into a capsule */
+            PyObject *cap = PyCapsule_New(inter, NULL, delete_array_struct);
+
+            /* save the pointer to the data */
+            PyCapsule_SetContext(cap, data);
+
+            fprintf(stderr, "new_array_struct\\ncap = %ld inter = %ld"
+                " ptr = %ld\\n", (long)cap, (long)inter, (long)data);
+
+            return cap;
+        """)
+        ]
+
+    more_init = "import_array();"
+
+    try:
+        import array_interface_testing
+        return array_interface_testing
+    except ImportError:
+        pass
+
+    # if it does not exist, build and load it
+    if sysconfig.get_platform() == "win-arm64":
+        pytest.skip("Meson unable to find MSVC linker on win-arm64")
+    return extbuild.build_and_import_extension('array_interface_testing',
+                                               functions,
+                                               prologue=prologue,
+                                               include_dirs=[np.get_include()],
+                                               build_dir=tmp_path,
+                                               more_init=more_init)
+
+
+@pytest.mark.slow
+def test_cstruct(get_module):
+
+    class data_source:
+        """
+        This class is for testing the timing of the PyCapsule destructor
+        invoked when numpy release its reference to the shared data as part of
+        the numpy array interface protocol. If the PyCapsule destructor is
+        called early the shared data is freed and invalid memory accesses will
+        occur.
+        """
+
+        def __init__(self, size, value):
+            self.size = size
+            self.value = value
+
+        @property
+        def __array_struct__(self):
+            return get_module.new_array_struct(self.size, self.value)
+
+    # write to the same stream as the C code
+    stderr = sys.__stderr__
+
+    # used to validate the shared data.
+    expected_value = -3.1415
+    multiplier = -10000.0
+
+    # create some data to share with numpy via the array interface
+    # assign the data an expected value.
+    stderr.write(' ---- create an object to share data ---- \n')
+    buf = data_source(256, expected_value)
+    stderr.write(' ---- OK!\n\n')
+
+    # share the data
+    stderr.write(' ---- share data via the array interface protocol ---- \n')
+    arr = np.array(buf, copy=False)
+    stderr.write(f'arr.__array_interface___ = {str(arr.__array_interface__)}\n')
+    stderr.write(f'arr.base = {str(arr.base)}\n')
+    stderr.write(' ---- OK!\n\n')
+
+    # release the source of the shared data. this will not release the data
+    # that was shared with numpy, that is done in the PyCapsule destructor.
+    stderr.write(' ---- destroy the object that shared data ---- \n')
+    buf = None
+    stderr.write(' ---- OK!\n\n')
+
+    # check that we got the expected data. If the PyCapsule destructor we
+    # defined was prematurely called then this test will fail because our
+    # destructor sets the elements of the array to NaN before free'ing the
+    # buffer. Reading the values here may also cause a SEGV
+    assert np.allclose(arr, expected_value)
+
+    # read the data. If the PyCapsule destructor we defined was prematurely
+    # called then reading the values here may cause a SEGV and will be reported
+    # as invalid reads by valgrind
+    stderr.write(' ---- read shared data ---- \n')
+    stderr.write(f'arr = {str(arr)}\n')
+    stderr.write(' ---- OK!\n\n')
+
+    # write to the shared buffer. If the shared data was prematurely deleted
+    # this will may cause a SEGV and valgrind will report invalid writes
+    stderr.write(' ---- modify shared data ---- \n')
+    arr *= multiplier
+    expected_value *= multiplier
+    stderr.write(f'arr.__array_interface___ = {str(arr.__array_interface__)}\n')
+    stderr.write(f'arr.base = {str(arr.base)}\n')
+    stderr.write(' ---- OK!\n\n')
+
+    # read the data. If the shared data was prematurely deleted this
+    # will may cause a SEGV and valgrind will report invalid reads
+    stderr.write(' ---- read modified shared data ---- \n')
+    stderr.write(f'arr = {str(arr)}\n')
+    stderr.write(' ---- OK!\n\n')
+
+    # check that we got the expected data. If the PyCapsule destructor we
+    # defined was prematurely called then this test will fail because our
+    # destructor sets the elements of the array to NaN before free'ing the
+    # buffer. Reading the values here may also cause a SEGV
+    assert np.allclose(arr, expected_value)
+
+    # free the shared data, the PyCapsule destructor should run here
+    stderr.write(' ---- free shared data ---- \n')
+    arr = None
+    stderr.write(' ---- OK!\n\n')

v12x/pylib/numpy/_core/tests/test_arraymethod.py

@@ -0,0 +1,85 @@
+"""
+This file tests the generic aspects of ArrayMethod.  At the time of writing
+this is private API, but when added, public API may be added here.
+"""
+
+import types
+from typing import Any
+
+import pytest
+
+import numpy as np
+from numpy._core._multiarray_umath import _get_castingimpl as get_castingimpl
+
+# accessing `numpy.char.charray` will issue a deprecation warning
+from numpy._core.defchararray import chararray
+
+
+class TestResolveDescriptors:
+    # Test mainly error paths of the resolve_descriptors function,
+    # note that the `casting_unittests` tests exercise this non-error paths.
+
+    # Casting implementations are the main/only current user:
+    method = get_castingimpl(type(np.dtype("d")), type(np.dtype("f")))
+
+    @pytest.mark.parametrize("args", [
+        (True,),  # Not a tuple.
+        ((None,)),  # Too few elements
+        ((None, None, None),),  # Too many
+        ((None, None),),  # Input dtype is None, which is invalid.
+        ((np.dtype("d"), True),),  # Output dtype is not a dtype
+        ((np.dtype("f"), None),),  # Input dtype does not match method
+    ])
+    def test_invalid_arguments(self, args):
+        with pytest.raises(TypeError):
+            self.method._resolve_descriptors(*args)
+
+
+class TestSimpleStridedCall:
+    # Test mainly error paths of the resolve_descriptors function,
+    # note that the `casting_unittests` tests exercise this non-error paths.
+
+    # Casting implementations are the main/only current user:
+    method = get_castingimpl(type(np.dtype("d")), type(np.dtype("f")))
+
+    @pytest.mark.parametrize(["args", "error"], [
+        ((True,), TypeError),  # Not a tuple
+        (((None,),), TypeError),  # Too few elements
+        ((None, None), TypeError),  # Inputs are not arrays.
+        (((None, None, None),), TypeError),  # Too many
+        (((np.arange(3), np.arange(3)),), TypeError),  # Incorrect dtypes
+        (((np.ones(3, dtype=">d"), np.ones(3, dtype="<f")),),
+         TypeError),  # Does not support byte-swapping
+        (((np.ones((2, 2), dtype="d"), np.ones((2, 2), dtype="f")),),
+         ValueError),  # not 1-D
+        (((np.ones(3, dtype="d"), np.ones(4, dtype="f")),),
+          ValueError),  # different length
+        (((np.frombuffer(b"\0x00" * 3 * 2, dtype="d"),
+           np.frombuffer(b"\0x00" * 3, dtype="f")),),
+         ValueError),  # output not writeable
+    ])
+    def test_invalid_arguments(self, args, error):
+        # This is private API, which may be modified freely
+        with pytest.raises(error):
+            self.method._simple_strided_call(*args)
+
+
+@pytest.mark.parametrize(
+    "cls", [np.ndarray, np.recarray, chararray, np.matrix, np.memmap]
+)
+class TestClassGetItem:
+    def test_class_getitem(self, cls: type[np.ndarray]) -> None:
+        """Test `ndarray.__class_getitem__`."""
+        alias = cls[Any, Any]
+        assert isinstance(alias, types.GenericAlias)
+        assert alias.__origin__ is cls
+
+    @pytest.mark.parametrize("arg_len", range(4))
+    def test_subscript_tup(self, cls: type[np.ndarray], arg_len: int) -> None:
+        arg_tup = (Any,) * arg_len
+        if arg_len in (1, 2):
+            assert cls[arg_tup]
+        else:
+            match = f"Too {'few' if arg_len == 0 else 'many'} arguments"
+            with pytest.raises(TypeError, match=match):
+                cls[arg_tup]

v12x/pylib/numpy/_core/tests/test_arrayobject.py

@@ -0,0 +1,198 @@
+import sys
+
+import pytest
+
+import numpy as np
+from numpy._core._rational_tests import rational, rational2
+from numpy.testing import HAS_REFCOUNT, assert_array_equal
+
+
+def test_matrix_transpose_raises_error_for_1d():
+    msg = "matrix transpose with ndim < 2 is undefined"
+    arr = np.arange(48)
+    with pytest.raises(ValueError, match=msg):
+        arr.mT
+
+
+def test_matrix_transpose_equals_transpose_2d():
+    arr = np.arange(48).reshape((6, 8))
+    assert_array_equal(arr.T, arr.mT)
+
+
+ARRAY_SHAPES_TO_TEST = (
+    (5, 2),
+    (5, 2, 3),
+    (5, 2, 3, 4),
+)
+
+
+@pytest.mark.parametrize("shape", ARRAY_SHAPES_TO_TEST)
+def test_matrix_transpose_equals_swapaxes(shape):
+    num_of_axes = len(shape)
+    vec = np.arange(shape[-1])
+    arr = np.broadcast_to(vec, shape)
+    tgt = np.swapaxes(arr, num_of_axes - 2, num_of_axes - 1)
+    mT = arr.mT
+    assert_array_equal(tgt, mT)
+
+
+class MyArr(np.ndarray):
+    def __array_wrap__(self, arr, context=None, return_scalar=None):
+        return super().__array_wrap__(arr, context, return_scalar)
+
+
+class MyArrNoWrap(np.ndarray):
+    pass
+
+
+@pytest.mark.parametrize("subclass_self", [np.ndarray, MyArr, MyArrNoWrap])
+@pytest.mark.parametrize("subclass_arr", [np.ndarray, MyArr, MyArrNoWrap])
+def test_array_wrap(subclass_self, subclass_arr):
+    # NumPy should allow `__array_wrap__` to be called on arrays, it's logic
+    # is designed in a way that:
+    #
+    # * Subclasses never return scalars by default (to preserve their
+    #   information).  They can choose to if they wish.
+    # * NumPy returns scalars, if `return_scalar` is passed as True to allow
+    #   manual calls to `arr.__array_wrap__` to do the right thing.
+    # * The type of the input should be ignored (it should be a base-class
+    #   array, but I am not sure this is guaranteed).
+
+    arr = np.arange(3).view(subclass_self)
+
+    arr0d = np.array(3, dtype=np.int8).view(subclass_arr)
+    # With third argument True, ndarray allows "decay" to scalar.
+    # (I don't think NumPy would pass `None`, but it seems clear to support)
+    if subclass_self is np.ndarray:
+        assert type(arr.__array_wrap__(arr0d, None, True)) is np.int8
+    else:
+        assert type(arr.__array_wrap__(arr0d, None, True)) is type(arr)
+
+    # Otherwise, result should be viewed as the subclass
+    assert type(arr.__array_wrap__(arr0d)) is type(arr)
+    assert type(arr.__array_wrap__(arr0d, None, None)) is type(arr)
+    assert type(arr.__array_wrap__(arr0d, None, False)) is type(arr)
+
+    # Non 0-D array can't be converted to scalar, so we ignore that
+    arr1d = np.array([3], dtype=np.int8).view(subclass_arr)
+    assert type(arr.__array_wrap__(arr1d, None, True)) is type(arr)
+
+
+@pytest.mark.skipif(not HAS_REFCOUNT, reason="Python lacks refcounts")
+def test_cleanup_with_refs_non_contig():
+    # Regression test, leaked the dtype (but also good for rest)
+    dtype = np.dtype("O,i")
+    obj = object()
+    expected_ref_dtype = sys.getrefcount(dtype)
+    expected_ref_obj = sys.getrefcount(obj)
+    proto = np.full((3, 4, 5, 6, 7), np.array((obj, 2), dtype=dtype))
+    # Give array a non-trivial order to exercise more cleanup paths.
+    arr = proto.transpose((2, 0, 3, 1, 4)).copy("K")
+    del proto, arr
+
+    actual_ref_dtype = sys.getrefcount(dtype)
+    actual_ref_obj = sys.getrefcount(obj)
+    assert actual_ref_dtype == expected_ref_dtype
+    assert actual_ref_obj == actual_ref_dtype
+
+
+@pytest.mark.parametrize("dtype",
+    list("?bhilqnpBHILQNPefdgSUV") +
+    ["M8[ns]", "m8[ns]", rational, rational2])
+def test_real_imag_attributes_non_complex(dtype):
+    dtype = np.dtype(dtype)
+
+    a = np.array([[1, 2, 3], [4, 5, 6]]).astype(dtype)
+    assert a.real is a
+    # One could imagine broadcasting, but doesn't right now:
+    imag = a.imag
+    assert imag.strides == a.strides
+    assert imag.dtype == a.dtype
+    # This part is rather unclear:
+    assert (imag == np.zeros((), dtype=a.dtype)).all()
+    assert imag.flags.writeable is False
+
+    class myarr(np.ndarray):
+        def __array_finalize__(self, obj):
+            self.finalized_with = obj
+
+    ma = a.view(myarr)
+    assert ma.real is ma
+    assert type(ma.imag) is myarr
+    assert ma.imag.finalized_with is ma
+
+
+@pytest.mark.parametrize("dtype,real_dt",
+    [(">c8", ">f4"), ("c16", "f8"), ("clongdouble", "longdouble")])
+@pytest.mark.parametrize("variation", ["transpose", "set_writeable"])
+def test_real_imag_attributes_complex(dtype, real_dt, variation):
+    a = np.array([[1, 2j, 3], [4, 5j, 6]]).astype(dtype)
+    real = np.array([[1, 0, 3], [4, 0, 6]], dtype=real_dt)
+    imag = np.array([[0, 2, 0], [0, 5, 0]], dtype=real_dt)
+
+    if variation == "transpose":
+        a = a.T
+        real = real.T
+        imag = imag.T
+    elif variation == "set_writeable":
+        a.flags.writeable = False
+
+    assert_array_equal(a.real, real)
+    assert_array_equal(a.imag, imag)
+    assert a.real.dtype == real_dt
+    assert a.imag.dtype == real_dt
+    assert np.may_share_memory(a.real, a)
+    assert np.may_share_memory(a.imag, a)
+    assert a.real.flags.writeable == a.flags.writeable
+    assert a.imag.flags.writeable == a.flags.writeable
+
+    class myarr(np.ndarray):
+        def __array_finalize__(self, obj):
+            self.finalized_with = obj
+
+    ma = a.view(myarr)
+    assert ma.real.finalized_with is ma
+    assert ma.imag.finalized_with is ma
+
+
+def test_real_imag_attributes_object():
+    a = np.array([[1, 0.5 + 2j, 3, int], [4, 5j, "string", {}]], dtype=object)
+
+    # NOTE(seberg): doing something for non-numbers is guesswork...
+    real = np.array([[1, 0.5, 3, int.real], [4, 0, "string", {}]], dtype=object)
+    imag = np.array([[0, 2, 0, int.imag], [0, 5, 0, 0]], dtype=object)
+
+    assert_array_equal(a.real, real)
+    assert_array_equal(a.imag, imag)
+    assert a.real.dtype == object
+    assert a.imag.dtype == object
+    assert not np.may_share_memory(a.real, a)
+    assert not np.may_share_memory(a.imag, a)
+    assert not a.real.flags.writeable
+    assert not a.imag.flags.writeable
+
+    # Object returns new arrays via ufuncs, so call wrap
+    class myarr(np.ndarray):
+        def __array_wrap__(self, *args, **kwargs):
+            ret = super().__array_wrap__(*args, **kwargs)
+            ret.wrap_called = True
+            return ret
+
+    ma = a.view(myarr)
+    assert ma.real.wrap_called
+    assert ma.imag.wrap_called
+
+
+@pytest.mark.parametrize("ufunc,attr", [
+    (np._core.umath.real, "real"), (np._core.umath.imag, "imag")])
+def test_real_imag_ufunc_minimal(ufunc, attr):
+    with pytest.raises(TypeError):
+        ufunc(np.array([1, 2, 3]))  # non-complex or object raises
+
+    arr = np.array([1 + 2j, 3 + 4j])
+    res = ufunc(arr)
+    assert_array_equal(res, getattr(arr, attr), strict=True)
+
+    arr = np.array([1 + 2j, 3 + 4j], dtype=object)
+    res = ufunc(arr)
+    assert_array_equal(res, getattr(arr, attr), strict=True)

v12x/pylib/numpy/_core/tests/test_arrayprint.py

@@ -0,0 +1,1363 @@
+import gc
+import sys
+import textwrap
+
+import pytest
+from hypothesis import given
+from hypothesis.extra import numpy as hynp
+
+import numpy as np
+from numpy._core._rational_tests import rational, rational2
+from numpy._core.arrayprint import _typelessdata
+from numpy._utils import _pep440
+from numpy.testing import (
+    HAS_REFCOUNT,
+    IS_WASM,
+    assert_,
+    assert_array_equal,
+    assert_equal,
+    assert_raises,
+    assert_raises_regex,
+)
+from numpy.testing._private.utils import run_threaded
+
+
+class TestArrayRepr:
+    def test_nan_inf(self):
+        x = np.array([np.nan, np.inf])
+        assert_equal(repr(x), 'array([nan, inf])')
+
+    def test_subclass(self):
+        class sub(np.ndarray):
+            pass
+
+        # one dimensional
+        x1d = np.array([1, 2]).view(sub)
+        assert_equal(repr(x1d), 'sub([1, 2])')
+
+        # two dimensional
+        x2d = np.array([[1, 2], [3, 4]]).view(sub)
+        assert_equal(repr(x2d),
+            'sub([[1, 2],\n'
+            '     [3, 4]])')
+
+        # two dimensional with flexible dtype
+        xstruct = np.ones((2, 2), dtype=[('a', '<i4')]).view(sub)
+        assert_equal(repr(xstruct),
+            "sub([[(1,), (1,)],\n"
+            "     [(1,), (1,)]], dtype=[('a', '<i4')])"
+        )
+
+    @pytest.mark.xfail(reason="See gh-10544")
+    def test_object_subclass(self):
+        class sub(np.ndarray):
+            def __new__(cls, inp):
+                obj = np.asarray(inp).view(cls)
+                return obj
+
+            def __getitem__(self, ind):
+                ret = super().__getitem__(ind)
+                return sub(ret)
+
+        # test that object + subclass is OK:
+        x = sub([None, None])
+        assert_equal(repr(x), 'sub([None, None], dtype=object)')
+        assert_equal(str(x), '[None None]')
+
+        x = sub([None, sub([None, None])])
+        assert_equal(repr(x),
+            'sub([None, sub([None, None], dtype=object)], dtype=object)')
+        assert_equal(str(x), '[None sub([None, None], dtype=object)]')
+
+    def test_0d_object_subclass(self):
+        # make sure that subclasses which return 0ds instead
+        # of scalars don't cause infinite recursion in str
+        class sub(np.ndarray):
+            def __new__(cls, inp):
+                obj = np.asarray(inp).view(cls)
+                return obj
+
+            def __getitem__(self, ind):
+                ret = super().__getitem__(ind)
+                return sub(ret)
+
+        x = sub(1)
+        assert_equal(repr(x), 'sub(1)')
+        assert_equal(str(x), '1')
+
+        x = sub([1, 1])
+        assert_equal(repr(x), 'sub([1, 1])')
+        assert_equal(str(x), '[1 1]')
+
+        # check it works properly with object arrays too
+        x = sub(None)
+        assert_equal(repr(x), 'sub(None, dtype=object)')
+        assert_equal(str(x), 'None')
+
+        # plus recursive object arrays (even depth > 1)
+        y = sub(None)
+        x[()] = y
+        y[()] = x
+        assert_equal(repr(x),
+            'sub(sub(sub(..., dtype=object), dtype=object), dtype=object)')
+        assert_equal(str(x), '...')
+        x[()] = 0  # resolve circular references for garbage collector
+
+        # nested 0d-subclass-object
+        x = sub(None)
+        x[()] = sub(None)
+        assert_equal(repr(x), 'sub(sub(None, dtype=object), dtype=object)')
+        assert_equal(str(x), 'None')
+
+        # gh-10663
+        class DuckCounter(np.ndarray):
+            def __getitem__(self, item):
+                result = super().__getitem__(item)
+                if not isinstance(result, DuckCounter):
+                    result = result[...].view(DuckCounter)
+                return result
+
+            def to_string(self):
+                return {0: 'zero', 1: 'one', 2: 'two'}.get(self.item(), 'many')
+
+            def __str__(self):
+                if self.shape == ():
+                    return self.to_string()
+                else:
+                    fmt = {'all': lambda x: x.to_string()}
+                    return np.array2string(self, formatter=fmt)
+
+        dc = np.arange(5).view(DuckCounter)
+        assert_equal(str(dc), "[zero one two many many]")
+        assert_equal(str(dc[0]), "zero")
+
+    def test_self_containing(self):
+        arr0d = np.array(None)
+        arr0d[()] = arr0d
+        assert_equal(repr(arr0d),
+            'array(array(..., dtype=object), dtype=object)')
+        arr0d[()] = 0  # resolve recursion for garbage collector
+
+        arr1d = np.array([None, None])
+        arr1d[1] = arr1d
+        assert_equal(repr(arr1d),
+            'array([None, array(..., dtype=object)], dtype=object)')
+        arr1d[1] = 0  # resolve recursion for garbage collector
+
+        first = np.array(None)
+        second = np.array(None)
+        first[()] = second
+        second[()] = first
+        assert_equal(repr(first),
+            'array(array(array(..., dtype=object), dtype=object), dtype=object)')
+        first[()] = 0  # resolve circular references for garbage collector
+
+    def test_containing_list(self):
+        # printing square brackets directly would be ambiguous
+        arr1d = np.array([None, None])
+        arr1d[0] = [1, 2]
+        arr1d[1] = [3]
+        assert_equal(repr(arr1d),
+            'array([list([1, 2]), list([3])], dtype=object)')
+
+    def test_void_scalar_recursion(self):
+        # gh-9345
+        repr(np.void(b'test'))  # RecursionError ?
+
+    def test_fieldless_structured(self):
+        # gh-10366
+        no_fields = np.dtype([])
+        arr_no_fields = np.empty(4, dtype=no_fields)
+        assert_equal(repr(arr_no_fields), 'array([(), (), (), ()], dtype=[])')
+
+
+class TestComplexArray:
+    def test_str(self):
+        rvals = [0, 1, -1, np.inf, -np.inf, np.nan]
+        cvals = [complex(rp, ip) for rp in rvals for ip in rvals]
+        dtypes = [np.complex64, np.cdouble, np.clongdouble]
+        actual = [str(np.array([c], dt)) for c in cvals for dt in dtypes]
+        wanted = [
+            '[0.+0.j]',    '[0.+0.j]',    '[0.+0.j]',
+            '[0.+1.j]',    '[0.+1.j]',    '[0.+1.j]',
+            '[0.-1.j]',    '[0.-1.j]',    '[0.-1.j]',
+            '[0.+infj]',   '[0.+infj]',   '[0.+infj]',
+            '[0.-infj]',   '[0.-infj]',   '[0.-infj]',
+            '[0.+nanj]',   '[0.+nanj]',   '[0.+nanj]',
+            '[1.+0.j]',    '[1.+0.j]',    '[1.+0.j]',
+            '[1.+1.j]',    '[1.+1.j]',    '[1.+1.j]',
+            '[1.-1.j]',    '[1.-1.j]',    '[1.-1.j]',
+            '[1.+infj]',   '[1.+infj]',   '[1.+infj]',
+            '[1.-infj]',   '[1.-infj]',   '[1.-infj]',
+            '[1.+nanj]',   '[1.+nanj]',   '[1.+nanj]',
+            '[-1.+0.j]',   '[-1.+0.j]',   '[-1.+0.j]',
+            '[-1.+1.j]',   '[-1.+1.j]',   '[-1.+1.j]',
+            '[-1.-1.j]',   '[-1.-1.j]',   '[-1.-1.j]',
+            '[-1.+infj]',  '[-1.+infj]',  '[-1.+infj]',
+            '[-1.-infj]',  '[-1.-infj]',  '[-1.-infj]',
+            '[-1.+nanj]',  '[-1.+nanj]',  '[-1.+nanj]',
+            '[inf+0.j]',   '[inf+0.j]',   '[inf+0.j]',
+            '[inf+1.j]',   '[inf+1.j]',   '[inf+1.j]',
+            '[inf-1.j]',   '[inf-1.j]',   '[inf-1.j]',
+            '[inf+infj]',  '[inf+infj]',  '[inf+infj]',
+            '[inf-infj]',  '[inf-infj]',  '[inf-infj]',
+            '[inf+nanj]',  '[inf+nanj]',  '[inf+nanj]',
+            '[-inf+0.j]',  '[-inf+0.j]',  '[-inf+0.j]',
+            '[-inf+1.j]',  '[-inf+1.j]',  '[-inf+1.j]',
+            '[-inf-1.j]',  '[-inf-1.j]',  '[-inf-1.j]',
+            '[-inf+infj]', '[-inf+infj]', '[-inf+infj]',
+            '[-inf-infj]', '[-inf-infj]', '[-inf-infj]',
+            '[-inf+nanj]', '[-inf+nanj]', '[-inf+nanj]',
+            '[nan+0.j]',   '[nan+0.j]',   '[nan+0.j]',
+            '[nan+1.j]',   '[nan+1.j]',   '[nan+1.j]',
+            '[nan-1.j]',   '[nan-1.j]',   '[nan-1.j]',
+            '[nan+infj]',  '[nan+infj]',  '[nan+infj]',
+            '[nan-infj]',  '[nan-infj]',  '[nan-infj]',
+            '[nan+nanj]',  '[nan+nanj]',  '[nan+nanj]']
+
+        for res, val in zip(actual, wanted):
+            assert_equal(res, val)
+
+class TestArray2String:
+    def test_basic(self):
+        """Basic test of array2string."""
+        a = np.arange(3)
+        assert_(np.array2string(a) == '[0 1 2]')
+        assert_(np.array2string(a, max_line_width=4, legacy='1.13') == '[0 1\n 2]')
+        assert_(np.array2string(a, max_line_width=4) == '[0\n 1\n 2]')
+
+    def test_unexpected_kwarg(self):
+        # ensure than an appropriate TypeError
+        # is raised when array2string receives
+        # an unexpected kwarg
+
+        with assert_raises_regex(TypeError, 'nonsense'):
+            np.array2string(np.array([1, 2, 3]),
+                            nonsense=None)
+
+    def test_format_function(self):
+        """Test custom format function for each element in array."""
+        def _format_function(x):
+            if np.abs(x) < 1:
+                return '.'
+            elif np.abs(x) < 2:
+                return 'o'
+            else:
+                return 'O'
+
+        x = np.arange(3)
+        x_hex = "[0x0 0x1 0x2]"
+        x_oct = "[0o0 0o1 0o2]"
+        assert_(np.array2string(x, formatter={'all': _format_function}) ==
+                "[. o O]")
+        assert_(np.array2string(x, formatter={'int_kind': _format_function}) ==
+                "[. o O]")
+        assert_(np.array2string(x, formatter={'all': lambda x: f"{x:.4f}"}) ==
+                "[0.0000 1.0000 2.0000]")
+        assert_equal(np.array2string(x, formatter={'int': hex}),
+                x_hex)
+        assert_equal(np.array2string(x, formatter={'int': oct}),
+                x_oct)
+
+        x = np.arange(3.)
+        assert_(np.array2string(x, formatter={'float_kind': lambda x: f"{x:.2f}"}) ==
+                "[0.00 1.00 2.00]")
+        assert_(np.array2string(x, formatter={'float': lambda x: f"{x:.2f}"}) ==
+                "[0.00 1.00 2.00]")
+
+        s = np.array(['abc', 'def'])
+        assert_(np.array2string(s, formatter={'numpystr': lambda s: s * 2}) ==
+                '[abcabc defdef]')
+
+    def test_structure_format_mixed(self):
+        dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))])
+        x = np.array([('Sarah', (8.0, 7.0)), ('John', (6.0, 7.0))], dtype=dt)
+        assert_equal(np.array2string(x),
+                "[('Sarah', [8., 7.]) ('John', [6., 7.])]")
+
+        np.set_printoptions(legacy='1.13')
+        try:
+            # for issue #5692
+            A = np.zeros(shape=10, dtype=[("A", "M8[s]")])
+            A[5:].fill(np.datetime64('NaT', 'D'))
+            date_string = '1970-01-01T00:00:00'
+            assert_equal(
+                np.array2string(A),
+                textwrap.dedent(f"""\
+                [('{date_string}',) ('{date_string}',) ('{date_string}',)
+                 ('{date_string}',) ('{date_string}',) ('NaT',) ('NaT',)
+                 ('NaT',) ('NaT',) ('NaT',)]""")
+            )
+        finally:
+            np.set_printoptions(legacy=False)
+
+        # same again, but with non-legacy behavior
+        assert_equal(
+            np.array2string(A),
+            textwrap.dedent("""\
+            [('1970-01-01T00:00:00',) ('1970-01-01T00:00:00',)
+             ('1970-01-01T00:00:00',) ('1970-01-01T00:00:00',)
+             ('1970-01-01T00:00:00',) (                'NaT',)
+             (                'NaT',) (                'NaT',)
+             (                'NaT',) (                'NaT',)]""")
+        )
+
+        # and again, with timedeltas
+        A = np.full(10, 123456, dtype=[("A", "m8[s]")])
+        A[5:].fill(np.datetime64('NaT', 'D'))
+        assert_equal(
+            np.array2string(A),
+            textwrap.dedent("""\
+            [(123456,) (123456,) (123456,) (123456,) (123456,) ( 'NaT',) ( 'NaT',)
+             ( 'NaT',) ( 'NaT',) ( 'NaT',)]""")
+        )
+
+    def test_structure_format_int(self):
+        # See #8160
+        struct_int = np.array([([1, -1],), ([123, 1],)],
+                dtype=[('B', 'i4', 2)])
+        assert_equal(np.array2string(struct_int),
+                "[([  1,  -1],) ([123,   1],)]")
+        struct_2dint = np.array([([[0, 1], [2, 3]],), ([[12, 0], [0, 0]],)],
+                dtype=[('B', 'i4', (2, 2))])
+        assert_equal(np.array2string(struct_2dint),
+                "[([[ 0,  1], [ 2,  3]],) ([[12,  0], [ 0,  0]],)]")
+
+    def test_structure_format_float(self):
+        # See #8172
+        array_scalar = np.array(
+                (1., 2.1234567890123456789, 3.), dtype=('f8,f8,f8'))
+        assert_equal(np.array2string(array_scalar), "(1., 2.12345679, 3.)")
+
+    def test_unstructured_void_repr(self):
+        a = np.array([27, 91, 50, 75, 7, 65, 10, 8, 27, 91, 51, 49, 109, 82, 101, 100],
+                      dtype='u1').view('V8')
+        assert_equal(repr(a[0]),
+            r"np.void(b'\x1B\x5B\x32\x4B\x07\x41\x0A\x08')")
+        assert_equal(str(a[0]), r"b'\x1B\x5B\x32\x4B\x07\x41\x0A\x08'")
+        assert_equal(repr(a),
+            r"array([b'\x1B\x5B\x32\x4B\x07\x41\x0A\x08',"
+            "\n"
+            r"       b'\x1B\x5B\x33\x31\x6D\x52\x65\x64'], dtype='|V8')")
+
+        assert_equal(eval(repr(a), vars(np)), a)
+        assert_equal(eval(repr(a[0]), {'np': np}), a[0])
+
+    def test_edgeitems_kwarg(self):
+        # previously the global print options would be taken over the kwarg
+        arr = np.zeros(3, int)
+        assert_equal(
+            np.array2string(arr, edgeitems=1, threshold=0),
+            "[0 ... 0]"
+        )
+
+    def test_summarize_1d(self):
+        A = np.arange(1001)
+        strA = '[   0    1    2 ...  998  999 1000]'
+        assert_equal(str(A), strA)
+
+        reprA = 'array([   0,    1,    2, ...,  998,  999, 1000])'
+        try:
+            np.set_printoptions(legacy='2.1')
+            assert_equal(repr(A), reprA)
+        finally:
+            np.set_printoptions(legacy=False)
+
+        assert_equal(repr(A), reprA.replace(')', ', shape=(1001,))'))
+
+    def test_summarize_2d(self):
+        A = np.arange(1002).reshape(2, 501)
+        strA = '[[   0    1    2 ...  498  499  500]\n' \
+               ' [ 501  502  503 ...  999 1000 1001]]'
+        assert_equal(str(A), strA)
+
+        reprA = 'array([[   0,    1,    2, ...,  498,  499,  500],\n' \
+                '       [ 501,  502,  503, ...,  999, 1000, 1001]])'
+        try:
+            np.set_printoptions(legacy='2.1')
+            assert_equal(repr(A), reprA)
+        finally:
+            np.set_printoptions(legacy=False)
+
+        assert_equal(repr(A), reprA.replace(')', ', shape=(2, 501))'))
+
+    def test_summarize_2d_dtype(self):
+        A = np.arange(1002, dtype='i2').reshape(2, 501)
+        strA = '[[   0    1    2 ...  498  499  500]\n' \
+               ' [ 501  502  503 ...  999 1000 1001]]'
+        assert_equal(str(A), strA)
+
+        reprA = ('array([[   0,    1,    2, ...,  498,  499,  500],\n'
+                 '       [ 501,  502,  503, ...,  999, 1000, 1001]],\n'
+                 '      shape=(2, 501), dtype=int16)')
+        assert_equal(repr(A), reprA)
+
+    def test_summarize_structure(self):
+        A = (np.arange(2002, dtype="<i8").reshape(2, 1001)
+             .view([('i', "<i8", (1001,))]))
+        strA = ("[[([   0,    1,    2, ...,  998,  999, 1000],)]\n"
+                " [([1001, 1002, 1003, ..., 1999, 2000, 2001],)]]")
+        assert_equal(str(A), strA)
+
+        reprA = ("array([[([   0,    1,    2, ...,  998,  999, 1000],)],\n"
+                 "       [([1001, 1002, 1003, ..., 1999, 2000, 2001],)]],\n"
+                 "      dtype=[('i', '<i8', (1001,))])")
+        assert_equal(repr(A), reprA)
+
+        B = np.ones(2002, dtype=">i8").view([('i', ">i8", (2, 1001))])
+        strB = "[([[1, 1, 1, ..., 1, 1, 1], [1, 1, 1, ..., 1, 1, 1]],)]"
+        assert_equal(str(B), strB)
+
+        reprB = (
+            "array([([[1, 1, 1, ..., 1, 1, 1], [1, 1, 1, ..., 1, 1, 1]],)],\n"
+            "      dtype=[('i', '>i8', (2, 1001))])"
+        )
+        assert_equal(repr(B), reprB)
+
+        C = (np.arange(22, dtype="<i8").reshape(2, 11)
+             .view([('i1', "<i8"), ('i10', "<i8", (10,))]))
+        strC = "[[( 0, [ 1, ..., 10])]\n [(11, [12, ..., 21])]]"
+        assert_equal(np.array2string(C, threshold=1, edgeitems=1), strC)
+
+    def test_linewidth(self):
+        a = np.full(6, 1)
+
+        def make_str(a, width, **kw):
+            return np.array2string(a, separator="", max_line_width=width, **kw)
+
+        assert_equal(make_str(a, 8, legacy='1.13'), '[111111]')
+        assert_equal(make_str(a, 7, legacy='1.13'), '[111111]')
+        assert_equal(make_str(a, 5, legacy='1.13'), '[1111\n'
+                                                    ' 11]')
+
+        assert_equal(make_str(a, 8), '[111111]')
+        assert_equal(make_str(a, 7), '[11111\n'
+                                     ' 1]')
+        assert_equal(make_str(a, 5), '[111\n'
+                                     ' 111]')
+
+        b = a[None, None, :]
+
+        assert_equal(make_str(b, 12, legacy='1.13'), '[[[111111]]]')
+        assert_equal(make_str(b,  9, legacy='1.13'), '[[[111111]]]')
+        assert_equal(make_str(b,  8, legacy='1.13'), '[[[11111\n'
+                                                     '   1]]]')
+
+        assert_equal(make_str(b, 12), '[[[111111]]]')
+        assert_equal(make_str(b,  9), '[[[111\n'
+                                      '   111]]]')
+        assert_equal(make_str(b,  8), '[[[11\n'
+                                      '   11\n'
+                                      '   11]]]')
+
+    def test_wide_element(self):
+        a = np.array(['xxxxx'])
+        assert_equal(
+            np.array2string(a, max_line_width=5),
+            "['xxxxx']"
+        )
+        assert_equal(
+            np.array2string(a, max_line_width=5, legacy='1.13'),
+            "[ 'xxxxx']"
+        )
+
+    def test_multiline_repr(self):
+        class MultiLine:
+            def __repr__(self):
+                return "Line 1\nLine 2"
+
+        a = np.array([[None, MultiLine()], [MultiLine(), None]])
+
+        assert_equal(
+            np.array2string(a),
+            '[[None Line 1\n'
+            '       Line 2]\n'
+            ' [Line 1\n'
+            '  Line 2 None]]'
+        )
+        assert_equal(
+            np.array2string(a, max_line_width=5),
+            '[[None\n'
+            '  Line 1\n'
+            '  Line 2]\n'
+            ' [Line 1\n'
+            '  Line 2\n'
+            '  None]]'
+        )
+        assert_equal(
+            repr(a),
+            'array([[None, Line 1\n'
+            '              Line 2],\n'
+            '       [Line 1\n'
+            '        Line 2, None]], dtype=object)'
+        )
+
+        class MultiLineLong:
+            def __repr__(self):
+                return "Line 1\nLooooooooooongestLine2\nLongerLine 3"
+
+        a = np.array([[None, MultiLineLong()], [MultiLineLong(), None]])
+        assert_equal(
+            repr(a),
+            'array([[None, Line 1\n'
+            '              LooooooooooongestLine2\n'
+            '              LongerLine 3          ],\n'
+            '       [Line 1\n'
+            '        LooooooooooongestLine2\n'
+            '        LongerLine 3          , None]], dtype=object)'
+        )
+        assert_equal(
+            np.array_repr(a, 20),
+            'array([[None,\n'
+            '        Line 1\n'
+            '        LooooooooooongestLine2\n'
+            '        LongerLine 3          ],\n'
+            '       [Line 1\n'
+            '        LooooooooooongestLine2\n'
+            '        LongerLine 3          ,\n'
+            '        None]],\n'
+            '      dtype=object)'
+        )
+
+    def test_nested_array_repr(self):
+        a = np.empty((2, 2), dtype=object)
+        a[0, 0] = np.eye(2)
+        a[0, 1] = np.eye(3)
+        a[1, 0] = None
+        a[1, 1] = np.ones((3, 1))
+        assert_equal(
+            repr(a),
+            'array([[array([[1., 0.],\n'
+            '               [0., 1.]]), array([[1., 0., 0.],\n'
+            '                                  [0., 1., 0.],\n'
+            '                                  [0., 0., 1.]])],\n'
+            '       [None, array([[1.],\n'
+            '                     [1.],\n'
+            '                     [1.]])]], dtype=object)'
+        )
+
+    @given(hynp.from_dtype(np.dtype("U")))
+    def test_any_text(self, text):
+        # This test checks that, given any value that can be represented in an
+        # array of dtype("U") (i.e. unicode string), ...
+        a = np.array([text, text, text])
+        # casting a list of them to an array does not e.g. truncate the value
+        assert_equal(a[0], text)
+        text = text.item()  # use raw python strings for repr below
+        # and that np.array2string puts a newline in the expected location
+        expected_repr = f"[{text!r} {text!r}\n {text!r}]"
+        result = np.array2string(a, max_line_width=len(repr(text)) * 2 + 3)
+        assert_equal(result, expected_repr)
+
+    @pytest.mark.skipif(not HAS_REFCOUNT, reason="Python lacks refcounts")
+    @pytest.mark.thread_unsafe(reason="garbage collector is global state")
+    def test_refcount(self):
+        # make sure we do not hold references to the array due to a recursive
+        # closure (gh-10620)
+        gc.disable()
+        a = np.arange(2)
+        r1 = sys.getrefcount(a)
+        np.array2string(a)
+        np.array2string(a)
+        r2 = sys.getrefcount(a)
+        gc.collect()
+        gc.enable()
+        assert_(r1 == r2)
+
+    def test_with_sign(self):
+        # mixed negative and positive value array
+        a = np.array([-2, 0, 3])
+        assert_equal(
+            np.array2string(a, sign='+'),
+            '[-2 +0 +3]'
+        )
+        assert_equal(
+            np.array2string(a, sign='-'),
+            '[-2  0  3]'
+        )
+        assert_equal(
+            np.array2string(a, sign=' '),
+            '[-2  0  3]'
+        )
+        # all non-negative array
+        a = np.array([2, 0, 3])
+        assert_equal(
+            np.array2string(a, sign='+'),
+            '[+2 +0 +3]'
+        )
+        assert_equal(
+            np.array2string(a, sign='-'),
+            '[2 0 3]'
+        )
+        assert_equal(
+            np.array2string(a, sign=' '),
+            '[ 2  0  3]'
+        )
+        # all negative array
+        a = np.array([-2, -1, -3])
+        assert_equal(
+            np.array2string(a, sign='+'),
+            '[-2 -1 -3]'
+        )
+        assert_equal(
+            np.array2string(a, sign='-'),
+            '[-2 -1 -3]'
+        )
+        assert_equal(
+            np.array2string(a, sign=' '),
+            '[-2 -1 -3]'
+        )
+        # 2d array mixed negative and positive
+        a = np.array([[10, -1, 1, 1], [10, 10, 10, 10]])
+        assert_equal(
+            np.array2string(a, sign='+'),
+            '[[+10  -1  +1  +1]\n [+10 +10 +10 +10]]'
+        )
+        assert_equal(
+            np.array2string(a, sign='-'),
+            '[[10 -1  1  1]\n [10 10 10 10]]'
+        )
+        assert_equal(
+            np.array2string(a, sign=' '),
+            '[[10 -1  1  1]\n [10 10 10 10]]'
+        )
+        # 2d array all positive
+        a = np.array([[10, 0, 1, 1], [10, 10, 10, 10]])
+        assert_equal(
+            np.array2string(a, sign='+'),
+            '[[+10  +0  +1  +1]\n [+10 +10 +10 +10]]'
+        )
+        assert_equal(
+            np.array2string(a, sign='-'),
+            '[[10  0  1  1]\n [10 10 10 10]]'
+        )
+        assert_equal(
+            np.array2string(a, sign=' '),
+            '[[ 10   0   1   1]\n [ 10  10  10  10]]'
+        )
+        # 2d array all negative
+        a = np.array([[-10, -1, -1, -1], [-10, -10, -10, -10]])
+        assert_equal(
+            np.array2string(a, sign='+'),
+            '[[-10  -1  -1  -1]\n [-10 -10 -10 -10]]'
+        )
+        assert_equal(
+            np.array2string(a, sign='-'),
+            '[[-10  -1  -1  -1]\n [-10 -10 -10 -10]]'
+        )
+        assert_equal(
+            np.array2string(a, sign=' '),
+            '[[-10  -1  -1  -1]\n [-10 -10 -10 -10]]'
+        )
+
+
+class TestPrintOptions:
+    """Test getting and setting global print options."""
+
+    def setup_method(self):
+        self.oldopts = np.get_printoptions()
+
+    def teardown_method(self):
+        np.set_printoptions(**self.oldopts)
+
+    def test_basic(self):
+        x = np.array([1.5, 0, 1.234567890])
+        assert_equal(repr(x), "array([1.5       , 0.        , 1.23456789])")
+        ret = np.set_printoptions(precision=4)
+        assert_equal(repr(x), "array([1.5   , 0.    , 1.2346])")
+        assert ret is None
+
+    def test_precision_zero(self):
+        np.set_printoptions(precision=0)
+        for values, string in (
+                ([0.], "0."), ([.3], "0."), ([-.3], "-0."), ([.7], "1."),
+                ([1.5], "2."), ([-1.5], "-2."), ([-15.34], "-15."),
+                ([100.], "100."), ([.2, -1, 122.51], "  0.,  -1., 123."),
+                ([0], "0"), ([-12], "-12"), ([complex(.3, -.7)], "0.-1.j")):
+            x = np.array(values)
+            assert_equal(repr(x), f"array([{string}])")
+
+    def test_formatter(self):
+        x = np.arange(3)
+        np.set_printoptions(formatter={'all': lambda x: str(x - 1)})
+        assert_equal(repr(x), "array([-1, 0, 1])")
+
+    def test_formatter_reset(self):
+        x = np.arange(3)
+        np.set_printoptions(formatter={'all': lambda x: str(x - 1)})
+        assert_equal(repr(x), "array([-1, 0, 1])")
+        np.set_printoptions(formatter={'int': None})
+        assert_equal(repr(x), "array([0, 1, 2])")
+
+        np.set_printoptions(formatter={'all': lambda x: str(x - 1)})
+        assert_equal(repr(x), "array([-1, 0, 1])")
+        np.set_printoptions(formatter={'all': None})
+        assert_equal(repr(x), "array([0, 1, 2])")
+
+        np.set_printoptions(formatter={'int': lambda x: str(x - 1)})
+        assert_equal(repr(x), "array([-1, 0, 1])")
+        np.set_printoptions(formatter={'int_kind': None})
+        assert_equal(repr(x), "array([0, 1, 2])")
+
+        x = np.arange(3.)
+        np.set_printoptions(formatter={'float': lambda x: str(x - 1)})
+        assert_equal(repr(x), "array([-1.0, 0.0, 1.0])")
+        np.set_printoptions(formatter={'float_kind': None})
+        assert_equal(repr(x), "array([0., 1., 2.])")
+
+    def test_override_repr(self):
+        x = np.arange(3)
+        np.set_printoptions(override_repr=lambda x: "FOO")
+        assert_equal(repr(x), "FOO")
+        np.set_printoptions(override_repr=None)
+        assert_equal(repr(x), "array([0, 1, 2])")
+
+        with np.printoptions(override_repr=lambda x: "BAR"):
+            assert_equal(repr(x), "BAR")
+        assert_equal(repr(x), "array([0, 1, 2])")
+
+    def test_0d_arrays(self):
+        assert_equal(str(np.array('café', '<U4')), 'café')
+
+        assert_equal(repr(np.array('café', '<U4')),
+                     "array('café', dtype='<U4')")
+        assert_equal(str(np.array('test', np.str_)), 'test')
+
+        a = np.zeros(1, dtype=[('a', '<i4', (3,))])
+        assert_equal(str(a[0]), '([0, 0, 0],)')
+
+        assert_equal(repr(np.datetime64('2005-02-25')[...]),
+                     "array('2005-02-25', dtype='datetime64[D]')")
+
+        assert_equal(repr(np.timedelta64('10', 'Y')[...]),
+                     "array(10, dtype='timedelta64[Y]')")
+
+        # repr of 0d arrays is affected by printoptions
+        x = np.array(1)
+        np.set_printoptions(formatter={'all': lambda x: "test"})
+        assert_equal(repr(x), "array(test)")
+        # str is unaffected
+        assert_equal(str(x), "1")
+
+        # check it works
+        np.array2string(np.array(1.), legacy='1.13')
+
+    def test_float_spacing(self):
+        x = np.array([1., 2., 3.])
+        y = np.array([1., 2., -10.])
+        z = np.array([100., 2., -1.])
+        w = np.array([-100., 2., 1.])
+
+        assert_equal(repr(x), 'array([1., 2., 3.])')
+        assert_equal(repr(y), 'array([  1.,   2., -10.])')
+        assert_equal(repr(np.array(y[0])), 'array(1.)')
+        assert_equal(repr(np.array(y[-1])), 'array(-10.)')
+        assert_equal(repr(z), 'array([100.,   2.,  -1.])')
+        assert_equal(repr(w), 'array([-100.,    2.,    1.])')
+
+        assert_equal(repr(np.array([np.nan, np.inf])), 'array([nan, inf])')
+        assert_equal(repr(np.array([np.nan, -np.inf])), 'array([ nan, -inf])')
+
+        x = np.array([np.inf, 100000, 1.1234])
+        y = np.array([np.inf, 100000, -1.1234])
+        z = np.array([np.inf, 1.1234, -1e120])
+        np.set_printoptions(precision=2)
+        assert_equal(repr(x), 'array([     inf, 1.00e+05, 1.12e+00])')
+        assert_equal(repr(y), 'array([      inf,  1.00e+05, -1.12e+00])')
+        assert_equal(repr(z), 'array([       inf,  1.12e+000, -1.00e+120])')
+
+    def test_bool_spacing(self):
+        assert_equal(repr(np.array([True, True])),
+                     'array([ True,  True])')
+        assert_equal(repr(np.array([True, False])),
+                     'array([ True, False])')
+        assert_equal(repr(np.array([True])),
+                     'array([ True])')
+        assert_equal(repr(np.array(True)),
+                     'array(True)')
+        assert_equal(repr(np.array(False)),
+                     'array(False)')
+
+    def test_sign_spacing(self):
+        a = np.arange(4.)
+        b = np.array([1.234e9])
+        c = np.array([1.0 + 1.0j, 1.123456789 + 1.123456789j], dtype='c16')
+
+        assert_equal(repr(a), 'array([0., 1., 2., 3.])')
+        assert_equal(repr(np.array(1.)), 'array(1.)')
+        assert_equal(repr(b), 'array([1.234e+09])')
+        assert_equal(repr(np.array([0.])), 'array([0.])')
+        assert_equal(repr(c),
+            "array([1.        +1.j        , 1.12345679+1.12345679j])")
+        assert_equal(repr(np.array([0., -0.])), 'array([ 0., -0.])')
+
+        np.set_printoptions(sign=' ')
+        assert_equal(repr(a), 'array([ 0.,  1.,  2.,  3.])')
+        assert_equal(repr(np.array(1.)), 'array( 1.)')
+        assert_equal(repr(b), 'array([ 1.234e+09])')
+        assert_equal(repr(c),
+            "array([ 1.        +1.j        ,  1.12345679+1.12345679j])")
+        assert_equal(repr(np.array([0., -0.])), 'array([ 0., -0.])')
+
+        np.set_printoptions(sign='+')
+        assert_equal(repr(a), 'array([+0., +1., +2., +3.])')
+        assert_equal(repr(np.array(1.)), 'array(+1.)')
+        assert_equal(repr(b), 'array([+1.234e+09])')
+        assert_equal(repr(c),
+            "array([+1.        +1.j        , +1.12345679+1.12345679j])")
+
+        np.set_printoptions(legacy='1.13')
+        assert_equal(repr(a), 'array([ 0.,  1.,  2.,  3.])')
+        assert_equal(repr(b),  'array([  1.23400000e+09])')
+        assert_equal(repr(-b), 'array([ -1.23400000e+09])')
+        assert_equal(repr(np.array(1.)), 'array(1.0)')
+        assert_equal(repr(np.array([0.])), 'array([ 0.])')
+        assert_equal(repr(c),
+            "array([ 1.00000000+1.j        ,  1.12345679+1.12345679j])")
+        # gh-10383
+        assert_equal(str(np.array([-1., 10])), "[ -1.  10.]")
+
+        assert_raises(TypeError, np.set_printoptions, wrongarg=True)
+
+    def test_float_overflow_nowarn(self):
+        # make sure internal computations in FloatingFormat don't
+        # warn about overflow
+        repr(np.array([1e4, 0.1], dtype='f2'))
+
+    def test_sign_spacing_structured(self):
+        a = np.ones(2, dtype='<f,<f')
+        assert_equal(repr(a),
+            "array([(1., 1.), (1., 1.)], dtype=[('f0', '<f4'), ('f1', '<f4')])")
+        assert_equal(repr(a[0]),
+            "np.void((1.0, 1.0), dtype=[('f0', '<f4'), ('f1', '<f4')])")
+
+    def test_floatmode(self):
+        x = np.array([0.6104, 0.922, 0.457, 0.0906, 0.3733, 0.007244,
+                      0.5933, 0.947, 0.2383, 0.4226], dtype=np.float16)
+        y = np.array([0.2918820979355541, 0.5064172631089138,
+                      0.2848750619642916, 0.4342965294660567,
+                      0.7326538397312751, 0.3459503329096204,
+                      0.0862072768214508, 0.39112753029631175],
+                      dtype=np.float64)
+        z = np.arange(6, dtype=np.float16) / 10
+        c = np.array([1.0 + 1.0j, 1.123456789 + 1.123456789j], dtype='c16')
+
+        # also make sure 1e23 is right (is between two fp numbers)
+        w = np.array([f'1e{i}' for i in range(25)], dtype=np.float64)
+        # note: we construct w from the strings `1eXX` instead of doing
+        # `10.**arange(24)` because it turns out the two are not equivalent in
+        # python. On some architectures `1e23 != 10.**23`.
+        wp = np.array([1.234e1, 1e2, 1e123])
+
+        # unique mode
+        np.set_printoptions(floatmode='unique')
+        assert_equal(repr(x),
+            "array([0.6104  , 0.922   , 0.457   , 0.0906  , 0.3733  , 0.007244,\n"
+            "       0.5933  , 0.947   , 0.2383  , 0.4226  ], dtype=float16)")
+        assert_equal(repr(y),
+            "array([0.2918820979355541 , 0.5064172631089138 , 0.2848750619642916 ,\n"
+            "       0.4342965294660567 , 0.7326538397312751 , 0.3459503329096204 ,\n"
+            "       0.0862072768214508 , 0.39112753029631175])")
+        assert_equal(repr(z),
+            "array([0. , 0.1, 0.2, 0.3, 0.4, 0.5], dtype=float16)")
+        assert_equal(repr(w),
+            "array([1.e+00, 1.e+01, 1.e+02, 1.e+03, 1.e+04, 1.e+05, 1.e+06, 1.e+07,\n"
+            "       1.e+08, 1.e+09, 1.e+10, 1.e+11, 1.e+12, 1.e+13, 1.e+14, 1.e+15,\n"
+            "       1.e+16, 1.e+17, 1.e+18, 1.e+19, 1.e+20, 1.e+21, 1.e+22, 1.e+23,\n"
+            "       1.e+24])")
+        assert_equal(repr(wp), "array([1.234e+001, 1.000e+002, 1.000e+123])")
+        assert_equal(repr(c),
+            "array([1.         +1.j         , 1.123456789+1.123456789j])")
+
+        # maxprec mode, precision=8
+        np.set_printoptions(floatmode='maxprec', precision=8)
+        assert_equal(repr(x),
+            "array([0.6104  , 0.922   , 0.457   , 0.0906  , 0.3733  , 0.007244,\n"
+            "       0.5933  , 0.947   , 0.2383  , 0.4226  ], dtype=float16)")
+        assert_equal(repr(y),
+            "array([0.2918821 , 0.50641726, 0.28487506, 0.43429653, 0.73265384,\n"
+            "       0.34595033, 0.08620728, 0.39112753])")
+        assert_equal(repr(z),
+            "array([0. , 0.1, 0.2, 0.3, 0.4, 0.5], dtype=float16)")
+        assert_equal(repr(w[::5]),
+            "array([1.e+00, 1.e+05, 1.e+10, 1.e+15, 1.e+20])")
+        assert_equal(repr(wp), "array([1.234e+001, 1.000e+002, 1.000e+123])")
+        assert_equal(repr(c),
+            "array([1.        +1.j        , 1.12345679+1.12345679j])")
+
+        # fixed mode, precision=4
+        np.set_printoptions(floatmode='fixed', precision=4)
+        assert_equal(repr(x),
+            "array([0.6104, 0.9219, 0.4570, 0.0906, 0.3733, 0.0072, 0.5933, 0.9468,\n"
+            "       0.2383, 0.4226], dtype=float16)")
+        assert_equal(repr(y),
+            "array([0.2919, 0.5064, 0.2849, 0.4343, 0.7327, 0.3460, 0.0862, 0.3911])")
+        assert_equal(repr(z),
+            "array([0.0000, 0.1000, 0.2000, 0.3000, 0.3999, 0.5000], dtype=float16)")
+        assert_equal(repr(w[::5]),
+            "array([1.0000e+00, 1.0000e+05, 1.0000e+10, 1.0000e+15, 1.0000e+20])")
+        assert_equal(repr(wp), "array([1.2340e+001, 1.0000e+002, 1.0000e+123])")
+        assert_equal(repr(np.zeros(3)), "array([0.0000, 0.0000, 0.0000])")
+        assert_equal(repr(c),
+            "array([1.0000+1.0000j, 1.1235+1.1235j])")
+        # for larger precision, representation error becomes more apparent:
+        np.set_printoptions(floatmode='fixed', precision=8)
+        assert_equal(repr(z),
+            "array([0.00000000, 0.09997559, 0.19995117, 0.30004883, 0.39990234,\n"
+            "       0.50000000], dtype=float16)")
+
+        # maxprec_equal  mode, precision=8
+        np.set_printoptions(floatmode='maxprec_equal', precision=8)
+        assert_equal(repr(x),
+            "array([0.610352, 0.921875, 0.457031, 0.090576, 0.373291, 0.007244,\n"
+            "       0.593262, 0.946777, 0.238281, 0.422607], dtype=float16)")
+        assert_equal(repr(y),
+            "array([0.29188210, 0.50641726, 0.28487506, 0.43429653, 0.73265384,\n"
+            "       0.34595033, 0.08620728, 0.39112753])")
+        assert_equal(repr(z),
+            "array([0.0, 0.1, 0.2, 0.3, 0.4, 0.5], dtype=float16)")
+        assert_equal(repr(w[::5]),
+            "array([1.e+00, 1.e+05, 1.e+10, 1.e+15, 1.e+20])")
+        assert_equal(repr(wp), "array([1.234e+001, 1.000e+002, 1.000e+123])")
+        assert_equal(repr(c),
+            "array([1.00000000+1.00000000j, 1.12345679+1.12345679j])")
+
+        # test unique special case (gh-18609)
+        a = np.float64.fromhex('-1p-97')
+        assert_equal(np.float64(np.array2string(a, floatmode='unique')), a)
+
+    test_cases_gh_28679 = [
+        (np.half([999, 999]), "[999. 999.]"),
+        (np.half([999, 1000]), "[9.99e+02 1.00e+03]"),
+        (np.single([999999, 999999]), "[999999. 999999.]"),
+        (np.single([999999, -1000000]), "[ 9.99999e+05 -1.00000e+06]"),
+        (
+            np.complex64([999999 + 999999j, 999999 + 999999j]),
+            "[999999.+999999.j 999999.+999999.j]"
+        ),
+        (
+            np.complex64([999999 + 999999j, 999999 + -1000000j]),
+            "[999999.+9.99999e+05j 999999.-1.00000e+06j]"
+        ),
+    ]
+
+    @pytest.mark.parametrize("input_array, expected_str", test_cases_gh_28679)
+    def test_gh_28679(self, input_array, expected_str):
+        # test cutoff to exponent notation for half, single, and complex64
+        assert_equal(str(input_array), expected_str)
+
+    test_cases_legacy_2_2 = [
+        (np.half([1.e3, 1.e4, 65504]), "[ 1000. 10000. 65504.]"),
+        (np.single([1.e6, 1.e7]), "[ 1000000. 10000000.]"),
+        (np.single([1.e7, 1.e8]), "[1.e+07 1.e+08]"),
+    ]
+
+    @pytest.mark.parametrize("input_array, expected_str", test_cases_legacy_2_2)
+    def test_legacy_2_2_mode(self, input_array, expected_str):
+        # test legacy cutoff to exponent notation for half and single
+        with np.printoptions(legacy='2.2'):
+            assert_equal(str(input_array), expected_str)
+
+    @pytest.mark.parametrize("legacy", ['1.13', '1.21', '1.25', '2.1', '2.2'])
+    def test_legacy_get_options(self, legacy):
+        # test legacy get options works okay
+        with np.printoptions(legacy=legacy):
+            p_opt = np.get_printoptions()
+            assert_equal(p_opt["legacy"], legacy)
+
+    def test_legacy_mode_scalars(self):
+        # in legacy mode, str of floats get truncated, and complex scalars
+        # use * for non-finite imaginary part
+        np.set_printoptions(legacy='1.13')
+        assert_equal(str(np.float64(1.123456789123456789)), '1.12345678912')
+        assert_equal(str(np.complex128(complex(1, np.nan))), '(1+nan*j)')
+
+        np.set_printoptions(legacy=False)
+        assert_equal(str(np.float64(1.123456789123456789)),
+                     '1.1234567891234568')
+        assert_equal(str(np.complex128(complex(1, np.nan))), '(1+nanj)')
+
+    def test_legacy_stray_comma(self):
+        np.set_printoptions(legacy='1.13')
+        assert_equal(str(np.arange(10000)), '[   0    1    2 ..., 9997 9998 9999]')
+
+        np.set_printoptions(legacy=False)
+        assert_equal(str(np.arange(10000)), '[   0    1    2 ... 9997 9998 9999]')
+
+    def test_dtype_linewidth_wrapping(self):
+        np.set_printoptions(linewidth=75)
+        assert_equal(repr(np.arange(10, 20., dtype='f4')),
+            "array([10., 11., 12., 13., 14., 15., 16., 17., 18., 19.], dtype=float32)")
+        assert_equal(repr(np.arange(10, 23., dtype='f4')), textwrap.dedent("""\
+            array([10., 11., 12., 13., 14., 15., 16., 17., 18., 19., 20., 21., 22.],
+                  dtype=float32)"""))
+
+        styp = '<U4'
+        assert_equal(repr(np.ones(3, dtype=styp)),
+            f"array(['1', '1', '1'], dtype='{styp}')")
+        assert_equal(repr(np.ones(12, dtype=styp)), textwrap.dedent(f"""\
+            array(['1', '1', '1', '1', '1', '1', '1', '1', '1', '1', '1', '1'],
+                  dtype='{styp}')"""))
+
+    @pytest.mark.parametrize(
+        ['native'],
+        [
+            ('bool',),
+            ('uint8',),
+            ('uint16',),
+            ('uint32',),
+            ('uint64',),
+            ('int8',),
+            ('int16',),
+            ('int32',),
+            ('int64',),
+            ('float16',),
+            ('float32',),
+            ('float64',),
+            ('U1',),     # 4-byte width string
+        ],
+    )
+    def test_dtype_endianness_repr(self, native):
+        '''
+        there was an issue where
+        repr(array([0], dtype='<u2')) and repr(array([0], dtype='>u2'))
+        both returned the same thing:
+        array([0], dtype=uint16)
+        even though their dtypes have different endianness.
+        '''
+        native_dtype = np.dtype(native)
+        non_native_dtype = native_dtype.newbyteorder()
+        non_native_repr = repr(np.array([1], non_native_dtype))
+        native_repr = repr(np.array([1], native_dtype))
+        # preserve the sensible default of only showing dtype if nonstandard
+        assert ('dtype' in native_repr) ^ (native_dtype in _typelessdata),\
+                ("an array's repr should show dtype if and only if the type "
+                 'of the array is NOT one of the standard types '
+                 '(e.g., int32, bool, float64).')
+        if non_native_dtype.itemsize > 1:
+            # if the type is >1 byte, the non-native endian version
+            # must show endianness.
+            assert non_native_repr != native_repr
+            assert f"dtype='{non_native_dtype.byteorder}" in non_native_repr
+
+    def test_linewidth_repr(self):
+        a = np.full(7, fill_value=2)
+        np.set_printoptions(linewidth=17)
+        assert_equal(
+            repr(a),
+            textwrap.dedent("""\
+            array([2, 2, 2,
+                   2, 2, 2,
+                   2])""")
+        )
+        np.set_printoptions(linewidth=17, legacy='1.13')
+        assert_equal(
+            repr(a),
+            textwrap.dedent("""\
+            array([2, 2, 2,
+                   2, 2, 2, 2])""")
+        )
+
+        a = np.full(8, fill_value=2)
+
+        np.set_printoptions(linewidth=18, legacy=False)
+        assert_equal(
+            repr(a),
+            textwrap.dedent("""\
+            array([2, 2, 2,
+                   2, 2, 2,
+                   2, 2])""")
+        )
+
+        np.set_printoptions(linewidth=18, legacy='1.13')
+        assert_equal(
+            repr(a),
+            textwrap.dedent("""\
+            array([2, 2, 2, 2,
+                   2, 2, 2, 2])""")
+        )
+
+    def test_linewidth_str(self):
+        a = np.full(18, fill_value=2)
+        np.set_printoptions(linewidth=18)
+        assert_equal(
+            str(a),
+            textwrap.dedent("""\
+            [2 2 2 2 2 2 2 2
+             2 2 2 2 2 2 2 2
+             2 2]""")
+        )
+        np.set_printoptions(linewidth=18, legacy='1.13')
+        assert_equal(
+            str(a),
+            textwrap.dedent("""\
+            [2 2 2 2 2 2 2 2 2
+             2 2 2 2 2 2 2 2 2]""")
+        )
+
+    def test_edgeitems(self):
+        np.set_printoptions(edgeitems=1, threshold=1)
+        a = np.arange(27).reshape((3, 3, 3))
+        assert_equal(
+            repr(a),
+            textwrap.dedent("""\
+            array([[[ 0, ...,  2],
+                    ...,
+                    [ 6, ...,  8]],
+
+                   ...,
+
+                   [[18, ..., 20],
+                    ...,
+                    [24, ..., 26]]], shape=(3, 3, 3))""")
+        )
+
+        b = np.zeros((3, 3, 1, 1))
+        assert_equal(
+            repr(b),
+            textwrap.dedent("""\
+            array([[[[0.]],
+
+                    ...,
+
+                    [[0.]]],
+
+
+                   ...,
+
+
+                   [[[0.]],
+
+                    ...,
+
+                    [[0.]]]], shape=(3, 3, 1, 1))""")
+        )
+
+        # 1.13 had extra trailing spaces, and was missing newlines
+        try:
+            np.set_printoptions(legacy='1.13')
+            assert_equal(repr(a), (
+                "array([[[ 0, ...,  2],\n"
+                "        ..., \n"
+                "        [ 6, ...,  8]],\n"
+                "\n"
+                "       ..., \n"
+                "       [[18, ..., 20],\n"
+                "        ..., \n"
+                "        [24, ..., 26]]])")
+            )
+            assert_equal(repr(b), (
+                "array([[[[ 0.]],\n"
+                "\n"
+                "        ..., \n"
+                "        [[ 0.]]],\n"
+                "\n"
+                "\n"
+                "       ..., \n"
+                "       [[[ 0.]],\n"
+                "\n"
+                "        ..., \n"
+                "        [[ 0.]]]])")
+            )
+        finally:
+            np.set_printoptions(legacy=False)
+
+    def test_edgeitems_structured(self):
+        np.set_printoptions(edgeitems=1, threshold=1)
+        A = np.arange(5 * 2 * 3, dtype="<i8").view([('i', "<i8", (5, 2, 3))])
+        reprA = (
+            "array([([[[ 0, ...,  2], [ 3, ...,  5]], ..., "
+            "[[24, ..., 26], [27, ..., 29]]],)],\n"
+            "      dtype=[('i', '<i8', (5, 2, 3))])"
+        )
+        assert_equal(repr(A), reprA)
+
+    def test_bad_args(self):
+        assert_raises(ValueError, np.set_printoptions, threshold=float('nan'))
+        assert_raises(TypeError, np.set_printoptions, threshold='1')
+        assert_raises(TypeError, np.set_printoptions, threshold=b'1')
+
+        assert_raises(TypeError, np.set_printoptions, precision='1')
+        assert_raises(TypeError, np.set_printoptions, precision=1.5)
+
+def test_unicode_object_array():
+    expected = "array(['é'], dtype=object)"
+    x = np.array(['\xe9'], dtype=object)
+    assert_equal(repr(x), expected)
+
+
+class TestContextManager:
+    def test_ctx_mgr(self):
+        # test that context manager actually works
+        with np.printoptions(precision=2):
+            s = str(np.array([2.0]) / 3)
+        assert_equal(s, '[0.67]')
+
+    def test_ctx_mgr_restores(self):
+        # test that print options are actually restored
+        opts = np.get_printoptions()
+        with np.printoptions(precision=opts['precision'] - 1,
+                             linewidth=opts['linewidth'] - 4):
+            pass
+        assert_equal(np.get_printoptions(), opts)
+
+    def test_ctx_mgr_exceptions(self):
+        # test that print options are restored even if an exception is raised
+        opts = np.get_printoptions()
+        try:
+            with np.printoptions(precision=2, linewidth=11):
+                raise ValueError
+        except ValueError:
+            pass
+        assert_equal(np.get_printoptions(), opts)
+
+    def test_ctx_mgr_as_smth(self):
+        opts = {"precision": 2}
+        with np.printoptions(**opts) as ctx:
+            saved_opts = ctx.copy()
+        assert_equal({k: saved_opts[k] for k in opts}, opts)
+
+
+@pytest.mark.parametrize("dtype", "bhilqpBHILQPefdgFDG")
+@pytest.mark.parametrize("value", [0, 1])
+def test_scalar_repr_numbers(dtype, value):
+    # Test NEP 51 scalar repr (and legacy option) for numeric types
+    dtype = np.dtype(dtype)
+    scalar = np.array(value, dtype=dtype)[()]
+    assert isinstance(scalar, np.generic)
+
+    string = str(scalar)
+    repr_string = string.strip("()")  # complex may have extra brackets
+    representation = repr(scalar)
+    if dtype.char == "g":
+        assert representation == f"np.longdouble('{repr_string}')"
+    elif dtype.char == 'G':
+        assert representation == f"np.clongdouble('{repr_string}')"
+    else:
+        normalized_name = np.dtype(f"{dtype.kind}{dtype.itemsize}").type.__name__
+        assert representation == f"np.{normalized_name}({repr_string})"
+
+    with np.printoptions(legacy="1.25"):
+        assert repr(scalar) == string
+
+
+@pytest.mark.parametrize("scalar, legacy_repr, representation", [
+        (np.True_, "True", "np.True_"),
+        (np.bytes_(b'a'), "b'a'", "np.bytes_(b'a')"),
+        (np.str_('a'), "'a'", "np.str_('a')"),
+        (np.datetime64("2012"),
+            "numpy.datetime64('2012')", "np.datetime64('2012')"),
+        (np.timedelta64(1, 's'), "numpy.timedelta64(1,'s')", "np.timedelta64(1,'s')"),
+        (np.void((True, 2), dtype="?,<i8"),
+            "(True, 2)",
+            "np.void((True, 2), dtype=[('f0', '?'), ('f1', '<i8')])"),
+        (np.void((1, 2), dtype="<f8,>f4"),
+            "(1., 2.)",
+            "np.void((1.0, 2.0), dtype=[('f0', '<f8'), ('f1', '>f4')])"),
+        (np.void(b'a'), r"void(b'\x61')", r"np.void(b'\x61')"),
+    ])
+def test_scalar_repr_special(scalar, legacy_repr, representation):
+    # Test NEP 51 scalar repr (and legacy option) for numeric types
+    assert repr(scalar) == representation
+
+    with np.printoptions(legacy="1.25"):
+        assert repr(scalar) == legacy_repr
+
+def test_scalar_void_float_str():
+    # Note that based on this currently we do not print the same as a tuple
+    # would, since the tuple would include the repr() inside for floats, but
+    # we do not do that.
+    scalar = np.void((1.0, 2.0), dtype=[('f0', '<f8'), ('f1', '>f4')])
+    assert str(scalar) == "(1.0, 2.0)"
+
+@pytest.mark.skipif(IS_WASM, reason="wasm doesn't support asyncio")
+def test_printoptions_asyncio_safe():
+    asyncio = pytest.importorskip("asyncio")
+
+    b = asyncio.Barrier(2)
+
+    async def legacy_113():
+        np.set_printoptions(legacy='1.13', precision=12)
+        await b.wait()
+        po = np.get_printoptions()
+        assert po['legacy'] == '1.13'
+        assert po['precision'] == 12
+        orig_linewidth = po['linewidth']
+        with np.printoptions(linewidth=34, legacy='1.21'):
+            po = np.get_printoptions()
+            assert po['legacy'] == '1.21'
+            assert po['precision'] == 12
+            assert po['linewidth'] == 34
+        po = np.get_printoptions()
+        assert po['linewidth'] == orig_linewidth
+        assert po['legacy'] == '1.13'
+        assert po['precision'] == 12
+
+    async def legacy_125():
+        np.set_printoptions(legacy='1.25', precision=7)
+        await b.wait()
+        po = np.get_printoptions()
+        assert po['legacy'] == '1.25'
+        assert po['precision'] == 7
+        orig_linewidth = po['linewidth']
+        with np.printoptions(linewidth=6, legacy='1.13'):
+            po = np.get_printoptions()
+            assert po['legacy'] == '1.13'
+            assert po['precision'] == 7
+            assert po['linewidth'] == 6
+        po = np.get_printoptions()
+        assert po['linewidth'] == orig_linewidth
+        assert po['legacy'] == '1.25'
+        assert po['precision'] == 7
+
+    async def main():
+        await asyncio.gather(legacy_125(), legacy_125())
+
+    loop = asyncio.new_event_loop()
+    asyncio.run(main())
+    loop.close()
+
+@pytest.mark.skipif(IS_WASM, reason="wasm doesn't support threads")
+@pytest.mark.thread_unsafe(reason="test is already explicitly multi-threaded")
+def test_multithreaded_array_printing():
+    # the dragon4 implementation uses a static scratch space for performance
+    # reasons this test makes sure it is set up in a thread-safe manner
+
+    run_threaded(TestPrintOptions().test_floatmode, 500)
+
+
+def test_user_defined_floating_dtype_printing_does_not_corrupt_precision():
+    """
+    Ensure that array printing does not use NumPy Dragon4 formatting
+    for user-defined floating dtypes, which would silently truncate
+    precision to float64.
+    """
+    # Quaddtype (<=1.0.0) may have a bug that leads to test failures elsewhere
+    # (this may also be an interplay of numpy/quaddtype but let's hope new
+    # quaddtype versions will fix it.)
+    from importlib.metadata import version
+
+    try:
+        quaddtype_version = version("numpy_quaddtype")
+    except Exception:
+        pytest.skip("numpy_quaddtype not installed")
+    else:
+        if _pep440.Version(quaddtype_version) <= _pep440.Version("1.0.0"):
+            pytest.skip("critical bug in quaddtype during import")
+
+    numpy_quaddtype = pytest.importorskip("numpy_quaddtype")
+
+    pi_str = "3.14159265358979323846264338327950288"
+    arr = np.array([pi_str], dtype=QuadPrecDType())
+    res = np.array(str(arr).strip("[] "), dtype=QuadPrecDType())
+    # Check that the string representation round-trips correctly.
+    assert_array_equal(res, arr)
+
+
+@pytest.mark.parametrize("sctype", [np.int8, np.float32, rational, rational2])
+def test_array_dtype_short_repr(sctype):
+    # Mainly test that rational/rational2 (both legacy dtypes) use short repr
+    # which in the end should just be the name for these (not default dtypes).
+    arr = np.zeros(1, dtype=sctype)
+    res = repr(arr)
+    assert f"dtype={sctype.__name__}" in res

v12x/pylib/numpy/_core/tests/test_casting_floatingpoint_errors.py

@@ -0,0 +1,154 @@
+import pytest
+from pytest import param
+
+import numpy as np
+from numpy.testing import IS_WASM
+
+
+def values_and_dtypes():
+    """
+    Generate value+dtype pairs that generate floating point errors during
+    casts.  The invalid casts to integers will generate "invalid" value
+    warnings, the float casts all generate "overflow".
+
+    (The Python int/float paths don't need to get tested in all the same
+    situations, but it does not hurt.)
+    """
+    # Casting to float16:
+    yield param(70000, "float16", id="int-to-f2")
+    yield param("70000", "float16", id="str-to-f2")
+    yield param(70000.0, "float16", id="float-to-f2")
+    yield param(np.longdouble(70000.), "float16", id="longdouble-to-f2")
+    yield param(np.float64(70000.), "float16", id="double-to-f2")
+    yield param(np.float32(70000.), "float16", id="float-to-f2")
+    # Casting to float32:
+    yield param(10**100, "float32", id="int-to-f4")
+    yield param(1e100, "float32", id="float-to-f2")
+    yield param(np.longdouble(1e300), "float32", id="longdouble-to-f2")
+    yield param(np.float64(1e300), "float32", id="double-to-f2")
+    # Casting to float64:
+    # If longdouble is double-double, its max can be rounded down to the double
+    # max.  So we correct the double spacing (a bit weird, admittedly):
+    max_ld = np.finfo(np.longdouble).max
+    spacing = np.spacing(np.nextafter(np.finfo("f8").max, 0))
+    if max_ld - spacing > np.finfo("f8").max:
+        yield param(np.finfo(np.longdouble).max, "float64",
+                    id="longdouble-to-f8")
+
+    # Cast to complex32:
+    yield param(2e300, "complex64", id="float-to-c8")
+    yield param(2e300 + 0j, "complex64", id="complex-to-c8")
+    yield param(2e300j, "complex64", id="complex-to-c8")
+    yield param(np.longdouble(2e300), "complex64", id="longdouble-to-c8")
+
+    # Invalid float to integer casts:
+    with np.errstate(over="ignore"):
+        for to_dt in np.typecodes["AllInteger"]:
+            for value in [np.inf, np.nan]:
+                for from_dt in np.typecodes["AllFloat"]:
+                    from_dt = np.dtype(from_dt)
+                    from_val = from_dt.type(value)
+
+                    yield param(from_val, to_dt, id=f"{from_val}-to-{to_dt}")
+
+
+def check_operations(dtype, value):
+    """
+    There are many dedicated paths in NumPy which cast and should check for
+    floating point errors which occurred during those casts.
+    """
+    if dtype.kind != 'i':
+        # These assignments use the stricter setitem logic:
+        def assignment():
+            arr = np.empty(3, dtype=dtype)
+            arr[0] = value
+
+        yield assignment
+
+        def fill():
+            arr = np.empty(3, dtype=dtype)
+            arr.fill(value)
+
+        yield fill
+
+    def copyto_scalar():
+        arr = np.empty(3, dtype=dtype)
+        np.copyto(arr, value, casting="unsafe")
+
+    yield copyto_scalar
+
+    def copyto():
+        arr = np.empty(3, dtype=dtype)
+        np.copyto(arr, np.array([value, value, value]), casting="unsafe")
+
+    yield copyto
+
+    def copyto_scalar_masked():
+        arr = np.empty(3, dtype=dtype)
+        np.copyto(arr, value, casting="unsafe",
+                  where=[True, False, True])
+
+    yield copyto_scalar_masked
+
+    def copyto_masked():
+        arr = np.empty(3, dtype=dtype)
+        np.copyto(arr, np.array([value, value, value]), casting="unsafe",
+                  where=[True, False, True])
+
+    yield copyto_masked
+
+    def direct_cast():
+        np.array([value, value, value]).astype(dtype)
+
+    yield direct_cast
+
+    def direct_cast_nd_strided():
+        arr = np.full((5, 5, 5), fill_value=value)[:, ::2, :]
+        arr.astype(dtype)
+
+    yield direct_cast_nd_strided
+
+    def boolean_array_assignment():
+        arr = np.empty(3, dtype=dtype)
+        arr[[True, False, True]] = np.array([value, value])
+
+    yield boolean_array_assignment
+
+    def integer_array_assignment():
+        arr = np.empty(3, dtype=dtype)
+        values = np.array([value, value])
+
+        arr[[0, 1]] = values
+
+    yield integer_array_assignment
+
+    def integer_array_assignment_with_subspace():
+        arr = np.empty((5, 3), dtype=dtype)
+        values = np.array([value, value, value])
+
+        arr[[0, 2]] = values
+
+    yield integer_array_assignment_with_subspace
+
+    def flat_assignment():
+        arr = np.empty((3,), dtype=dtype)
+        values = np.array([value, value, value])
+        arr.flat[:] = values
+
+    yield flat_assignment
+
+@pytest.mark.skipif(IS_WASM, reason="no wasm fp exception support")
+@pytest.mark.parametrize(["value", "dtype"], list(values_and_dtypes()))
+@pytest.mark.filterwarnings("ignore::numpy.exceptions.ComplexWarning")
+def test_floatingpoint_errors_casting(dtype, value):
+    dtype = np.dtype(dtype)
+    for operation in check_operations(dtype, value):
+        dtype = np.dtype(dtype)
+
+        match = "invalid" if dtype.kind in 'iu' else "overflow"
+        with pytest.warns(RuntimeWarning, match=match):
+            operation()
+
+        with np.errstate(all="raise"):
+            with pytest.raises(FloatingPointError, match=match):
+                operation()

v12x/pylib/numpy/_core/tests/test_casting_unittests.py

@@ -0,0 +1,970 @@
+"""
+The tests exercise the casting machinery in a more low-level manner.
+The reason is mostly to test a new implementation of the casting machinery.
+
+Unlike most tests in NumPy, these are closer to unit-tests rather
+than integration tests.
+"""
+
+import ctypes
+import enum
+import random
+import textwrap
+import warnings
+
+import pytest
+
+import numpy as np
+from numpy._core._multiarray_umath import _get_castingimpl as get_castingimpl
+from numpy.lib.stride_tricks import as_strided
+from numpy.testing import assert_array_equal, assert_equal
+
+# Simple skips object, parametric and long double (unsupported by struct)
+simple_dtypes = "?bhilqBHILQefdFD"
+if np.dtype("l").itemsize != np.dtype("q").itemsize:
+    # Remove l and L, the table was generated with 64bit linux in mind.
+    simple_dtypes = simple_dtypes.replace("l", "").replace("L", "")
+simple_dtypes = [type(np.dtype(c)) for c in simple_dtypes]
+
+
+def simple_dtype_instances():
+    params = []
+    for dtype_class in simple_dtypes:
+        dt = dtype_class()
+        params.append(pytest.param(dt, id=str(dt)))
+        if dt.byteorder != "|":
+            dt = dt.newbyteorder()
+            params.append(pytest.param(dt, id=str(dt)))
+    return params
+
+
+def get_expected_stringlength(dtype):
+    """Returns the string length when casting the basic dtypes to strings.
+    """
+    if dtype == np.bool:
+        return 5
+    if dtype.kind in "iu":
+        if dtype.itemsize == 1:
+            length = 3
+        elif dtype.itemsize == 2:
+            length = 5
+        elif dtype.itemsize == 4:
+            length = 10
+        elif dtype.itemsize == 8:
+            length = 20
+        else:
+            raise AssertionError(f"did not find expected length for {dtype}")
+
+        if dtype.kind == "i":
+            length += 1  # adds one character for the sign
+
+        return length
+
+    # Note: Can't do dtype comparison for longdouble on windows
+    if dtype.char == "g":
+        return 48
+    elif dtype.char == "G":
+        return 48 * 2
+    elif dtype.kind == "f":
+        return 32  # also for half apparently.
+    elif dtype.kind == "c":
+        return 32 * 2
+
+    raise AssertionError(f"did not find expected length for {dtype}")
+
+
+class Casting(enum.IntEnum):
+    no = 0
+    equiv = 1
+    safe = 2
+    same_kind = 3
+    unsafe = 4
+    same_value = 64
+
+
+same_value_dtypes = tuple(type(np.dtype(c)) for c in "?bhilqBHILQefdgFDG")
+
+def _get_cancast_table():
+    table = textwrap.dedent("""
+        X ? b h i l q B H I L Q e f d g F D G S U V O M m
+        ? # = = = = = = = = = = = = = = = = = = = = = . =
+        b . # = = = = . . . . . = = = = = = = = = = = . =
+        h . ~ # = = = . . . . . ~ = = = = = = = = = = . =
+        i . ~ ~ # = = . . . . . ~ ~ = = ~ = = = = = = . =
+        l . ~ ~ ~ # # . . . . . ~ ~ = = ~ = = = = = = . =
+        q . ~ ~ ~ # # . . . . . ~ ~ = = ~ = = = = = = . =
+        B . ~ = = = = # = = = = = = = = = = = = = = = . =
+        H . ~ ~ = = = ~ # = = = ~ = = = = = = = = = = . =
+        I . ~ ~ ~ = = ~ ~ # = = ~ ~ = = ~ = = = = = = . =
+        L . ~ ~ ~ ~ ~ ~ ~ ~ # # ~ ~ = = ~ = = = = = = . ~
+        Q . ~ ~ ~ ~ ~ ~ ~ ~ # # ~ ~ = = ~ = = = = = = . ~
+        e . . . . . . . . . . . # = = = = = = = = = = . .
+        f . . . . . . . . . . . ~ # = = = = = = = = = . .
+        d . . . . . . . . . . . ~ ~ # = ~ = = = = = = . .
+        g . . . . . . . . . . . ~ ~ ~ # ~ ~ = = = = = . .
+        F . . . . . . . . . . . . . . . # = = = = = = . .
+        D . . . . . . . . . . . . . . . ~ # = = = = = . .
+        G . . . . . . . . . . . . . . . ~ ~ # = = = = . .
+        S . . . . . . . . . . . . . . . . . . # = = = . .
+        U . . . . . . . . . . . . . . . . . . . # = = . .
+        V . . . . . . . . . . . . . . . . . . . . # = . .
+        O . . . . . . . . . . . . . . . . . . . . = # . .
+        M . . . . . . . . . . . . . . . . . . . . = = # .
+        m . . . . . . . . . . . . . . . . . . . . = = . #
+        """).strip().split("\n")
+    dtypes = [type(np.dtype(c)) for c in table[0][2::2]]
+
+    convert_cast = {".": Casting.unsafe, "~": Casting.same_kind,
+                    "=": Casting.safe, "#": Casting.equiv,
+                    " ": -1}
+
+    cancast = {}
+    for from_dt, row in zip(dtypes, table[1:]):
+        cancast[from_dt] = {}
+        for to_dt, c in zip(dtypes, row[2::2]):
+            cancast[from_dt][to_dt] = convert_cast[c]
+            # Of the types checked, numeric cast support same-value
+            if from_dt in same_value_dtypes and to_dt in same_value_dtypes:
+                cancast[from_dt][to_dt] |= Casting.same_value
+
+    return cancast
+
+
+CAST_TABLE = _get_cancast_table()
+
+
+class TestChanges:
+    """
+    These test cases exercise some behaviour changes
+    """
+    @pytest.mark.parametrize("string", ["S", "U"])
+    @pytest.mark.parametrize("floating", ["e", "f", "d", "g"])
+    def test_float_to_string(self, floating, string):
+        assert np.can_cast(floating, string)
+        # 100 is long enough to hold any formatted floating
+        assert np.can_cast(floating, f"{string}100")
+
+    def test_to_void(self):
+        # But in general, we do consider these safe:
+        assert np.can_cast("d", "V")
+        assert np.can_cast("S20", "V")
+
+        # Do not consider it a safe cast if the void is too smaller:
+        assert not np.can_cast("d", "V1")
+        assert not np.can_cast("S20", "V1")
+        assert not np.can_cast("U1", "V1")
+        # Structured to unstructured is just like any other:
+        assert np.can_cast("d,i", "V", casting="same_kind")
+        # Unstructured void to unstructured is actually no cast at all:
+        assert np.can_cast("V3", "V", casting="no")
+        assert np.can_cast("V0", "V", casting="no")
+
+
+class TestCasting:
+    size = 1500  # Best larger than NPY_LOWLEVEL_BUFFER_BLOCKSIZE * itemsize
+
+    def get_data(self, dtype1, dtype2):
+        if dtype2 is None or dtype1.itemsize >= dtype2.itemsize:
+            length = self.size // dtype1.itemsize
+        else:
+            length = self.size // dtype2.itemsize
+
+        # Assume that the base array is well enough aligned for all inputs.
+        arr1 = np.empty(length, dtype=dtype1)
+        assert arr1.flags.c_contiguous
+        assert arr1.flags.aligned
+
+        values = [random.randrange(-128, 128) for _ in range(length)]
+
+        for i, value in enumerate(values):
+            # Use item assignment to ensure this is not using casting:
+            if value < 0 and dtype1.kind == "u":
+                # Manually rollover unsigned integers (-1 -> int.max)
+                value = value + np.iinfo(dtype1).max + 1
+            arr1[i] = value
+
+        if dtype2 is None:
+            if dtype1.char == "?":
+                values = [bool(v) for v in values]
+            return arr1, values
+
+        if dtype2.char == "?":
+            values = [bool(v) for v in values]
+
+        arr2 = np.empty(length, dtype=dtype2)
+        assert arr2.flags.c_contiguous
+        assert arr2.flags.aligned
+
+        for i, value in enumerate(values):
+            # Use item assignment to ensure this is not using casting:
+            if value < 0 and dtype2.kind == "u":
+                # Manually rollover unsigned integers (-1 -> int.max)
+                value = value + np.iinfo(dtype2).max + 1
+            arr2[i] = value
+
+        return arr1, arr2, values
+
+    def get_data_variation(self, arr1, arr2, aligned=True, contig=True):
+        """
+        Returns a copy of arr1 that may be non-contiguous or unaligned, and a
+        matching array for arr2 (although not a copy).
+        """
+        if contig:
+            stride1 = arr1.dtype.itemsize
+            stride2 = arr2.dtype.itemsize
+        elif aligned:
+            stride1 = 2 * arr1.dtype.itemsize
+            stride2 = 2 * arr2.dtype.itemsize
+        else:
+            stride1 = arr1.dtype.itemsize + 1
+            stride2 = arr2.dtype.itemsize + 1
+
+        max_size1 = len(arr1) * 3 * arr1.dtype.itemsize + 1
+        max_size2 = len(arr2) * 3 * arr2.dtype.itemsize + 1
+        from_bytes = np.zeros(max_size1, dtype=np.uint8)
+        to_bytes = np.zeros(max_size2, dtype=np.uint8)
+
+        # Sanity check that the above is large enough:
+        assert stride1 * len(arr1) <= from_bytes.nbytes
+        assert stride2 * len(arr2) <= to_bytes.nbytes
+
+        if aligned:
+            new1 = as_strided(from_bytes[:-1].view(arr1.dtype),
+                              arr1.shape, (stride1,))
+            new2 = as_strided(to_bytes[:-1].view(arr2.dtype),
+                              arr2.shape, (stride2,))
+        else:
+            new1 = as_strided(from_bytes[1:].view(arr1.dtype),
+                              arr1.shape, (stride1,))
+            new2 = as_strided(to_bytes[1:].view(arr2.dtype),
+                              arr2.shape, (stride2,))
+
+        new1[...] = arr1
+
+        if not contig:
+            # Ensure we did not overwrite bytes that should not be written:
+            offset = arr1.dtype.itemsize if aligned else 0
+            buf = from_bytes[offset::stride1].tobytes()
+            assert buf.count(b"\0") == len(buf)
+
+        if contig:
+            assert new1.flags.c_contiguous
+            assert new2.flags.c_contiguous
+        else:
+            assert not new1.flags.c_contiguous
+            assert not new2.flags.c_contiguous
+
+        if aligned:
+            assert new1.flags.aligned
+            assert new2.flags.aligned
+        else:
+            assert not new1.flags.aligned or new1.dtype.alignment == 1
+            assert not new2.flags.aligned or new2.dtype.alignment == 1
+
+        return new1, new2
+
+    @pytest.mark.parametrize("from_Dt", simple_dtypes)
+    def test_simple_cancast(self, from_Dt):
+        for to_Dt in simple_dtypes:
+            cast = get_castingimpl(from_Dt, to_Dt)
+
+            for from_dt in [from_Dt(), from_Dt().newbyteorder()]:
+                default = cast._resolve_descriptors((from_dt, None))[1][1]
+                assert default == to_Dt()
+                del default
+
+                for to_dt in [to_Dt(), to_Dt().newbyteorder()]:
+                    casting, (from_res, to_res), view_off = (
+                            cast._resolve_descriptors((from_dt, to_dt)))
+                    assert type(from_res) is from_Dt
+                    assert type(to_res) is to_Dt
+                    if view_off is not None:
+                        # If a view is acceptable, this is "no" casting
+                        # and byte order must be matching.
+                        assert casting == Casting.no | Casting.same_value
+                        # The above table lists this as "equivalent", perhaps
+                        # with "same_value"
+                        v = CAST_TABLE[from_Dt][to_Dt] & ~Casting.same_value
+                        assert Casting.equiv == v
+                        # Note that to_res may not be the same as from_dt
+                        assert from_res.isnative == to_res.isnative
+                    else:
+                        if from_Dt == to_Dt:
+                            # Note that to_res may not be the same as from_dt
+                            assert from_res.isnative != to_res.isnative
+                        assert casting == CAST_TABLE[from_Dt][to_Dt]
+
+                    if from_Dt is to_Dt:
+                        assert from_dt is from_res
+                        assert to_dt is to_res
+
+    @pytest.mark.filterwarnings("ignore::numpy.exceptions.ComplexWarning")
+    @pytest.mark.parametrize("from_dt", simple_dtype_instances())
+    def test_simple_direct_casts(self, from_dt):
+        """
+        This test checks numeric direct casts for dtypes supported also by the
+        struct module (plus complex).  It tries to be test a wide range of
+        inputs, but skips over possibly undefined behaviour (e.g. int rollover).
+        Longdouble and CLongdouble are tested, but only using double precision.
+
+        If this test creates issues, it should possibly just be simplified
+        or even removed (checking whether unaligned/non-contiguous casts give
+        the same results is useful, though).
+        """
+        for to_dt in simple_dtype_instances():
+            to_dt = to_dt.values[0]
+            cast = get_castingimpl(type(from_dt), type(to_dt))
+
+            # print("from_dt", from_dt, "to_dt", to_dt)
+            casting, (from_res, to_res), view_off = cast._resolve_descriptors(
+                (from_dt, to_dt))
+
+            if from_res is not from_dt or to_res is not to_dt:
+                # Do not test this case, it is handled in multiple steps,
+                # each of which should is tested individually.
+                return
+
+            safe = casting <= Casting.safe
+            del from_res, to_res, casting
+
+            arr1, arr2, values = self.get_data(from_dt, to_dt)
+
+            # print("2", arr1, arr2, cast)
+            cast._simple_strided_call((arr1, arr2))
+            # print("3")
+
+            # Check via python list
+            assert arr2.tolist() == values
+
+            # Check that the same results are achieved for strided loops
+            arr1_o, arr2_o = self.get_data_variation(arr1, arr2, True, False)
+            cast._simple_strided_call((arr1_o, arr2_o))
+
+            assert_array_equal(arr2_o, arr2)
+            assert arr2_o.tobytes() == arr2.tobytes()
+
+            # Check if alignment makes a difference, but only if supported
+            # and only if the alignment can be wrong
+            if ((from_dt.alignment == 1 and to_dt.alignment == 1) or
+                    not cast._supports_unaligned):
+                return
+
+            arr1_o, arr2_o = self.get_data_variation(arr1, arr2, False, True)
+            cast._simple_strided_call((arr1_o, arr2_o))
+
+            assert_array_equal(arr2_o, arr2)
+            assert arr2_o.tobytes() == arr2.tobytes()
+
+            arr1_o, arr2_o = self.get_data_variation(arr1, arr2, False, False)
+            cast._simple_strided_call((arr1_o, arr2_o))
+
+            assert_array_equal(arr2_o, arr2)
+            assert arr2_o.tobytes() == arr2.tobytes()
+
+            del arr1_o, arr2_o, cast
+
+    @pytest.mark.parametrize("from_Dt", simple_dtypes)
+    def test_numeric_to_times(self, from_Dt):
+        # We currently only implement contiguous loops, so only need to
+        # test those.
+        from_dt = from_Dt()
+
+        time_dtypes = [np.dtype("M8"), np.dtype("M8[ms]"), np.dtype("M8[4D]"),
+                       np.dtype("m8"), np.dtype("m8[ms]"), np.dtype("m8[4D]")]
+        for time_dt in time_dtypes:
+            cast = get_castingimpl(type(from_dt), type(time_dt))
+
+            casting, (from_res, to_res), view_off = cast._resolve_descriptors(
+                (from_dt, time_dt))
+
+            assert from_res is from_dt
+            assert to_res is time_dt
+            del from_res, to_res
+
+            assert casting & CAST_TABLE[from_Dt][type(time_dt)]
+            assert view_off is None
+
+            int64_dt = np.dtype(np.int64)
+            arr1, arr2, values = self.get_data(from_dt, int64_dt)
+            arr2 = arr2.view(time_dt)
+            arr2[...] = np.datetime64("NaT", "D")
+
+            if time_dt == np.dtype("M8"):
+                # This is a bit of a strange path, and could probably be removed
+                arr1[-1] = 0  # ensure at least one value is not NaT
+
+                # The cast currently succeeds, but the values are invalid:
+                cast._simple_strided_call((arr1, arr2))
+                with pytest.raises(ValueError):
+                    str(arr2[-1])  # e.g. conversion to string fails
+                return
+
+            cast._simple_strided_call((arr1, arr2))
+
+            assert [int(v) for v in arr2.tolist()] == values
+
+            # Check that the same results are achieved for strided loops
+            arr1_o, arr2_o = self.get_data_variation(arr1, arr2, True, False)
+            cast._simple_strided_call((arr1_o, arr2_o))
+
+            assert_array_equal(arr2_o, arr2)
+            assert arr2_o.tobytes() == arr2.tobytes()
+
+    @pytest.mark.parametrize(
+            ["from_dt", "to_dt", "expected_casting", "expected_view_off",
+             "nom", "denom"],
+            [("M8[ns]", None, Casting.no, 0, 1, 1),
+             (str(np.dtype("M8[ns]").newbyteorder()), None,
+                  Casting.equiv, None, 1, 1),
+             ("M8", "M8[ms]", Casting.safe, 0, 1, 1),
+             # should be invalid cast:
+             ("M8[ms]", "M8", Casting.unsafe, None, 1, 1),
+             ("M8[5ms]", "M8[5ms]", Casting.no, 0, 1, 1),
+             ("M8[ns]", "M8[ms]", Casting.same_kind, None, 1, 10**6),
+             ("M8[ms]", "M8[ns]", Casting.safe, None, 10**6, 1),
+             ("M8[ms]", "M8[7ms]", Casting.same_kind, None, 1, 7),
+             ("M8[4D]", "M8[1M]", Casting.same_kind, None, None,
+                  # give full values based on NumPy 1.19.x
+                  [-2**63, 0, -1, 1314, -1315, 564442610]),
+             ("m8[ns]", None, Casting.no, 0, 1, 1),
+             (str(np.dtype("m8[ns]").newbyteorder()), None,
+                  Casting.equiv, None, 1, 1),
+             ("m8", "m8[ms]", Casting.safe, 0, 1, 1),
+             # should be invalid cast:
+             ("m8[5ms]", "m8[5ms]", Casting.no, 0, 1, 1),
+             ("m8[ns]", "m8[ms]", Casting.same_kind, None, 1, 10**6),
+             ("m8[ms]", "m8[ns]", Casting.safe, None, 10**6, 1),
+             ("m8[ms]", "m8[7ms]", Casting.same_kind, None, 1, 7),
+             ("m8[4D]", "m8[1M]", Casting.unsafe, None, None,
+                  # give full values based on NumPy 1.19.x
+                  [-2**63, 0, 0, 1314, -1315, 564442610])])
+    def test_time_to_time(self, from_dt, to_dt,
+                          expected_casting, expected_view_off,
+                          nom, denom):
+        from_dt = np.dtype(from_dt)
+        if to_dt is not None:
+            to_dt = np.dtype(to_dt)
+
+        # Test a few values for casting (results generated with NumPy 1.19)
+        values = np.array([-2**63, 1, 2**63 - 1, 10000, -10000, 2**32])
+        values = values.astype(np.dtype("int64").newbyteorder(from_dt.byteorder))
+        assert values.dtype.byteorder == from_dt.byteorder
+        assert np.isnat(values.view(from_dt)[0])
+
+        DType = type(from_dt)
+        cast = get_castingimpl(DType, DType)
+        casting, (from_res, to_res), view_off = cast._resolve_descriptors(
+                (from_dt, to_dt))
+        assert from_res is from_dt
+        assert to_res is to_dt or to_dt is None
+        assert casting == expected_casting
+        assert view_off == expected_view_off
+
+        if nom is not None:
+            expected_out = (values * nom // denom).view(to_res)
+            if to_dt == np.dtype("M8"):
+                with pytest.warns(
+                    DeprecationWarning,
+                    match="The 'generic' unit for NumPy timedelta is deprecated",
+                ):
+                    expected_out[0] = "NaT"
+            else:
+                expected_out[0] = "NaT"
+        else:
+            expected_out = np.empty_like(values)
+            expected_out[...] = denom
+            expected_out = expected_out.view(to_dt)
+
+        orig_arr = values.view(from_dt)
+        orig_out = np.empty_like(expected_out)
+
+        if casting == Casting.unsafe and (to_dt == "m8" or to_dt == "M8"):
+            # Casting from non-generic to generic units is an error and should
+            # probably be reported as an invalid cast earlier.
+            with pytest.raises(ValueError):
+                cast._simple_strided_call((orig_arr, orig_out))
+            return
+
+        for aligned in [True, True]:
+            for contig in [True, True]:
+                arr, out = self.get_data_variation(
+                        orig_arr, orig_out, aligned, contig)
+                out[...] = 0
+                try:
+                    cast._simple_strided_call((arr, out))
+                except OverflowError:
+                    # Extreme values (e.g. INT64_MAX) can overflow when
+                    # scaled by the unit conversion factor. gh-16352
+                    break
+                assert_array_equal(out.view("int64"), expected_out.view("int64"))
+
+    def string_with_modified_length(self, dtype, change_length):
+        fact = 1 if dtype.char == "S" else 4
+        length = dtype.itemsize // fact + change_length
+        return np.dtype(f"{dtype.byteorder}{dtype.char}{length}")
+
+    @pytest.mark.parametrize("other_DT", simple_dtypes)
+    @pytest.mark.parametrize("string_char", ["S", "U"])
+    def test_string_cancast(self, other_DT, string_char):
+        fact = 1 if string_char == "S" else 4
+
+        string_DT = type(np.dtype(string_char))
+        cast = get_castingimpl(other_DT, string_DT)
+
+        other_dt = other_DT()
+        expected_length = get_expected_stringlength(other_dt)
+        string_dt = np.dtype(f"{string_char}{expected_length}")
+
+        safety, (res_other_dt, res_dt), view_off = cast._resolve_descriptors(
+                (other_dt, None))
+        assert res_dt.itemsize == expected_length * fact
+        assert safety == Casting.safe  # we consider to string casts "safe"
+        assert view_off is None
+        assert isinstance(res_dt, string_DT)
+
+        # These casts currently implement changing the string length, so
+        # check the cast-safety for too long/fixed string lengths:
+        for change_length in [-1, 0, 1]:
+            if change_length >= 0:
+                expected_safety = Casting.safe
+            else:
+                expected_safety = Casting.same_kind
+
+            to_dt = self.string_with_modified_length(string_dt, change_length)
+            safety, (_, res_dt), view_off = cast._resolve_descriptors(
+                    (other_dt, to_dt))
+            assert res_dt is to_dt
+            assert safety == expected_safety
+            assert view_off is None
+
+        # The opposite direction is always considered unsafe:
+        cast = get_castingimpl(string_DT, other_DT)
+
+        safety, _, view_off = cast._resolve_descriptors((string_dt, other_dt))
+        assert safety == Casting.unsafe
+        assert view_off is None
+
+        cast = get_castingimpl(string_DT, other_DT)
+        safety, (_, res_dt), view_off = cast._resolve_descriptors(
+            (string_dt, None))
+        assert safety == Casting.unsafe
+        assert view_off is None
+        assert other_dt is res_dt  # returns the singleton for simple dtypes
+
+    @pytest.mark.parametrize("string_char", ["S", "U"])
+    @pytest.mark.parametrize("other_dt", simple_dtype_instances())
+    def test_simple_string_casts_roundtrip(self, other_dt, string_char):
+        """
+        Tests casts from and to string by checking the roundtripping property.
+
+        The test also covers some string to string casts (but not all).
+
+        If this test creates issues, it should possibly just be simplified
+        or even removed (checking whether unaligned/non-contiguous casts give
+        the same results is useful, though).
+        """
+        string_DT = type(np.dtype(string_char))
+
+        cast = get_castingimpl(type(other_dt), string_DT)
+        cast_back = get_castingimpl(string_DT, type(other_dt))
+        _, (res_other_dt, string_dt), _ = cast._resolve_descriptors(
+                (other_dt, None))
+
+        if res_other_dt is not other_dt:
+            # do not support non-native byteorder, skip test in that case
+            assert other_dt.byteorder != res_other_dt.byteorder
+            return
+
+        orig_arr, values = self.get_data(other_dt, None)
+        str_arr = np.zeros(len(orig_arr), dtype=string_dt)
+        string_dt_short = self.string_with_modified_length(string_dt, -1)
+        str_arr_short = np.zeros(len(orig_arr), dtype=string_dt_short)
+        string_dt_long = self.string_with_modified_length(string_dt, 1)
+        str_arr_long = np.zeros(len(orig_arr), dtype=string_dt_long)
+
+        assert not cast._supports_unaligned  # if support is added, should test
+        assert not cast_back._supports_unaligned
+
+        for contig in [True, False]:
+            other_arr, str_arr = self.get_data_variation(
+                orig_arr, str_arr, True, contig)
+            _, str_arr_short = self.get_data_variation(
+                orig_arr, str_arr_short.copy(), True, contig)
+            _, str_arr_long = self.get_data_variation(
+                orig_arr, str_arr_long, True, contig)
+
+            cast._simple_strided_call((other_arr, str_arr))
+
+            cast._simple_strided_call((other_arr, str_arr_short))
+            assert_array_equal(str_arr.astype(string_dt_short), str_arr_short)
+
+            cast._simple_strided_call((other_arr, str_arr_long))
+            assert_array_equal(str_arr, str_arr_long)
+
+            if other_dt.kind == "b":
+                # Booleans do not roundtrip
+                continue
+
+            other_arr[...] = 0
+            cast_back._simple_strided_call((str_arr, other_arr))
+            assert_array_equal(orig_arr, other_arr)
+
+            other_arr[...] = 0
+            cast_back._simple_strided_call((str_arr_long, other_arr))
+            assert_array_equal(orig_arr, other_arr)
+
+    @pytest.mark.parametrize("other_dt", ["S8", "<U8", ">U8"])
+    @pytest.mark.parametrize("string_char", ["S", "U"])
+    def test_string_to_string_cancast(self, other_dt, string_char):
+        other_dt = np.dtype(other_dt)
+
+        fact = 1 if string_char == "S" else 4
+        div = 1 if other_dt.char == "S" else 4
+
+        string_DT = type(np.dtype(string_char))
+        cast = get_castingimpl(type(other_dt), string_DT)
+
+        expected_length = other_dt.itemsize // div
+        string_dt = np.dtype(f"{string_char}{expected_length}")
+
+        safety, (res_other_dt, res_dt), view_off = cast._resolve_descriptors(
+                (other_dt, None))
+        assert res_dt.itemsize == expected_length * fact
+        assert isinstance(res_dt, string_DT)
+
+        expected_view_off = None
+        if other_dt.char == string_char:
+            if other_dt.isnative:
+                expected_safety = Casting.no
+                expected_view_off = 0
+            else:
+                expected_safety = Casting.equiv
+        elif string_char == "U":
+            expected_safety = Casting.safe
+        else:
+            expected_safety = Casting.unsafe
+
+        assert view_off == expected_view_off
+        assert expected_safety == safety
+
+        for change_length in [-1, 0, 1]:
+            to_dt = self.string_with_modified_length(string_dt, change_length)
+            safety, (_, res_dt), view_off = cast._resolve_descriptors(
+                    (other_dt, to_dt))
+
+            assert res_dt is to_dt
+            if change_length <= 0:
+                assert view_off == expected_view_off
+            else:
+                assert view_off is None
+            if expected_safety == Casting.unsafe:
+                assert safety == expected_safety
+            elif change_length < 0:
+                assert safety == Casting.same_kind
+            elif change_length == 0:
+                assert safety == expected_safety
+            elif change_length > 0:
+                assert safety == Casting.safe
+
+    @pytest.mark.parametrize("order1", [">", "<"])
+    @pytest.mark.parametrize("order2", [">", "<"])
+    def test_unicode_byteswapped_cast(self, order1, order2):
+        # Very specific tests (not using the castingimpl directly)
+        # that tests unicode bytedwaps including for unaligned array data.
+        dtype1 = np.dtype(f"{order1}U30")
+        dtype2 = np.dtype(f"{order2}U30")
+        data1 = np.empty(30 * 4 + 1, dtype=np.uint8)[1:].view(dtype1)
+        data2 = np.empty(30 * 4 + 1, dtype=np.uint8)[1:].view(dtype2)
+        if dtype1.alignment != 1:
+            # alignment should always be >1, but skip the check if not
+            assert not data1.flags.aligned
+            assert not data2.flags.aligned
+
+        element = "this is a ünicode string‽"
+        data1[()] = element
+        # Test both `data1` and `data1.copy()`  (which should be aligned)
+        for data in [data1, data1.copy()]:
+            data2[...] = data1
+            assert data2[()] == element
+            assert data2.copy()[()] == element
+
+    def test_void_to_string_special_case(self):
+        # Cover a small special case in void to string casting that could
+        # probably just as well be turned into an error (compare
+        # `test_object_to_parametric_internal_error` below).
+        assert np.array([], dtype="V5").astype("S").dtype.itemsize == 5
+        assert np.array([], dtype="V5").astype("U").dtype.itemsize == 4 * 5
+
+    def test_object_to_parametric_internal_error(self):
+        # We reject casting from object to a parametric type, without
+        # figuring out the correct instance first.
+        object_dtype = type(np.dtype(object))
+        other_dtype = type(np.dtype(str))
+        cast = get_castingimpl(object_dtype, other_dtype)
+        with pytest.raises(TypeError,
+                    match="casting from object to the parametric DType"):
+            cast._resolve_descriptors((np.dtype("O"), None))
+
+    @pytest.mark.parametrize("dtype", simple_dtype_instances())
+    def test_object_and_simple_resolution(self, dtype):
+        # Simple test to exercise the cast when no instance is specified
+        object_dtype = type(np.dtype(object))
+        cast = get_castingimpl(object_dtype, type(dtype))
+
+        safety, (_, res_dt), view_off = cast._resolve_descriptors(
+                (np.dtype("O"), dtype))
+        assert safety == Casting.unsafe
+        assert view_off is None
+        assert res_dt is dtype
+
+        safety, (_, res_dt), view_off = cast._resolve_descriptors(
+                (np.dtype("O"), None))
+        assert safety == Casting.unsafe
+        assert view_off is None
+        assert res_dt == dtype.newbyteorder("=")
+
+    @pytest.mark.parametrize("dtype", simple_dtype_instances())
+    def test_simple_to_object_resolution(self, dtype):
+        # Simple test to exercise the cast when no instance is specified
+        object_dtype = type(np.dtype(object))
+        cast = get_castingimpl(type(dtype), object_dtype)
+
+        safety, (_, res_dt), view_off = cast._resolve_descriptors(
+                (dtype, None))
+        assert safety == Casting.safe
+        assert view_off is None
+        assert res_dt is np.dtype("O")
+
+    @pytest.mark.parametrize("casting", ["no", "unsafe"])
+    def test_void_and_structured_with_subarray(self, casting):
+        # test case corresponding to gh-19325
+        dtype = np.dtype([("foo", "<f4", (3, 2))])
+        expected = casting == "unsafe"
+        assert np.can_cast("V4", dtype, casting=casting) == expected
+        assert np.can_cast(dtype, "V4", casting=casting) == expected
+
+    @pytest.mark.parametrize(["to_dt", "expected_off"],
+            [  # Same as `from_dt` but with both fields shifted:
+             (np.dtype({"names": ["a", "b"], "formats": ["i4", "f4"],
+                        "offsets": [0, 4]}), 2),
+             # Additional change of the names
+             (np.dtype({"names": ["b", "a"], "formats": ["i4", "f4"],
+                        "offsets": [0, 4]}), 2),
+             # Incompatible field offset change
+             (np.dtype({"names": ["b", "a"], "formats": ["i4", "f4"],
+                        "offsets": [0, 6]}), None)])
+    def test_structured_field_offsets(self, to_dt, expected_off):
+        # This checks the cast-safety and view offset for swapped and "shifted"
+        # fields which are viewable
+        from_dt = np.dtype({"names": ["a", "b"],
+                            "formats": ["i4", "f4"],
+                            "offsets": [2, 6]})
+        cast = get_castingimpl(type(from_dt), type(to_dt))
+        safety, _, view_off = cast._resolve_descriptors((from_dt, to_dt))
+        if from_dt.names == to_dt.names:
+            assert safety == Casting.equiv
+        else:
+            assert safety == Casting.safe
+        # Shifting the original data pointer by -2 will align both by
+        # effectively adding 2 bytes of spacing before `from_dt`.
+        assert view_off == expected_off
+
+    @pytest.mark.parametrize(("from_dt", "to_dt", "expected_off"), [
+            # Subarray cases:
+            ("i", "(1,1)i", 0),
+            ("(1,1)i", "i", 0),
+            ("(2,1)i", "(2,1)i", 0),
+            # field cases (field to field is tested explicitly also):
+            # Not considered viewable, because a negative offset would allow
+            # may structured dtype to indirectly access invalid memory.
+            ("i", {"names": ["a"], "formats": ["i"], "offsets": [2]}, None),
+            ({"names": ["a"], "formats": ["i"], "offsets": [2]}, "i", 2),
+            # Currently considered not viewable, due to multiple fields
+            # even though they overlap (maybe we should not allow that?)
+            ("i", {"names": ["a", "b"], "formats": ["i", "i"], "offsets": [2, 2]},
+             None),
+            # different number of fields can't work, should probably just fail
+            # so it never reports "viewable":
+            ("i,i", "i,i,i", None),
+            # Unstructured void cases:
+            ("i4", "V3", 0),  # void smaller or equal
+            ("i4", "V4", 0),  # void smaller or equal
+            ("i4", "V10", None),  # void is larger (no view)
+            ("O", "V4", None),  # currently reject objects for view here.
+            ("O", "V8", None),  # currently reject objects for view here.
+            ("V4", "V3", 0),
+            ("V4", "V4", 0),
+            ("V3", "V4", None),
+            # Note that currently void-to-other cast goes via byte-strings
+            # and is not a "view" based cast like the opposite direction:
+            ("V4", "i4", None),
+            # completely invalid/impossible cast:
+            ("i,i", "i,i,i", None),
+        ])
+    def test_structured_view_offsets_parametric(
+            self, from_dt, to_dt, expected_off):
+        # TODO: While this test is fairly thorough, right now, it does not
+        # really test some paths that may have nonzero offsets (they don't
+        # really exists).
+        from_dt = np.dtype(from_dt)
+        to_dt = np.dtype(to_dt)
+        cast = get_castingimpl(type(from_dt), type(to_dt))
+        _, _, view_off = cast._resolve_descriptors((from_dt, to_dt))
+        assert view_off == expected_off
+
+    @pytest.mark.parametrize("dtype", np.typecodes["All"])
+    def test_object_casts_NULL_None_equivalence(self, dtype):
+        # None to <other> casts may succeed or fail, but a NULL'ed array must
+        # behave the same as one filled with None's.
+        arr_normal = np.array([None] * 5)
+        arr_NULLs = np.empty_like(arr_normal)
+        ctypes.memset(arr_NULLs.ctypes.data, 0, arr_NULLs.nbytes)
+        # If the check fails (maybe it should) the test would lose its purpose:
+        assert arr_NULLs.tobytes() == b"\x00" * arr_NULLs.nbytes
+
+        try:
+            if dtype == "M":
+                dtype = "M[D]"
+            expected = arr_normal.astype(dtype)
+        except TypeError:
+            with pytest.raises(TypeError):
+                arr_NULLs.astype(dtype)
+        else:
+            assert_array_equal(expected, arr_NULLs.astype(dtype))
+
+    @pytest.mark.parametrize("dtype",
+            np.typecodes["AllInteger"] + np.typecodes["AllFloat"])
+    def test_nonstandard_bool_to_other(self, dtype):
+        # simple test for casting bool_ to numeric types, which should not
+        # expose the detail that NumPy bools can sometimes take values other
+        # than 0 and 1.  See also gh-19514.
+        nonstandard_bools = np.array([0, 3, -7], dtype=np.int8).view(bool)
+        res = nonstandard_bools.astype(dtype)
+        expected = [0, 1, 1]
+        assert_array_equal(res, expected)
+
+    @pytest.mark.parametrize("to_dtype",
+            np.typecodes["AllInteger"] + np.typecodes["AllFloat"])
+    @pytest.mark.parametrize("from_dtype",
+            np.typecodes["AllInteger"] + np.typecodes["AllFloat"])
+    @pytest.mark.filterwarnings("ignore::numpy.exceptions.ComplexWarning")
+    def test_same_value_overflow(self, from_dtype, to_dtype):
+        if from_dtype == to_dtype:
+            return
+        top1 = 0
+        top2 = 0
+        try:
+            top1 = np.iinfo(from_dtype).max
+        except ValueError:
+            top1 = np.finfo(from_dtype).max
+        try:
+            top2 = np.iinfo(to_dtype).max
+        except ValueError:
+            top2 = np.finfo(to_dtype).max
+        # No need to test if top2 > top1, since the test will also do the
+        # reverse dtype matching. Catch then warning if the comparison warns,
+        # i.e. np.int16(65535) < np.float16(6.55e4)
+        with warnings.catch_warnings(record=True):
+            warnings.simplefilter("always", RuntimeWarning)
+            if top2 >= top1:
+                # will be tested when the dtypes are reversed
+                return
+        # Happy path
+        arr1 = np.array([0] * 10, dtype=from_dtype)
+        arr2 = np.array([0] * 10, dtype=to_dtype)
+        arr1_astype = arr1.astype(to_dtype, casting='same_value')
+        assert_equal(arr1_astype, arr2, strict=True)
+        # Make it overflow, both aligned and unaligned
+        arr1[0] = top1
+        aligned = np.empty(arr1.itemsize * arr1.size + 1, 'uint8')
+        unaligned = aligned[1:].view(arr1.dtype)
+        unaligned[:] = arr1
+        with pytest.raises(ValueError):
+            # Casting float to float with overflow should raise
+            # RuntimeWarning (fperror)
+            # Casting float to int with overflow sometimes raises
+            # RuntimeWarning (fperror)
+            # Casting with overflow  and 'same_value', should raise ValueError
+            with warnings.catch_warnings(record=True) as w:
+                warnings.simplefilter("always", RuntimeWarning)
+                arr1.astype(to_dtype, casting='same_value')
+            assert len(w) < 2
+        with pytest.raises(ValueError):
+            # again, unaligned
+            with warnings.catch_warnings(record=True) as w:
+                warnings.simplefilter("always", RuntimeWarning)
+                unaligned.astype(to_dtype, casting='same_value')
+            assert len(w) < 2
+
+    @pytest.mark.parametrize("to_dtype",
+            np.typecodes["AllInteger"])
+    @pytest.mark.parametrize("from_dtype",
+            np.typecodes["AllFloat"])
+    @pytest.mark.filterwarnings("ignore::RuntimeWarning")
+    def test_same_value_float_to_int(self, from_dtype, to_dtype):
+        # Should not raise, since the values can round trip
+        arr1 = np.arange(10, dtype=from_dtype)
+        aligned = np.empty(arr1.itemsize * arr1.size + 1, 'uint8')
+        unaligned = aligned[1:].view(arr1.dtype)
+        unaligned[:] = arr1
+        arr2 = np.arange(10, dtype=to_dtype)
+        assert_array_equal(arr1.astype(to_dtype, casting='same_value'), arr2)
+        assert_array_equal(unaligned.astype(to_dtype, casting='same_value'), arr2)
+
+        # Should raise, since values cannot round trip. Might warn too about
+        # FPE errors
+        arr1_66 = arr1 + 0.666
+        unaligned_66 = unaligned + 0.66
+        with pytest.raises(ValueError):
+            arr1_66.astype(to_dtype, casting='same_value')
+        with pytest.raises(ValueError):
+            unaligned_66.astype(to_dtype, casting='same_value')
+
+    @pytest.mark.parametrize("to_dtype",
+            np.typecodes["AllInteger"])
+    @pytest.mark.parametrize("from_dtype",
+            np.typecodes["AllFloat"])
+    @pytest.mark.filterwarnings("ignore::RuntimeWarning")
+    def test_same_value_float_to_int_scalar(self, from_dtype, to_dtype):
+        # Should not raise, since the values can round trip
+        s1 = np.array(10, dtype=from_dtype)
+        assert s1.astype(to_dtype, casting='same_value') == 10
+
+        # Should raise, since values cannot round trip
+        s1_66 = s1 + 0.666
+        with pytest.raises(ValueError):
+            s1_66.astype(to_dtype, casting='same_value')
+
+    @pytest.mark.parametrize("value", [np.nan, np.inf, -np.inf])
+    @pytest.mark.filterwarnings("ignore::numpy.exceptions.ComplexWarning")
+    @pytest.mark.filterwarnings("ignore::RuntimeWarning")
+    def test_same_value_naninf(self, value):
+        # These work, but may trigger FPE warnings on macOS
+        np.array([value], dtype=np.half).astype(np.cdouble, casting='same_value')
+        np.array([value], dtype=np.half).astype(np.double, casting='same_value')
+        np.array([value], dtype=np.float32).astype(np.cdouble, casting='same_value')
+        np.array([value], dtype=np.float32).astype(np.double, casting='same_value')
+        np.array([value], dtype=np.float32).astype(np.half, casting='same_value')
+        np.array([value], dtype=np.complex64).astype(np.half, casting='same_value')
+        # These fail
+        with pytest.raises(ValueError):
+            np.array([value], dtype=np.half).astype(np.int64, casting='same_value')
+        with pytest.raises(ValueError):
+            np.array([value], dtype=np.complex64).astype(np.int64, casting='same_value')
+        with pytest.raises(ValueError):
+            np.array([value], dtype=np.float32).astype(np.int64, casting='same_value')
+
+    @pytest.mark.filterwarnings("ignore::numpy.exceptions.ComplexWarning")
+    def test_same_value_complex(self):
+        arr = np.array([complex(1, 1)], dtype=np.cdouble)
+        # This works
+        arr.astype(np.complex64, casting='same_value')
+        # Casting with a non-zero imag part fails
+        with pytest.raises(ValueError):
+            arr.astype(np.float32, casting='same_value')
+
+    def test_same_value_scalar(self):
+        i = np.array(123, dtype=np.int64)
+        f = np.array(123, dtype=np.float64)
+        assert i.astype(np.float64, casting='same_value') == f
+        assert f.astype(np.int64, casting='same_value') == f

v12x/pylib/numpy/_core/tests/test_conversion_utils.py

@@ -0,0 +1,209 @@
+"""
+Tests for numpy/_core/src/multiarray/conversion_utils.c
+"""
+import re
+
+import pytest
+
+import numpy._core._multiarray_tests as mt
+from numpy._core.multiarray import CLIP, RAISE, WRAP
+from numpy.testing import assert_raises
+
+
+class StringConverterTestCase:
+    allow_bytes = True
+    case_insensitive = True
+    exact_match = False
+    warn = True
+
+    def _check_value_error(self, val):
+        pattern = fr'\(got {re.escape(repr(val))}\)'
+        with pytest.raises(ValueError, match=pattern) as exc:
+            self.conv(val)
+
+    def _check_conv_assert_warn(self, val, expected):
+        if self.warn:
+            with assert_raises(ValueError) as exc:
+                assert self.conv(val) == expected
+        else:
+            assert self.conv(val) == expected
+
+    def _check(self, val, expected):
+        """Takes valid non-deprecated inputs for converters,
+        runs converters on inputs, checks correctness of outputs,
+        warnings and errors"""
+        assert self.conv(val) == expected
+
+        if self.allow_bytes:
+            assert self.conv(val.encode('ascii')) == expected
+        else:
+            with pytest.raises(TypeError):
+                self.conv(val.encode('ascii'))
+
+        if len(val) != 1:
+            if self.exact_match:
+                self._check_value_error(val[:1])
+                self._check_value_error(val + '\0')
+            else:
+                self._check_conv_assert_warn(val[:1], expected)
+
+        if self.case_insensitive:
+            if val != val.lower():
+                self._check_conv_assert_warn(val.lower(), expected)
+            if val != val.upper():
+                self._check_conv_assert_warn(val.upper(), expected)
+        else:
+            if val != val.lower():
+                self._check_value_error(val.lower())
+            if val != val.upper():
+                self._check_value_error(val.upper())
+
+    def test_wrong_type(self):
+        # common cases which apply to all the below
+        with pytest.raises(TypeError):
+            self.conv({})
+        with pytest.raises(TypeError):
+            self.conv([])
+
+    def test_wrong_value(self):
+        # nonsense strings
+        self._check_value_error('')
+        self._check_value_error('\N{greek small letter pi}')
+
+        if self.allow_bytes:
+            self._check_value_error(b'')
+            # bytes which can't be converted to strings via utf8
+            self._check_value_error(b"\xFF")
+        if self.exact_match:
+            self._check_value_error("there's no way this is supported")
+
+
+class TestByteorderConverter(StringConverterTestCase):
+    """ Tests of PyArray_ByteorderConverter """
+    conv = mt.run_byteorder_converter
+    warn = False
+
+    def test_valid(self):
+        for s in ['big', '>']:
+            self._check(s, 'NPY_BIG')
+        for s in ['little', '<']:
+            self._check(s, 'NPY_LITTLE')
+        for s in ['native', '=']:
+            self._check(s, 'NPY_NATIVE')
+        for s in ['ignore', '|']:
+            self._check(s, 'NPY_IGNORE')
+        for s in ['swap']:
+            self._check(s, 'NPY_SWAP')
+
+
+class TestSortkindConverter(StringConverterTestCase):
+    """ Tests of PyArray_SortkindConverter """
+    conv = mt.run_sortkind_converter
+    warn = False
+
+    def test_valid(self):
+        self._check('quicksort', 'NPY_QUICKSORT')
+        self._check('heapsort', 'NPY_HEAPSORT')
+        self._check('mergesort', 'NPY_STABLESORT')  # alias
+        self._check('stable', 'NPY_STABLESORT')
+
+
+class TestSelectkindConverter(StringConverterTestCase):
+    """ Tests of PyArray_SelectkindConverter """
+    conv = mt.run_selectkind_converter
+    case_insensitive = False
+    exact_match = True
+
+    def test_valid(self):
+        self._check('introselect', 'NPY_INTROSELECT')
+
+
+class TestSearchsideConverter(StringConverterTestCase):
+    """ Tests of PyArray_SearchsideConverter """
+    conv = mt.run_searchside_converter
+
+    def test_valid(self):
+        self._check('left', 'NPY_SEARCHLEFT')
+        self._check('right', 'NPY_SEARCHRIGHT')
+
+
+class TestOrderConverter(StringConverterTestCase):
+    """ Tests of PyArray_OrderConverter """
+    conv = mt.run_order_converter
+    warn = False
+
+    def test_valid(self):
+        self._check('c', 'NPY_CORDER')
+        self._check('f', 'NPY_FORTRANORDER')
+        self._check('a', 'NPY_ANYORDER')
+        self._check('k', 'NPY_KEEPORDER')
+
+    def test_flatten_invalid_order(self):
+        # invalid after gh-14596
+        with pytest.raises(ValueError):
+            self.conv('Z')
+        for order in [False, True, 0, 8]:
+            with pytest.raises(TypeError):
+                self.conv(order)
+
+
+class TestClipmodeConverter(StringConverterTestCase):
+    """ Tests of PyArray_ClipmodeConverter """
+    conv = mt.run_clipmode_converter
+
+    def test_valid(self):
+        self._check('clip', 'NPY_CLIP')
+        self._check('wrap', 'NPY_WRAP')
+        self._check('raise', 'NPY_RAISE')
+
+        # integer values allowed here
+        assert self.conv(CLIP) == 'NPY_CLIP'
+        assert self.conv(WRAP) == 'NPY_WRAP'
+        assert self.conv(RAISE) == 'NPY_RAISE'
+
+
+class TestCastingConverter(StringConverterTestCase):
+    """ Tests of PyArray_CastingConverter """
+    conv = mt.run_casting_converter
+    case_insensitive = False
+    exact_match = True
+
+    def test_valid(self):
+        self._check("no", "NPY_NO_CASTING")
+        self._check("equiv", "NPY_EQUIV_CASTING")
+        self._check("safe", "NPY_SAFE_CASTING")
+        self._check("unsafe", "NPY_UNSAFE_CASTING")
+        self._check("same_kind", "NPY_SAME_KIND_CASTING")
+
+    def test_invalid(self):
+        # Currently, 'same_value' is supported only in ndarray.astype
+        self._check_value_error("same_value")
+
+class TestIntpConverter:
+    """ Tests of PyArray_IntpConverter """
+    conv = mt.run_intp_converter
+
+    def test_basic(self):
+        assert self.conv(1) == (1,)
+        assert self.conv((1, 2)) == (1, 2)
+        assert self.conv([1, 2]) == (1, 2)
+        assert self.conv(()) == ()
+
+    def test_none(self):
+        with pytest.raises(TypeError):
+            assert self.conv(None) == ()
+
+    def test_float(self):
+        with pytest.raises(TypeError):
+            self.conv(1.0)
+        with pytest.raises(TypeError):
+            self.conv([1, 1.0])
+
+    def test_too_large(self):
+        with pytest.raises(ValueError):
+            self.conv(2**64)
+
+    def test_too_many_dims(self):
+        assert self.conv([1] * 64) == (1,) * 64
+        with pytest.raises(ValueError):
+            self.conv([1] * 65)

v12x/pylib/numpy/_core/tests/test_cpu_dispatcher.py

@@ -0,0 +1,48 @@
+from numpy._core import _umath_tests
+from numpy._core._multiarray_umath import (
+    __cpu_baseline__,
+    __cpu_dispatch__,
+    __cpu_features__,
+)
+from numpy.testing import assert_equal
+
+
+def test_dispatcher():
+    """
+    Testing the utilities of the CPU dispatcher
+    """
+    targets = (
+        "X86_V2", "X86_V3",
+        "VSX", "VSX2", "VSX3",
+        "NEON", "ASIMD", "ASIMDHP",
+        "VX", "VXE", "LSX", "RVV"
+    )
+    highest_sfx = ""  # no suffix for the baseline
+    all_sfx = []
+    for feature in reversed(targets):
+        # skip baseline features, by the default `CCompilerOpt` do not generate
+        # separated objects for the baseline, just one object combined all of them
+        # via 'baseline' option within the configuration statements.
+        if feature in __cpu_baseline__:
+            continue
+        # check compiler and running machine support
+        if feature not in __cpu_dispatch__ or not __cpu_features__[feature]:
+            continue
+
+        if not highest_sfx:
+            highest_sfx = "_" + feature
+        all_sfx.append("func" + "_" + feature)
+
+    test = _umath_tests.test_dispatch()
+    assert_equal(test["func"], "func" + highest_sfx)
+    assert_equal(test["var"], "var" + highest_sfx)
+
+    if highest_sfx:
+        assert_equal(test["func_xb"], "func" + highest_sfx)
+        assert_equal(test["var_xb"], "var" + highest_sfx)
+    else:
+        assert_equal(test["func_xb"], "nobase")
+        assert_equal(test["var_xb"], "nobase")
+
+    all_sfx.append("func")  # add the baseline
+    assert_equal(test["all"], all_sfx)

v12x/pylib/numpy/_core/tests/test_cpu_features.py

@@ -0,0 +1,533 @@
+import os
+import pathlib
+import platform
+import re
+import subprocess
+import sys
+
+import pytest
+
+from numpy._core._multiarray_umath import (
+    __cpu_baseline__,
+    __cpu_dispatch__,
+    __cpu_features__,
+)
+
+
+def assert_features_equal(actual, desired, fname):
+    __tracebackhide__ = True  # Hide traceback for py.test
+    actual, desired = str(actual), str(desired)
+    if actual == desired:
+        return
+    detected = str(__cpu_features__).replace("'", "")
+    try:
+        with open("/proc/cpuinfo") as fd:
+            cpuinfo = fd.read(2048)
+    except Exception as err:
+        cpuinfo = str(err)
+
+    try:
+        import subprocess
+        auxv = subprocess.check_output(['/bin/true'], env={"LD_SHOW_AUXV": "1"})
+        auxv = auxv.decode()
+    except Exception as err:
+        auxv = str(err)
+
+    import textwrap
+    error_report = textwrap.indent(
+f"""
+###########################################
+### Extra debugging information
+###########################################
+-------------------------------------------
+--- NumPy Detections
+-------------------------------------------
+{detected}
+-------------------------------------------
+--- SYS / CPUINFO
+-------------------------------------------
+{cpuinfo}....
+-------------------------------------------
+--- SYS / AUXV
+-------------------------------------------
+{auxv}
+""", prefix='\r')
+
+    raise AssertionError(
+        "Failure Detection\n"
+        f" NAME: '{fname}'\n"
+        f" ACTUAL: {actual}\n"
+        f" DESIRED: {desired}\n"
+        f"{error_report}")
+
+def _text_to_list(txt):
+    out = txt.strip("][\n").replace("'", "").split(', ')
+    return None if out[0] == "" else out
+
+class AbstractTest:
+    features = []
+    features_groups = {}
+    features_map = {}
+    features_flags = set()
+
+    def load_flags(self):
+        # a hook
+        pass
+
+    def test_features(self):
+        self.load_flags()
+        for gname, features in self.features_groups.items():
+            test_features = [self.cpu_have(f) for f in features]
+            assert_features_equal(
+                __cpu_features__.get(gname),
+                all(test_features),
+                gname,
+            )
+
+        for feature_name in self.features:
+            cpu_have = self.cpu_have(feature_name)
+            npy_have = __cpu_features__.get(feature_name)
+            assert_features_equal(npy_have, cpu_have, feature_name)
+
+    def cpu_have(self, feature_name):
+        map_names = self.features_map.get(feature_name, feature_name)
+        if isinstance(map_names, str):
+            return map_names in self.features_flags
+        return any(f in self.features_flags for f in map_names)
+
+    def load_flags_cpuinfo(self, magic_key):
+        self.features_flags = self.get_cpuinfo_item(magic_key)
+
+    def get_cpuinfo_item(self, magic_key):
+        values = set()
+        with open('/proc/cpuinfo') as fd:
+            for line in fd:
+                if not line.startswith(magic_key):
+                    continue
+                flags_value = [s.strip() for s in line.split(':', 1)]
+                if len(flags_value) == 2:
+                    values = values.union(flags_value[1].upper().split())
+        return values
+
+    def load_flags_auxv(self):
+        auxv = subprocess.check_output(['/bin/true'], env={"LD_SHOW_AUXV": "1"})
+        for at in auxv.split(b'\n'):
+            if not at.startswith(b"AT_HWCAP"):
+                continue
+            hwcap_value = [s.strip() for s in at.split(b':', 1)]
+            if len(hwcap_value) == 2:
+                self.features_flags = self.features_flags.union(
+                    hwcap_value[1].upper().decode().split()
+                )
+
+@pytest.mark.skipif(
+    sys.platform == 'emscripten',
+    reason=(
+        "The subprocess module is not available on WASM platforms and"
+        " therefore this test class cannot be properly executed."
+    ),
+)
+@pytest.mark.thread_unsafe(
+    reason="setup & tmp_path_factory threads-unsafe, modifies environment variables",
+)
+class TestEnvPrivation:
+    cwd = pathlib.Path(__file__).parent.resolve()
+    env = os.environ.copy()
+    _enable = os.environ.pop('NPY_ENABLE_CPU_FEATURES', None)
+    _disable = os.environ.pop('NPY_DISABLE_CPU_FEATURES', None)
+    SUBPROCESS_ARGS = {"cwd": cwd, "capture_output": True, "text": True, "check": True}
+    unavailable_feats = [
+        feat for feat in __cpu_dispatch__ if not __cpu_features__[feat]
+    ]
+    UNAVAILABLE_FEAT = (
+        None if len(unavailable_feats) == 0
+        else unavailable_feats[0]
+    )
+    BASELINE_FEAT = None if len(__cpu_baseline__) == 0 else __cpu_baseline__[0]
+    SCRIPT = """
+def main():
+    from numpy._core._multiarray_umath import (
+        __cpu_features__,
+        __cpu_dispatch__
+    )
+
+    detected = [feat for feat in __cpu_dispatch__ if __cpu_features__[feat]]
+    print(detected)
+
+if __name__ == "__main__":
+    main()
+    """
+
+    @pytest.fixture(autouse=True)
+    def setup_class(self, tmp_path_factory):
+        file = tmp_path_factory.mktemp("runtime_test_script")
+        file /= "_runtime_detect.py"
+        file.write_text(self.SCRIPT)
+        self.file = file
+
+    def _run(self):
+        return subprocess.run(
+            [sys.executable, self.file],
+            env=self.env,
+            **self.SUBPROCESS_ARGS,
+            )
+
+    # Helper function mimicking pytest.raises for subprocess call
+    def _expect_error(
+        self,
+        msg,
+        err_type,
+        no_error_msg="Failed to generate error"
+    ):
+        try:
+            self._run()
+        except subprocess.CalledProcessError as e:
+            assertion_message = f"Expected: {msg}\nGot: {e.stderr}"
+            assert re.search(msg, e.stderr), assertion_message
+
+            assertion_message = (
+                f"Expected error of type: {err_type}; see full "
+                f"error:\n{e.stderr}"
+            )
+            assert re.search(err_type, e.stderr), assertion_message
+        else:
+            assert False, no_error_msg
+
+    def setup_method(self):
+        """Ensure that the environment is reset"""
+        self.env = os.environ.copy()
+
+    def test_runtime_feature_selection(self):
+        """
+        Ensure that when selecting `NPY_ENABLE_CPU_FEATURES`, only the
+        features exactly specified are dispatched.
+        """
+
+        # Capture runtime-enabled features
+        out = self._run()
+        non_baseline_features = _text_to_list(out.stdout)
+
+        if non_baseline_features is None:
+            pytest.skip(
+                "No dispatchable features outside of baseline detected."
+            )
+        feature = non_baseline_features[0]
+
+        # Capture runtime-enabled features when `NPY_ENABLE_CPU_FEATURES` is
+        # specified
+        self.env['NPY_ENABLE_CPU_FEATURES'] = feature
+        out = self._run()
+        enabled_features = _text_to_list(out.stdout)
+
+        # Ensure that only one feature is enabled, and it is exactly the one
+        # specified by `NPY_ENABLE_CPU_FEATURES`
+        assert set(enabled_features) == {feature}
+
+        if len(non_baseline_features) < 2:
+            pytest.skip("Only one non-baseline feature detected.")
+        # Capture runtime-enabled features when `NPY_ENABLE_CPU_FEATURES` is
+        # specified
+        self.env['NPY_ENABLE_CPU_FEATURES'] = ",".join(non_baseline_features)
+        out = self._run()
+        enabled_features = _text_to_list(out.stdout)
+
+        # Ensure that both features are enabled, and they are exactly the ones
+        # specified by `NPY_ENABLE_CPU_FEATURES`
+        assert set(enabled_features) == set(non_baseline_features)
+
+    @pytest.mark.parametrize("enabled, disabled",
+    [
+        ("feature", "feature"),
+        ("feature", "same"),
+    ])
+    def test_both_enable_disable_set(self, enabled, disabled):
+        """
+        Ensure that when both environment variables are set then an
+        ImportError is thrown
+        """
+        self.env['NPY_ENABLE_CPU_FEATURES'] = enabled
+        self.env['NPY_DISABLE_CPU_FEATURES'] = disabled
+        msg = "Both NPY_DISABLE_CPU_FEATURES and NPY_ENABLE_CPU_FEATURES"
+        err_type = "ImportError"
+        self._expect_error(msg, err_type)
+
+    @pytest.mark.skipif(
+        not __cpu_dispatch__,
+        reason=(
+            "NPY_*_CPU_FEATURES only parsed if "
+            "`__cpu_dispatch__` is non-empty"
+        )
+    )
+    @pytest.mark.parametrize("action", ["ENABLE", "DISABLE"])
+    def test_variable_too_long(self, action):
+        """
+        Test that an error is thrown if the environment variables are too long
+        to be processed. Current limit is 1024, but this may change later.
+        """
+        MAX_VAR_LENGTH = 1024
+        # Actual length is MAX_VAR_LENGTH + 1 due to null-termination
+        self.env[f'NPY_{action}_CPU_FEATURES'] = "t" * MAX_VAR_LENGTH
+        msg = (
+            f"Length of environment variable 'NPY_{action}_CPU_FEATURES' is "
+            f"{MAX_VAR_LENGTH + 1}, only {MAX_VAR_LENGTH} accepted"
+        )
+        err_type = "RuntimeError"
+        self._expect_error(msg, err_type)
+
+    @pytest.mark.skipif(
+        not __cpu_dispatch__,
+        reason=(
+            "NPY_*_CPU_FEATURES only parsed if "
+            "`__cpu_dispatch__` is non-empty"
+        )
+    )
+    @pytest.mark.parametrize("action", ["ENABLE", "DISABLE"])
+    def test_max_length_nonexistent_feature(self, action):
+        """
+        Test that the maximum accepted environment variable length can be
+        processed even if the whole value is an invalid feature name.
+        """
+        MAX_VAR_LENGTH = 1024
+        self.env[f'NPY_{action}_CPU_FEATURES'] = "t" * (MAX_VAR_LENGTH - 1)
+        self._run()
+
+    @pytest.mark.skipif(
+        not __cpu_dispatch__,
+        reason=(
+            "NPY_*_CPU_FEATURES only parsed if "
+            "`__cpu_dispatch__` is non-empty"
+        )
+    )
+    def test_impossible_feature_disable(self):
+        """
+        Test that a RuntimeError is thrown if an impossible feature-disabling
+        request is made. This includes disabling a baseline feature.
+        """
+
+        if self.BASELINE_FEAT is None:
+            pytest.skip("There are no unavailable features to test with")
+        bad_feature = self.BASELINE_FEAT
+        self.env['NPY_DISABLE_CPU_FEATURES'] = bad_feature
+        msg = (
+            f"You cannot disable CPU feature '{bad_feature}', since it is "
+            "part of the baseline optimizations"
+        )
+        err_type = "RuntimeError"
+        self._expect_error(msg, err_type)
+
+    def test_impossible_feature_enable(self):
+        """
+        Test that a RuntimeError is thrown if an impossible feature-enabling
+        request is made. This includes enabling a feature not supported by the
+        machine, or disabling a baseline optimization.
+        """
+
+        if self.UNAVAILABLE_FEAT is None:
+            pytest.skip("There are no unavailable features to test with")
+        bad_feature = self.UNAVAILABLE_FEAT
+        self.env['NPY_ENABLE_CPU_FEATURES'] = bad_feature
+        msg = (
+            f"You cannot enable CPU features \\({bad_feature}\\), since "
+            "they are not supported by your machine."
+        )
+        err_type = "RuntimeError"
+        self._expect_error(msg, err_type)
+
+        # Ensure that it fails even when providing garbage in addition
+        feats = f"{bad_feature}, Foobar"
+        self.env['NPY_ENABLE_CPU_FEATURES'] = feats
+        msg = (
+            f"You cannot enable CPU features \\({bad_feature}\\), since they "
+            "are not supported by your machine."
+        )
+        self._expect_error(msg, err_type)
+
+        if self.BASELINE_FEAT is not None:
+            # Ensure that only the bad feature gets reported
+            feats = f"{bad_feature}, {self.BASELINE_FEAT}"
+            self.env['NPY_ENABLE_CPU_FEATURES'] = feats
+            msg = (
+                f"You cannot enable CPU features \\({bad_feature}\\), since "
+                "they are not supported by your machine."
+            )
+            self._expect_error(msg, err_type)
+
+    @pytest.mark.parametrize("action", ["ENABLE", "DISABLE"])
+    def test_repeated_unavailable_feature(self, action):
+        """
+        Test that repeated unavailable features can be processed without
+        overflowing the diagnostic buffer.
+        """
+        if self.UNAVAILABLE_FEAT is None:
+            pytest.skip("There are no unavailable features to test with")
+
+        bad_feature = self.UNAVAILABLE_FEAT
+        feature_repeats = 1024 // (len(bad_feature) + 1)
+        self.env[f'NPY_{action}_CPU_FEATURES'] = ",".join(
+            [bad_feature] * feature_repeats
+        )
+
+        if action == "ENABLE":
+            msg = "You cannot enable CPU features"
+            err_type = "RuntimeError"
+            self._expect_error(msg, err_type)
+        else:
+            self._run()
+
+
+is_linux = sys.platform.startswith('linux')
+is_cygwin = sys.platform.startswith('cygwin')
+machine = platform.machine()
+is_x86 = re.match(r"^(amd64|x86|i386|i686)", machine, re.IGNORECASE)
+@pytest.mark.skipif(
+    not (is_linux or is_cygwin) or not is_x86,
+    reason="Only for Linux and x86",
+)
+class Test_X86_Features(AbstractTest):
+    features = []
+
+    features_groups = {
+        "X86_V2": [
+            "SSE", "SSE2", "SSE3", "SSSE3", "SSE41", "SSE42",
+            "POPCNT", "LAHF", "CX16"
+        ],
+    }
+    features_groups["X86_V3"] = features_groups["X86_V2"] + [
+        "AVX", "AVX2", "FMA3", "BMI", "BMI2",
+        "LZCNT", "F16C", "MOVBE"
+    ]
+    features_groups["X86_V4"] = features_groups["X86_V3"] + [
+        "AVX512F", "AVX512CD", "AVX512BW", "AVX512DQ", "AVX512VL"
+    ]
+    features_groups["AVX512_ICL"] = features_groups["X86_V4"] + [
+        "AVX512IFMA", "AVX512VBMI", "AVX512VNNI",
+        "AVX512VBMI2", "AVX512BITALG", "AVX512VPOPCNTDQ",
+        "VAES", "VPCLMULQDQ", "GFNI"
+    ]
+    features_groups["AVX512_SPR"] = (
+        features_groups["AVX512_ICL"] + ["AVX512FP16", "AVX512BF16"]
+    )
+
+    features_map = {
+        "SSE3": "PNI", "SSE41": "SSE4_1", "SSE42": "SSE4_2", "FMA3": "FMA",
+        "BMI": "BMI1", "LZCNT": "ABM", "LAHF": "LAHF_LM",
+        "AVX512VNNI": "AVX512_VNNI", "AVX512BITALG": "AVX512_BITALG",
+        "AVX512VBMI2": "AVX512_VBMI2", "AVX5124FMAPS": "AVX512_4FMAPS",
+        "AVX5124VNNIW": "AVX512_4VNNIW", "AVX512VPOPCNTDQ": "AVX512_VPOPCNTDQ",
+        "AVX512FP16": "AVX512_FP16", "AVX512BF16": "AVX512_BF16"
+    }
+
+    def load_flags(self):
+        self.load_flags_cpuinfo("flags")
+
+
+is_power = re.match(r"^(powerpc|ppc)64", machine, re.IGNORECASE)
+@pytest.mark.skipif(not is_linux or not is_power, reason="Only for Linux and Power")
+class Test_POWER_Features(AbstractTest):
+    features = ["VSX", "VSX2", "VSX3", "VSX4"]
+    features_map = {
+        "VSX":  "ARCH_2_06",
+        "VSX2": "ARCH_2_07",
+        "VSX3": "ARCH_3_00",
+        "VSX4": "ARCH_3_1B"
+    }
+
+    def load_flags(self):
+        self.load_flags_auxv()
+        platform = self._get_platform()
+
+        if platform:
+            power_match = re.search(r'power(\d+)', platform, re.IGNORECASE)
+            if power_match:
+                power_gen = int(power_match.group(1))
+                if power_gen >= 7:
+                    self.features_flags.add("ARCH_2_06")
+                if power_gen >= 8:
+                    self.features_flags.add("ARCH_2_07")
+                if power_gen >= 9:
+                    self.features_flags.add("ARCH_3_00")
+                if power_gen >= 10:
+                    self.features_flags.add("ARCH_3_1B")
+
+    def _get_platform(self):
+        """Get the AT_PLATFORM value from AUXV"""
+        try:
+            auxv = subprocess.check_output(['/bin/true'], env={"LD_SHOW_AUXV": "1"})
+            for line in auxv.split(b'\n'):
+                if line.startswith(b'AT_PLATFORM'):
+                    parts = line.split(b':', 1)
+                    if len(parts) == 2:
+                        return parts[1].strip().decode().lower()
+        except Exception:
+            pass
+        return None
+
+
+is_zarch = re.match(r"^(s390x)", machine, re.IGNORECASE)
+@pytest.mark.skipif(not is_linux or not is_zarch,
+                    reason="Only for Linux and IBM Z")
+class Test_ZARCH_Features(AbstractTest):
+    features = ["VX", "VXE", "VXE2"]
+
+    def load_flags(self):
+        self.load_flags_cpuinfo("features")
+
+
+is_arm = re.match(r"^(arm|aarch64)", machine, re.IGNORECASE)
+@pytest.mark.skipif(not is_linux or not is_arm, reason="Only for Linux and ARM")
+class Test_ARM_Features(AbstractTest):
+    features = [
+        "SVE", "NEON", "ASIMD", "FPHP", "ASIMDHP", "ASIMDDP", "ASIMDFHM"
+    ]
+    features_groups = {
+        "NEON_FP16":  ["NEON", "HALF"],
+        "NEON_VFPV4": ["NEON", "VFPV4"],
+    }
+
+    def load_flags(self):
+        self.load_flags_cpuinfo("Features")
+        arch = self.get_cpuinfo_item("CPU architecture")
+        # in case of mounting virtual filesystem of aarch64 kernel without linux32
+        is_rootfs_v8 = (
+            not re.match(r"^armv[0-9]+l$", machine) and
+            (int('0' + next(iter(arch))) > 7 if arch else 0)
+        )
+        if re.match(r"^(aarch64|AARCH64)", machine) or is_rootfs_v8:
+            self.features_map = {
+                "NEON": "ASIMD", "HALF": "ASIMD", "VFPV4": "ASIMD"
+            }
+        else:
+            self.features_map = {
+                # ELF auxiliary vector and /proc/cpuinfo on Linux kernel(armv8 aarch32)
+                # doesn't provide information about ASIMD
+                # so we assume that ASIMD is supported
+                # if the kernel reports any one of the following ARM8 features.
+                "ASIMD": ("AES", "SHA1", "SHA2", "PMULL", "CRC32")
+            }
+
+
+is_loongarch = re.match(r"^(loongarch)", machine, re.IGNORECASE)
+@pytest.mark.skipif(
+    not is_linux or not is_loongarch,
+    reason="Only for Linux and LoongArch",
+)
+class Test_LOONGARCH_Features(AbstractTest):
+    features = ["LSX"]
+
+    def load_flags(self):
+        self.load_flags_cpuinfo("Features")
+
+
+is_riscv = re.match(r"^(riscv)", machine, re.IGNORECASE)
+@pytest.mark.skipif(not is_linux or not is_riscv, reason="Only for Linux and RISC-V")
+class Test_RISCV_Features(AbstractTest):
+    features = ["RVV"]
+
+    def load_flags(self):
+        self.load_flags_auxv()
+        if not self.features_flags:
+            # Let the test fail and dump if we cannot read HWCAP.
+            return
+        hwcap = int(next(iter(self.features_flags)), 16)
+        if hwcap & (1 << 21):  # HWCAP_RISCV_V
+            self.features_flags.add("RVV")

v12x/pylib/numpy/_core/tests/test_custom_dtypes.py

@@ -0,0 +1,511 @@
+from tempfile import NamedTemporaryFile
+
+import pytest
+
+import numpy as np
+from numpy._core._multiarray_umath import (
+    _discover_array_parameters as discover_array_params,
+    _get_sfloat_dtype,
+)
+from numpy.testing import assert_array_equal
+
+SF = _get_sfloat_dtype()
+
+
+class TestSFloat:
+    def _get_array(self, scaling, aligned=True):
+        if not aligned:
+            a = np.empty(3 * 8 + 1, dtype=np.uint8)[1:]
+            a = a.view(np.float64)
+            a[:] = [1., 2., 3.]
+        else:
+            a = np.array([1., 2., 3.])
+
+        a *= 1. / scaling  # the casting code also uses the reciprocal.
+        return a.view(SF(scaling))
+
+    def test_sfloat_rescaled(self):
+        sf = SF(1.)
+        sf2 = sf.scaled_by(2.)
+        assert sf2.get_scaling() == 2.
+        sf6 = sf2.scaled_by(3.)
+        assert sf6.get_scaling() == 6.
+
+    def test_class_discovery(self):
+        # This does not test much, since we always discover the scaling as 1.
+        # But most of NumPy (when writing) does not understand DType classes
+        dt, _ = discover_array_params([1., 2., 3.], dtype=SF)
+        assert dt == SF(1.)
+
+    @pytest.mark.parametrize("scaling", [1., -1., 2.])
+    def test_scaled_float_from_floats(self, scaling):
+        a = np.array([1., 2., 3.], dtype=SF(scaling))
+
+        assert a.dtype.get_scaling() == scaling
+        assert_array_equal(scaling * a.view(np.float64), [1., 2., 3.])
+
+    def test_structured_field_byteswap_raises(self):
+        # a field (or subarray field) whose dtype lacks the legacy copyswap
+        # slot cannot be byteswapped; previously this segfaulted via the
+        # unguarded field copyswap calls in VOID_copyswapn
+        arr = np.zeros(2, dtype=[("a", "i4"), ("v", SF(1.))])
+        with pytest.raises(TypeError, match="does not implement copyswap"):
+            arr.byteswap()
+
+        subarr = np.zeros(2, dtype=[("v", SF(1.), (2,))])
+        with pytest.raises(TypeError, match="does not implement copyswap"):
+            subarr.byteswap()
+
+    def test_byteswap_raises(self):
+        # a top-level DType without the legacy copyswap slot does not
+        # support byteswapping
+        arr = np.zeros(2, dtype=SF(1.))
+        with pytest.raises(TypeError, match="does not implement copyswap"):
+            arr.byteswap()
+
+        # the in-place writeability check fires before the missing-slot
+        # check, matching the behavior for dtypes that fill the slot
+        arr.flags.writeable = False
+        with pytest.raises(ValueError, match="array to be byte-swapped"):
+            arr.byteswap(inplace=True)
+
+    def test_structured_field_place_and_flat_raise(self):
+        # requests that need to copy through the missing legacy copyswap
+        # slot raise instead of crashing
+        arr = np.zeros(2, dtype=[("v", SF(1.))])
+        with pytest.raises(TypeError, match="does not implement copyswap"):
+            np.place(arr, [True, False], arr[:1])
+        with pytest.raises(TypeError, match="does not implement copyswap"):
+            arr.flat = arr[:1]
+
+        # both stop copying as soon as the error is detected, so elements
+        # after the first (failing) one keep their values, even for fields
+        # that could have been copied
+        marr = np.zeros(3, dtype=[("a", "i4"), ("v", SF(1.))])
+        marr["a"] = [5, 6, 7]
+        src = marr[:1].copy()
+        src["a"] = 1
+        with pytest.raises(TypeError, match="does not implement copyswap"):
+            marr.flat = src
+        assert marr["a"].tolist()[1:] == [6, 7]
+        with pytest.raises(TypeError, match="does not implement copyswap"):
+            np.place(marr, [True, True, True], src)
+        assert marr["a"].tolist()[1:] == [6, 7]
+
+    def test_structured_field_sort_raises(self):
+        # VOID_compare called the field's legacy compare slot, which
+        # new-style DTypes do not fill
+        arr = np.zeros(3, dtype=[("v", SF(1.))])
+        with pytest.raises(TypeError, match="does not support comparison"):
+            np.sort(arr, order="v")
+
+        # packed fields are misaligned; the compare == NULL check fires
+        # before VOID_compare's alignment handling, so this exits through
+        # the same guard as the aligned case above and never reaches the
+        # misaligned buffer path (which would call the missing copyswap
+        # slot); it checks that the guard keeps covering that layout
+        packed_dt = np.dtype({"names": ["a", "v"],
+                              "formats": ["u1", SF(1.)],
+                              "offsets": [0, 1], "itemsize": 17})
+        with pytest.raises(TypeError, match="does not support comparison"):
+            np.sort(np.zeros(3, dtype=packed_dt), order="v")
+
+    def test_structured_setitem_uses_cast_path(self):
+        # scalar assignment between equivalent structured dtypes used to
+        # segfault in the copyswap fast path; it now falls back to casting
+        arr = np.zeros(2, dtype=[("v", SF(1.))])
+        arr["v"] = np.array([1., 2.]).view(SF(1.))
+        arr[0] = arr[1]
+        assert arr["v"].view(np.float64).tolist() == [2., 2.]
+
+    def test_structured_setitem_nested_uses_cast_path(self):
+        # for a nested field the copyswap slot is VOID_copyswap, which
+        # fails on the inner sfloat field only after it is called; the
+        # error must not leak out of a successful-looking assignment and
+        # the copy falls back to the casting path like the flat case
+        arr = np.zeros(2, dtype=[("a", "i4"), ("nested", [("v", SF(1.))])])
+        arr["a"] = [1, 2]
+        arr["nested"]["v"] = np.array([1., 2.]).view(SF(1.))
+        arr[0] = arr[1]
+        assert arr["a"].tolist() == [2, 2]
+        assert arr["nested"]["v"].view(np.float64).tolist() == [2., 2.]
+
+        # same for a subarray field of an sfloat dtype
+        arr = np.zeros(2, dtype=[("sub", SF(1.), (2,))])
+        arr["sub"] = np.array([[1., 2.], [3., 4.]]).view(SF(1.))
+        arr[0] = arr[1]
+        assert arr["sub"].view(np.float64).tolist() == [[3., 4.], [3., 4.]]
+
+    def test_repr(self):
+        # Check the repr, mainly to cover the code paths:
+        assert repr(SF(scaling=1.)) == "_ScaledFloatTestDType(scaling=1.0)"
+
+    def test_dtype_str(self):
+        assert SF(1.).str == "_ScaledFloatTestDType(scaling=1.0)"
+
+    def test_dtype_name(self):
+        assert SF(1.).name == "_ScaledFloatTestDType64"
+
+    def test_sfloat_structured_dtype_printing(self):
+        dt = np.dtype([("id", int), ("value", SF(0.5))])
+        # repr of structured dtypes need special handling because the
+        # implementation bypasses the object repr
+        assert "('value', '_ScaledFloatTestDType64')" in repr(dt)
+
+    @pytest.mark.parametrize("scaling", [1., -1., 2.])
+    def test_sfloat_from_float(self, scaling):
+        a = np.array([1., 2., 3.]).astype(dtype=SF(scaling))
+
+        assert a.dtype.get_scaling() == scaling
+        assert_array_equal(scaling * a.view(np.float64), [1., 2., 3.])
+
+    @pytest.mark.parametrize("aligned", [True, False])
+    @pytest.mark.parametrize("scaling", [1., -1., 2.])
+    def test_sfloat_getitem(self, aligned, scaling):
+        a = self._get_array(1., aligned)
+        assert a.tolist() == [1., 2., 3.]
+
+    @pytest.mark.parametrize("aligned", [True, False])
+    def test_sfloat_casts(self, aligned):
+        a = self._get_array(1., aligned)
+
+        assert np.can_cast(a, SF(-1.), casting="equiv")
+        assert not np.can_cast(a, SF(-1.), casting="no")
+        na = a.astype(SF(-1.))
+        assert_array_equal(-1 * na.view(np.float64), a.view(np.float64))
+
+        assert np.can_cast(a, SF(2.), casting="same_kind")
+        assert not np.can_cast(a, SF(2.), casting="safe")
+        a2 = a.astype(SF(2.))
+        assert_array_equal(2 * a2.view(np.float64), a.view(np.float64))
+
+    @pytest.mark.parametrize("aligned", [True, False])
+    def test_sfloat_cast_internal_errors(self, aligned):
+        a = self._get_array(2e300, aligned)
+
+        with pytest.raises(TypeError,
+                match="error raised inside the core-loop: non-finite factor!"):
+            a.astype(SF(2e-300))
+
+    def test_sfloat_promotion(self):
+        assert np.result_type(SF(2.), SF(3.)) == SF(3.)
+        assert np.result_type(SF(3.), SF(2.)) == SF(3.)
+        # Float64 -> SF(1.) and then promotes normally, so both of this work:
+        assert np.result_type(SF(3.), np.float64) == SF(3.)
+        assert np.result_type(np.float64, SF(0.5)) == SF(1.)
+
+        # Test an undefined promotion:
+        with pytest.raises(TypeError):
+            np.result_type(SF(1.), np.int64)
+
+    def test_basic_multiply(self):
+        a = self._get_array(2.)
+        b = self._get_array(4.)
+
+        res = a * b
+        # multiplies dtype scaling and content separately:
+        assert res.dtype.get_scaling() == 8.
+        expected_view = a.view(np.float64) * b.view(np.float64)
+        assert_array_equal(res.view(np.float64), expected_view)
+
+    def test_possible_and_impossible_reduce(self):
+        # For reductions to work, the first and last operand must have the
+        # same dtype.  For this parametric DType that is not necessarily true.
+        a = self._get_array(2.)
+        # Addition reduction works (as of writing requires to pass initial
+        # because setting a scaled-float from the default `0` fails).
+        res = np.add.reduce(a, initial=0.)
+        assert res == a.astype(np.float64).sum()
+
+        # But each multiplication changes the factor, so a reduction is not
+        # possible (the relaxed version of the old refusal to handle any
+        # flexible dtype).
+        with pytest.raises(TypeError,
+                match="the resolved dtypes are not compatible"):
+            np.multiply.reduce(a)
+
+    def test_basic_ufunc_at(self):
+        float_a = np.array([1., 2., 3.])
+        b = self._get_array(2.)
+
+        float_b = b.view(np.float64).copy()
+        np.multiply.at(float_b, [1, 1, 1], float_a)
+        np.multiply.at(b, [1, 1, 1], float_a)
+
+        assert_array_equal(b.view(np.float64), float_b)
+
+    def test_basic_multiply_promotion(self):
+        float_a = np.array([1., 2., 3.])
+        b = self._get_array(2.)
+
+        res1 = float_a * b
+        res2 = b * float_a
+
+        # one factor is one, so we get the factor of b:
+        assert res1.dtype == res2.dtype == b.dtype
+        expected_view = float_a * b.view(np.float64)
+        assert_array_equal(res1.view(np.float64), expected_view)
+        assert_array_equal(res2.view(np.float64), expected_view)
+
+        # Check that promotion works when `out` is used:
+        np.multiply(b, float_a, out=res2)
+        with pytest.raises(TypeError):
+            # The promoter accepts this (maybe it should not), but the SFloat
+            # result cannot be cast to integer:
+            np.multiply(b, float_a, out=np.arange(3))
+
+    def test_basic_addition(self):
+        a = self._get_array(2.)
+        b = self._get_array(4.)
+
+        res = a + b
+        # addition uses the type promotion rules for the result:
+        assert res.dtype == np.result_type(a.dtype, b.dtype)
+        expected_view = (a.astype(res.dtype).view(np.float64) +
+                         b.astype(res.dtype).view(np.float64))
+        assert_array_equal(res.view(np.float64), expected_view)
+
+    def test_addition_cast_safety(self):
+        """The addition method is special for the scaled float, because it
+        includes the "cast" between different factors, thus cast-safety
+        is influenced by the implementation.
+        """
+        a = self._get_array(2.)
+        b = self._get_array(-2.)
+        c = self._get_array(3.)
+
+        # sign change is "equiv":
+        np.add(a, b, casting="equiv")
+        with pytest.raises(TypeError):
+            np.add(a, b, casting="no")
+
+        # Different factor is "same_kind" (default) so check that "safe" fails
+        with pytest.raises(TypeError):
+            np.add(a, c, casting="safe")
+
+        # Check that casting the output fails also (done by the ufunc here)
+        with pytest.raises(TypeError):
+            np.add(a, a, out=c, casting="safe")
+
+    def test_sfloat_histogram_passes_dtype_class(self):
+        # Regression test for gh-31447.
+        #
+        # ``_unsigned_subtract`` used to forward a DType instance (from
+        # ``np.result_type``) to ``np.subtract``; the ufunc dispatcher
+        # rejects instances of non-legacy user DTypes.
+        #
+        # Expected behaviour:
+        #   pre-fix:  TypeError "Cannot pass a new user DType instance ..."
+        #   post-fix: TypeError "ufunc 'subtract' did not contain a loop"
+        #             (SF has no subtract loop; once the dispatcher
+        #             accepts the DType class, the missing-loop error
+        #             surfaces.)
+        from numpy.lib._histograms_impl import _unsigned_subtract
+        a = np.array([3.]).view(SF(1.))
+        b = np.array([1.]).view(SF(1.))
+        with pytest.raises(TypeError,
+                match="ufunc 'subtract' did not contain a loop"):
+            _unsigned_subtract(a, b)
+
+    @pytest.mark.parametrize("ufunc",
+            [np.logical_and, np.logical_or, np.logical_xor])
+    def test_logical_ufuncs_casts_to_bool(self, ufunc):
+        a = self._get_array(2.)
+        a[0] = 0.  # make sure first element is considered False.
+
+        float_equiv = a.astype(float)
+        expected = ufunc(float_equiv, float_equiv)
+        res = ufunc(a, a)
+        assert_array_equal(res, expected)
+
+        # also check that the same works for reductions:
+        expected = ufunc.reduce(float_equiv)
+        res = ufunc.reduce(a)
+        assert_array_equal(res, expected)
+
+        # The output casting does not match the bool, bool -> bool loop:
+        with pytest.raises(TypeError):
+            ufunc(a, a, out=np.empty(a.shape, dtype=int), casting="equiv")
+
+    def test_wrapped_and_wrapped_reductions(self):
+        a = self._get_array(2.)
+        float_equiv = a.astype(float)
+
+        expected = np.hypot(float_equiv, float_equiv)
+        res = np.hypot(a, a)
+        assert res.dtype == a.dtype
+        res_float = res.view(np.float64) * 2
+        assert_array_equal(res_float, expected)
+
+        # Also check reduction (keepdims, due to incorrect getitem)
+        res = np.hypot.reduce(a, keepdims=True)
+        assert res.dtype == a.dtype
+        expected = np.hypot.reduce(float_equiv, keepdims=True)
+        assert res.view(np.float64) * 2 == expected
+
+    def test_sort(self):
+        a = self._get_array(1.)
+        a = a[::-1]  # reverse it
+
+        a.sort()
+        assert_array_equal(a.view(np.float64), [1., 2., 3.])
+
+        a = self._get_array(1.)
+        a = a[::-1]  # reverse it
+
+        sorted_a = np.sort(a)
+        assert_array_equal(sorted_a.view(np.float64), [1., 2., 3.])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [3., 2., 1.])
+
+        a = self._get_array(0.5)  # different factor
+        a = a[::2][::-1]  # non-contiguous
+        sorted_a = np.sort(a)
+        assert_array_equal(sorted_a.view(np.float64), [2., 6.])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [6., 2.])
+
+        a = self._get_array(0.5, aligned=False)
+        a = a[::-1]  # reverse it
+        sorted_a = np.sort(a)
+        assert_array_equal(sorted_a.view(np.float64), [2., 4., 6.])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [6., 4., 2.])
+
+        sorted_a = np.sort(a, stable=True)
+        assert_array_equal(sorted_a.view(np.float64), [2., 4., 6.])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [6., 4., 2.])
+
+        sorted_a = np.sort(a, stable=False)
+        assert_array_equal(sorted_a.view(np.float64), [2., 4., 6.])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [6., 4., 2.])
+
+    def test_argsort(self):
+        a = self._get_array(1.)
+        a = a[::-1]  # reverse it
+
+        indices = np.argsort(a)
+        assert_array_equal(indices, [2, 1, 0])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [3., 2., 1.])
+
+        a = self._get_array(0.5)
+        a = a[::2][::-1]  # reverse it
+        indices = np.argsort(a)
+        assert_array_equal(indices, [1, 0])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [6., 2.])
+
+        a = self._get_array(0.5, aligned=False)
+        a = a[::-1]  # reverse it
+        indices = np.argsort(a)
+        assert_array_equal(indices, [2, 1, 0])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [6., 4., 2.])
+
+        sorted_indices = np.argsort(a, stable=True)
+        assert_array_equal(sorted_indices, [2, 1, 0])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [6., 4., 2.])
+
+        sorted_indices = np.argsort(a, stable=False)
+        assert_array_equal(sorted_indices, [2, 1, 0])
+        # original is unchanged
+        assert_array_equal(a.view(np.float64), [6., 4., 2.])
+
+    def test_astype_class(self):
+        # Very simple test that we accept `.astype()` also on the class.
+        # ScaledFloat always returns the default descriptor, but it does
+        # check the relevant code paths.
+        arr = np.array([1., 2., 3.], dtype=object)
+
+        res = arr.astype(SF)  # passing the class class
+        expected = arr.astype(SF(1.))  # above will have discovered 1. scaling
+        assert_array_equal(res.view(np.float64), expected.view(np.float64))
+
+    def test_creation_class(self):
+        # passing in a dtype class should return
+        # the default descriptor
+        arr1 = np.array([1., 2., 3.], dtype=SF)
+        assert arr1.dtype == SF(1.)
+        arr2 = np.array([1., 2., 3.], dtype=SF(1.))
+        assert_array_equal(arr1.view(np.float64), arr2.view(np.float64))
+        assert arr1.dtype == arr2.dtype
+
+        assert np.empty(3, dtype=SF).dtype == SF(1.)
+        assert np.empty_like(arr1, dtype=SF).dtype == SF(1.)
+        assert np.zeros(3, dtype=SF).dtype == SF(1.)
+        assert np.zeros_like(arr1, dtype=SF).dtype == SF(1.)
+
+    @pytest.mark.thread_unsafe(
+        reason="_ScaledFloatTestDType setup is thread-unsafe (gh-29850)"
+    )
+    def test_np_save_load(self):
+        # this monkeypatch is needed because pickle
+        # uses the repr of a type to reconstruct it
+        np._ScaledFloatTestDType = SF
+
+        arr = np.array([1.0, 2.0, 3.0], dtype=SF(1.0))
+
+        # adapted from RoundtripTest.roundtrip in np.save tests
+        with NamedTemporaryFile("wb", delete=False, suffix=".npz") as f:
+            with pytest.warns(UserWarning) as record:
+                np.savez(f.name, arr)
+
+        assert len(record) == 1
+
+        with np.load(f.name, allow_pickle=True) as data:
+            larr = data["arr_0"]
+        assert_array_equal(arr.view(np.float64), larr.view(np.float64))
+        assert larr.dtype == arr.dtype == SF(1.0)
+
+        del np._ScaledFloatTestDType
+
+    def test_flatiter(self):
+        arr = np.array([1.0, 2.0, 3.0], dtype=SF(1.0))
+
+        for i, val in enumerate(arr.flat):
+            assert arr[i] == val
+
+    @pytest.mark.parametrize(
+        "index", [
+            [1, 2], ..., slice(None, 2, None),
+            np.array([True, True, False]), np.array([0, 1])
+        ], ids=["int_list", "ellipsis", "slice", "bool_array", "int_array"])
+    def test_flatiter_index(self, index):
+        arr = np.array([1.0, 2.0, 3.0], dtype=SF(1.0))
+        np.testing.assert_array_equal(
+            arr[index].view(np.float64), arr.flat[index].view(np.float64))
+
+        arr2 = arr.copy()
+        arr[index] = 5.0
+        arr2.flat[index] = 5.0
+        np.testing.assert_array_equal(
+            arr.view(np.float64), arr2.view(np.float64))
+
+    def test_conjugate(self):
+        # Also user dtype can just return self if conjugate should be no-op.
+        arr = np.array([1.0, 2.0, 3.0], dtype=SF(1.0))
+        assert arr.conjugate() is arr
+
+
+@pytest.mark.thread_unsafe(
+    reason="_ScaledFloatTestDType setup is thread-unsafe (gh-29850)"
+)
+def test_type_pickle():
+    # can't actually unpickle, but we can pickle (if in namespace)
+    import pickle
+
+    np._ScaledFloatTestDType = SF
+
+    s = pickle.dumps(SF)
+    res = pickle.loads(s)
+    assert res is SF
+
+    del np._ScaledFloatTestDType
+
+
+def test_is_numeric():
+    assert SF._is_numeric