numpy 2.4.1__cp314-cp314t-win_arm64.whl

numpy/tests/test_reloading.py

@@ -0,0 +1,76 @@
+import pickle
+import subprocess
+import sys
+import textwrap
+from importlib import reload
+
+import pytest
+
+import numpy.exceptions as ex
+from numpy.testing import IS_WASM, assert_, assert_equal, assert_raises
+
+
+@pytest.mark.thread_unsafe(reason="reloads global module")
+def test_numpy_reloading():
+    # gh-7844. Also check that relevant globals retain their identity.
+    import numpy as np
+    import numpy._globals
+
+    _NoValue = np._NoValue
+    VisibleDeprecationWarning = ex.VisibleDeprecationWarning
+    ModuleDeprecationWarning = ex.ModuleDeprecationWarning
+
+    with pytest.warns(UserWarning):
+        reload(np)
+    assert_(_NoValue is np._NoValue)
+    assert_(ModuleDeprecationWarning is ex.ModuleDeprecationWarning)
+    assert_(VisibleDeprecationWarning is ex.VisibleDeprecationWarning)
+
+    assert_raises(RuntimeError, reload, numpy._globals)
+    with pytest.warns(UserWarning):
+        reload(np)
+    assert_(_NoValue is np._NoValue)
+    assert_(ModuleDeprecationWarning is ex.ModuleDeprecationWarning)
+    assert_(VisibleDeprecationWarning is ex.VisibleDeprecationWarning)
+
+def test_novalue():
+    import numpy as np
+    for proto in range(2, pickle.HIGHEST_PROTOCOL + 1):
+        assert_equal(repr(np._NoValue), '<no value>')
+        assert_(pickle.loads(pickle.dumps(np._NoValue,
+                                          protocol=proto)) is np._NoValue)
+
+
+@pytest.mark.skipif(IS_WASM, reason="can't start subprocess")
+def test_full_reimport():
+    # Reimporting numpy like this is not safe due to use of global C state,
+    # and has unexpected side effects. Test that an ImportError is raised.
+    # When all extension modules are isolated, this should test that clearing
+    # sys.modules and reimporting numpy works without error.
+
+    # Test within a new process, to ensure that we do not mess with the
+    # global state during the test run (could lead to cryptic test failures).
+    # This is generally unsafe, especially, since we also reload the C-modules.
+    code = textwrap.dedent(r"""
+        import sys
+        import numpy as np
+
+        for k in [k for k in sys.modules if k.startswith('numpy')]:
+            del sys.modules[k]
+
+        try:
+            import numpy as np
+        except ImportError as err:
+            if str(err) != "cannot load module more than once per process":
+                raise SystemExit(f"Unexpected ImportError: {err}")
+        else:
+            raise SystemExit("DID NOT RAISE ImportError")
+        """)
+    p = subprocess.run(
+        (sys.executable, '-c', code),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        encoding='utf-8',
+        check=False,
+    )
+    assert p.returncode == 0, p.stdout

numpy/tests/test_scripts.py

@@ -0,0 +1,48 @@
+""" Test scripts
+
+Test that we can run executable scripts that have been installed with numpy.
+"""
+import os
+import subprocess
+import sys
+from os.path import dirname, isfile, join as pathjoin
+
+import pytest
+
+import numpy as np
+from numpy.testing import IS_WASM, assert_equal
+
+is_inplace = isfile(pathjoin(dirname(np.__file__), '..', 'setup.py'))
+
+
+def find_f2py_commands():
+    if sys.platform == 'win32':
+        exe_dir = dirname(sys.executable)
+        if exe_dir.endswith('Scripts'):  # virtualenv
+            return [os.path.join(exe_dir, 'f2py')]
+        else:
+            return [os.path.join(exe_dir, "Scripts", 'f2py')]
+    else:
+        # Three scripts are installed in Unix-like systems:
+        # 'f2py', 'f2py{major}', and 'f2py{major.minor}'. For example,
+        # if installed with python3.9 the scripts would be named
+        # 'f2py', 'f2py3', and 'f2py3.9'.
+        version = sys.version_info
+        major = str(version.major)
+        minor = str(version.minor)
+        return ['f2py', 'f2py' + major, 'f2py' + major + '.' + minor]
+
+
+@pytest.mark.skipif(is_inplace, reason="Cannot test f2py command inplace")
+@pytest.mark.xfail(reason="Test is unreliable")
+@pytest.mark.parametrize('f2py_cmd', find_f2py_commands())
+def test_f2py(f2py_cmd):
+    # test that we can run f2py script
+    stdout = subprocess.check_output([f2py_cmd, '-v'])
+    assert_equal(stdout.strip(), np.__version__.encode('ascii'))
+
+
+@pytest.mark.skipif(IS_WASM, reason="Cannot start subprocess")
+def test_pep338():
+    stdout = subprocess.check_output([sys.executable, '-mnumpy.f2py', '-v'])
+    assert_equal(stdout.strip(), np.__version__.encode('ascii'))

numpy/tests/test_warnings.py

@@ -0,0 +1,79 @@
+"""
+Tests which scan for certain occurrences in the code, they may not find
+all of these occurrences but should catch almost all.
+"""
+import ast
+import tokenize
+from pathlib import Path
+
+import pytest
+
+import numpy
+
+
+class ParseCall(ast.NodeVisitor):
+    def __init__(self):
+        self.ls = []
+
+    def visit_Attribute(self, node):
+        ast.NodeVisitor.generic_visit(self, node)
+        self.ls.append(node.attr)
+
+    def visit_Name(self, node):
+        self.ls.append(node.id)
+
+
+class FindFuncs(ast.NodeVisitor):
+    def __init__(self, filename):
+        super().__init__()
+        self.__filename = filename
+
+    def visit_Call(self, node):
+        p = ParseCall()
+        p.visit(node.func)
+        ast.NodeVisitor.generic_visit(self, node)
+
+        if p.ls[-1] == 'simplefilter' or p.ls[-1] == 'filterwarnings':
+            if getattr(node.args[0], "value", None) == "ignore":
+                if not self.__filename.name.startswith("test_"):
+                    raise AssertionError(
+                        "ignore filters should only be used in tests; "
+                        f"found in {self.__filename} on line {node.lineno}")
+
+        if p.ls[-1] == 'warn' and (
+                len(p.ls) == 1 or p.ls[-2] == 'warnings'):
+
+            if "testing/tests/test_warnings.py" == self.__filename:
+                # This file
+                return
+
+            # See if stacklevel exists:
+            if len(node.args) == 3:
+                return
+            args = {kw.arg for kw in node.keywords}
+            if "stacklevel" in args:
+                return
+            raise AssertionError(
+                "warnings should have an appropriate stacklevel; "
+                f"found in {self.__filename} on line {node.lineno}")
+
+
+@pytest.mark.slow
+def test_warning_calls():
+    # combined "ignore" and stacklevel error
+    base = Path(numpy.__file__).parent
+
+    for path in base.rglob("*.py"):
+        if base / "testing" in path.parents:
+            continue
+        if path == base / "__init__.py":
+            continue
+        if path == base / "random" / "__init__.py":
+            continue
+        if path == base / "conftest.py":
+            continue
+        # use tokenize to auto-detect encoding on systems where no
+        # default encoding is defined (e.g. LANG='C')
+        with tokenize.open(str(path)) as file:
+            tree = ast.parse(file.read())
+            FindFuncs(path).visit(tree)

numpy/typing/__init__.py

@@ -0,0 +1,233 @@
+"""
+============================
+Typing (:mod:`numpy.typing`)
+============================
+
+.. versionadded:: 1.20
+
+Large parts of the NumPy API have :pep:`484`-style type annotations. In
+addition a number of type aliases are available to users, most prominently
+the two below:
+
+- `ArrayLike`: objects that can be converted to arrays
+- `DTypeLike`: objects that can be converted to dtypes
+
+.. _typing-extensions: https://pypi.org/project/typing-extensions/
+
+Mypy plugin
+-----------
+
+.. versionadded:: 1.21
+
+.. automodule:: numpy.typing.mypy_plugin
+
+.. currentmodule:: numpy.typing
+
+Differences from the runtime NumPy API
+--------------------------------------
+
+NumPy is very flexible. Trying to describe the full range of
+possibilities statically would result in types that are not very
+helpful. For that reason, the typed NumPy API is often stricter than
+the runtime NumPy API. This section describes some notable
+differences.
+
+ArrayLike
+~~~~~~~~~
+
+The `ArrayLike` type tries to avoid creating object arrays. For
+example,
+
+.. code-block:: python
+
+    >>> np.array(x**2 for x in range(10))
+    array(<generator object <genexpr> at ...>, dtype=object)
+
+is valid NumPy code which will create a 0-dimensional object
+array. Type checkers will complain about the above example when using
+the NumPy types however. If you really intended to do the above, then
+you can either use a ``# type: ignore`` comment:
+
+.. code-block:: python
+
+    >>> np.array(x**2 for x in range(10))  # type: ignore
+
+or explicitly type the array like object as `~typing.Any`:
+
+.. code-block:: python
+
+    >>> from typing import Any
+    >>> array_like: Any = (x**2 for x in range(10))
+    >>> np.array(array_like)
+    array(<generator object <genexpr> at ...>, dtype=object)
+
+ndarray
+~~~~~~~
+
+It's possible to mutate the dtype of an array at runtime. For example,
+the following code is valid:
+
+.. code-block:: python
+
+    >>> x = np.array([1, 2])
+    >>> x.dtype = np.bool
+
+This sort of mutation is not allowed by the types. Users who want to
+write statically typed code should instead use the `numpy.ndarray.view`
+method to create a view of the array with a different dtype.
+
+DTypeLike
+~~~~~~~~~
+
+The `DTypeLike` type tries to avoid creation of dtype objects using
+dictionary of fields like below:
+
+.. code-block:: python
+
+    >>> x = np.dtype({"field1": (float, 1), "field2": (int, 3)})
+
+Although this is valid NumPy code, the type checker will complain about it,
+since its usage is discouraged.
+Please see : :ref:`Data type objects <arrays.dtypes>`
+
+Number precision
+~~~~~~~~~~~~~~~~
+
+The precision of `numpy.number` subclasses is treated as a invariant generic
+parameter (see :class:`~NBitBase`), simplifying the annotating of processes
+involving precision-based casting.
+
+.. code-block:: python
+
+    >>> from typing import TypeVar
+    >>> import numpy as np
+    >>> import numpy.typing as npt
+
+    >>> T = TypeVar("T", bound=npt.NBitBase)
+    >>> def func(a: np.floating[T], b: np.floating[T]) -> np.floating[T]:
+    ...     ...
+
+Consequently, the likes of `~numpy.float16`, `~numpy.float32` and
+`~numpy.float64` are still sub-types of `~numpy.floating`, but, contrary to
+runtime, they're not necessarily considered as sub-classes.
+
+.. deprecated:: 2.3
+    The :class:`~numpy.typing.NBitBase` helper is deprecated and will be
+    removed in a future release. Prefer expressing precision relationships via
+    ``typing.overload`` or ``TypeVar`` definitions bounded by concrete scalar
+    classes. For example:
+
+    .. code-block:: python
+
+        from typing import TypeVar
+        import numpy as np
+
+        S = TypeVar("S", bound=np.floating)
+
+        def func(a: S, b: S) -> S:
+            ...
+
+    or in the case of different input types mapping to different output types:
+
+   .. code-block:: python
+
+        from typing import overload
+        import numpy as np
+
+        @overload
+        def phase(x: np.complex64) -> np.float32: ...
+        @overload
+        def phase(x: np.complex128) -> np.float64: ...
+        @overload
+        def phase(x: np.clongdouble) -> np.longdouble: ...
+        def phase(x: np.complexfloating) -> np.floating:
+            ...
+
+Timedelta64
+~~~~~~~~~~~
+
+The `~numpy.timedelta64` class is not considered a subclass of
+`~numpy.signedinteger`, the former only inheriting from `~numpy.generic`
+while static type checking.
+
+0D arrays
+~~~~~~~~~
+
+During runtime numpy aggressively casts any passed 0D arrays into their
+corresponding `~numpy.generic` instance. Until the introduction of shape
+typing (see :pep:`646`) it is unfortunately not possible to make the
+necessary distinction between 0D and >0D arrays. While thus not strictly
+correct, all operations that can potentially perform a 0D-array -> scalar
+cast are currently annotated as exclusively returning an `~numpy.ndarray`.
+
+If it is known in advance that an operation *will* perform a
+0D-array -> scalar cast, then one can consider manually remedying the
+situation with either `typing.cast` or a ``# type: ignore`` comment.
+
+Record array dtypes
+~~~~~~~~~~~~~~~~~~~
+
+The dtype of `numpy.recarray`, and the :ref:`routines.array-creation.rec`
+functions in general, can be specified in one of two ways:
+
+* Directly via the ``dtype`` argument.
+* With up to five helper arguments that operate via `numpy.rec.format_parser`:
+  ``formats``, ``names``, ``titles``, ``aligned`` and ``byteorder``.
+
+These two approaches are currently typed as being mutually exclusive,
+*i.e.* if ``dtype`` is specified than one may not specify ``formats``.
+While this mutual exclusivity is not (strictly) enforced during runtime,
+combining both dtype specifiers can lead to unexpected or even downright
+buggy behavior.
+
+API
+---
+
+"""
+# NOTE: The API section will be appended with additional entries
+# further down in this file
+
+# pyright: reportDeprecated=false
+
+from numpy._typing import ArrayLike, DTypeLike, NBitBase, NDArray
+
+__all__ = ["ArrayLike", "DTypeLike", "NBitBase", "NDArray"]
+
+
+__DIR = __all__ + [k for k in globals() if k.startswith("__") and k.endswith("__")]
+__DIR_SET = frozenset(__DIR)
+
+
+def __dir__() -> list[str]:
+    return __DIR
+
+def __getattr__(name: str) -> object:
+    if name == "NBitBase":
+        import warnings
+
+        # Deprecated in NumPy 2.3, 2025-05-01
+        warnings.warn(
+            "`NBitBase` is deprecated and will be removed from numpy.typing in the "
+            "future. Use `@typing.overload` or a `TypeVar` with a scalar-type as upper "
+            "bound, instead. (deprecated in NumPy 2.3)",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return NBitBase
+
+    if name in __DIR_SET:
+        return globals()[name]
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+if __doc__ is not None:
+    from numpy._typing._add_docstring import _docstrings
+    __doc__ += _docstrings
+    __doc__ += '\n.. autoclass:: numpy.typing.NBitBase\n'
+    del _docstrings
+
+from numpy._pytesttester import PytestTester
+
+test = PytestTester(__name__)
+del PytestTester

numpy/typing/__init__.pyi

@@ -0,0 +1,3 @@
+from numpy._typing import ArrayLike, DTypeLike, NBitBase, NDArray
+
+__all__ = ["ArrayLike", "DTypeLike", "NBitBase", "NDArray"]

numpy/typing/mypy_plugin.py

@@ -0,0 +1,200 @@
+"""A mypy_ plugin for managing a number of platform-specific annotations.
+Its functionality can be split into three distinct parts:
+
+* Assigning the (platform-dependent) precisions of certain `~numpy.number`
+  subclasses, including the likes of `~numpy.int_`, `~numpy.intp` and
+  `~numpy.longlong`. See the documentation on
+  :ref:`scalar types <arrays.scalars.built-in>` for a comprehensive overview
+  of the affected classes. Without the plugin the precision of all relevant
+  classes will be inferred as `~typing.Any`.
+* Removing all extended-precision `~numpy.number` subclasses that are
+  unavailable for the platform in question. Most notably this includes the
+  likes of `~numpy.float128` and `~numpy.complex256`. Without the plugin *all*
+  extended-precision types will, as far as mypy is concerned, be available
+  to all platforms.
+* Assigning the (platform-dependent) precision of `~numpy.ctypeslib.c_intp`.
+  Without the plugin the type will default to `ctypes.c_int64`.
+
+  .. versionadded:: 1.22
+
+.. deprecated:: 2.3
+    The :mod:`numpy.typing.mypy_plugin` entry-point is deprecated in favor of
+    platform-agnostic static type inference. Remove
+    ``numpy.typing.mypy_plugin`` from the ``plugins`` section of your mypy
+    configuration; if that surfaces new errors, please open an issue with a
+    minimal reproducer.
+
+Examples
+--------
+To enable the plugin, one must add it to their mypy `configuration file`_:
+
+.. code-block:: ini
+
+    [mypy]
+    plugins = numpy.typing.mypy_plugin
+
+.. _mypy: https://mypy-lang.org/
+.. _configuration file: https://mypy.readthedocs.io/en/stable/config_file.html
+
+"""
+
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Final, TypeAlias, cast
+
+import numpy as np
+
+__all__: list[str] = []
+
+
+def _get_precision_dict() -> dict[str, str]:
+    names = [
+        ("_NBitByte", np.byte),
+        ("_NBitShort", np.short),
+        ("_NBitIntC", np.intc),
+        ("_NBitIntP", np.intp),
+        ("_NBitInt", np.int_),
+        ("_NBitLong", np.long),
+        ("_NBitLongLong", np.longlong),
+
+        ("_NBitHalf", np.half),
+        ("_NBitSingle", np.single),
+        ("_NBitDouble", np.double),
+        ("_NBitLongDouble", np.longdouble),
+    ]
+    ret: dict[str, str] = {}
+    for name, typ in names:
+        n = 8 * np.dtype(typ).itemsize
+        ret[f"{_MODULE}._nbit.{name}"] = f"{_MODULE}._nbit_base._{n}Bit"
+    return ret
+
+
+def _get_extended_precision_list() -> list[str]:
+    extended_names = [
+        "float96",
+        "float128",
+        "complex192",
+        "complex256",
+    ]
+    return [i for i in extended_names if hasattr(np, i)]
+
+def _get_c_intp_name() -> str:
+    # Adapted from `np.core._internal._getintp_ctype`
+    return {
+        "i": "c_int",
+        "l": "c_long",
+        "q": "c_longlong",
+    }.get(np.dtype("n").char, "c_long")
+
+
+_MODULE: Final = "numpy._typing"
+
+#: A dictionary mapping type-aliases in `numpy._typing._nbit` to
+#: concrete `numpy.typing.NBitBase` subclasses.
+_PRECISION_DICT: Final = _get_precision_dict()
+
+#: A list with the names of all extended precision `np.number` subclasses.
+_EXTENDED_PRECISION_LIST: Final = _get_extended_precision_list()
+
+#: The name of the ctypes equivalent of `np.intp`
+_C_INTP: Final = _get_c_intp_name()
+
+
+try:
+    if TYPE_CHECKING:
+        from mypy.typeanal import TypeAnalyser
+
+    import mypy.types
+    from mypy.build import PRI_MED
+    from mypy.nodes import ImportFrom, MypyFile, Statement
+    from mypy.plugin import AnalyzeTypeContext, Plugin
+
+except ModuleNotFoundError as e:
+
+    def plugin(version: str) -> type:
+        raise e
+
+else:
+
+    _HookFunc: TypeAlias = Callable[[AnalyzeTypeContext], mypy.types.Type]
+
+    def _hook(ctx: AnalyzeTypeContext) -> mypy.types.Type:
+        """Replace a type-alias with a concrete ``NBitBase`` subclass."""
+        typ, _, api = ctx
+        name = typ.name.split(".")[-1]
+        name_new = _PRECISION_DICT[f"{_MODULE}._nbit.{name}"]
+        return cast("TypeAnalyser", api).named_type(name_new)
+
+    def _index(iterable: Iterable[Statement], id: str) -> int:
+        """Identify the first ``ImportFrom`` instance the specified `id`."""
+        for i, value in enumerate(iterable):
+            if getattr(value, "id", None) == id:
+                return i
+        raise ValueError("Failed to identify a `ImportFrom` instance "
+                         f"with the following id: {id!r}")
+
+    def _override_imports(
+        file: MypyFile,
+        module: str,
+        imports: list[tuple[str, str | None]],
+    ) -> None:
+        """Override the first `module`-based import with new `imports`."""
+        # Construct a new `from module import y` statement
+        import_obj = ImportFrom(module, 0, names=imports)
+        import_obj.is_top_level = True
+
+        # Replace the first `module`-based import statement with `import_obj`
+        for lst in [file.defs, cast("list[Statement]", file.imports)]:
+            i = _index(lst, module)
+            lst[i] = import_obj
+
+    class _NumpyPlugin(Plugin):
+        """A mypy plugin for handling versus numpy-specific typing tasks."""
+
+        def get_type_analyze_hook(self, fullname: str) -> _HookFunc | None:
+            """Set the precision of platform-specific `numpy.number`
+            subclasses.
+
+            For example: `numpy.int_`, `numpy.longlong` and `numpy.longdouble`.
+            """
+            if fullname in _PRECISION_DICT:
+                return _hook
+            return None
+
+        def get_additional_deps(
+            self, file: MypyFile
+        ) -> list[tuple[int, str, int]]:
+            """Handle all import-based overrides.
+
+            * Import platform-specific extended-precision `numpy.number`
+              subclasses (*e.g.* `numpy.float96` and `numpy.float128`).
+            * Import the appropriate `ctypes` equivalent to `numpy.intp`.
+
+            """
+            fullname = file.fullname
+            if fullname == "numpy":
+                _override_imports(
+                    file,
+                    f"{_MODULE}._extended_precision",
+                    imports=[(v, v) for v in _EXTENDED_PRECISION_LIST],
+                )
+            elif fullname == "numpy.ctypeslib":
+                _override_imports(
+                    file,
+                    "ctypes",
+                    imports=[(_C_INTP, "_c_intp")],
+                )
+            return [(PRI_MED, fullname, -1)]
+
+    def plugin(version: str) -> type:
+        import warnings
+
+        plugin = "numpy.typing.mypy_plugin"
+        # Deprecated 2025-01-10, NumPy 2.3
+        warn_msg = (
+            f"`{plugin}` is deprecated, and will be removed in a future "
+            f"release. Please remove `plugins = {plugin}` in your mypy config."
+            f"(deprecated in NumPy 2.3)"
+        )
+        warnings.warn(warn_msg, DeprecationWarning, stacklevel=3)
+
+        return _NumpyPlugin