numpy 2.3.5__cp313-cp313-macosx_14_0_arm64.whl

numpy/lib/_utils_impl.pyi

@@ -0,0 +1,10 @@
+from _typeshed import SupportsWrite
+
+from numpy._typing import DTypeLike
+
+__all__ = ["get_include", "info", "show_runtime"]
+
+def get_include() -> str: ...
+def show_runtime() -> None: ...
+def info(object: object = ..., maxwidth: int = ..., output: SupportsWrite[str] | None = ..., toplevel: str = ...) -> None: ...
+def drop_metadata(dtype: DTypeLike, /) -> DTypeLike: ...

numpy/lib/_version.py

@@ -0,0 +1,154 @@
+"""Utility to compare (NumPy) version strings.
+
+The NumpyVersion class allows properly comparing numpy version strings.
+The LooseVersion and StrictVersion classes that distutils provides don't
+work; they don't recognize anything like alpha/beta/rc/dev versions.
+
+"""
+import re
+
+__all__ = ['NumpyVersion']
+
+
+class NumpyVersion:
+    """Parse and compare numpy version strings.
+
+    NumPy has the following versioning scheme (numbers given are examples; they
+    can be > 9 in principle):
+
+    - Released version: '1.8.0', '1.8.1', etc.
+    - Alpha: '1.8.0a1', '1.8.0a2', etc.
+    - Beta: '1.8.0b1', '1.8.0b2', etc.
+    - Release candidates: '1.8.0rc1', '1.8.0rc2', etc.
+    - Development versions: '1.8.0.dev-f1234afa' (git commit hash appended)
+    - Development versions after a1: '1.8.0a1.dev-f1234afa',
+                                     '1.8.0b2.dev-f1234afa',
+                                     '1.8.1rc1.dev-f1234afa', etc.
+    - Development versions (no git hash available): '1.8.0.dev-Unknown'
+
+    Comparing needs to be done against a valid version string or other
+    `NumpyVersion` instance. Note that all development versions of the same
+    (pre-)release compare equal.
+
+    Parameters
+    ----------
+    vstring : str
+        NumPy version string (``np.__version__``).
+
+    Examples
+    --------
+    >>> from numpy.lib import NumpyVersion
+    >>> if NumpyVersion(np.__version__) < '1.7.0':
+    ...     print('skip')
+    >>> # skip
+
+    >>> NumpyVersion('1.7')  # raises ValueError, add ".0"
+    Traceback (most recent call last):
+        ...
+    ValueError: Not a valid numpy version string
+
+    """
+
+    __module__ = "numpy.lib"
+
+    def __init__(self, vstring):
+        self.vstring = vstring
+        ver_main = re.match(r'\d+\.\d+\.\d+', vstring)
+        if not ver_main:
+            raise ValueError("Not a valid numpy version string")
+
+        self.version = ver_main.group()
+        self.major, self.minor, self.bugfix = [int(x) for x in
+            self.version.split('.')]
+        if len(vstring) == ver_main.end():
+            self.pre_release = 'final'
+        else:
+            alpha = re.match(r'a\d', vstring[ver_main.end():])
+            beta = re.match(r'b\d', vstring[ver_main.end():])
+            rc = re.match(r'rc\d', vstring[ver_main.end():])
+            pre_rel = [m for m in [alpha, beta, rc] if m is not None]
+            if pre_rel:
+                self.pre_release = pre_rel[0].group()
+            else:
+                self.pre_release = ''
+
+        self.is_devversion = bool(re.search(r'.dev', vstring))
+
+    def _compare_version(self, other):
+        """Compare major.minor.bugfix"""
+        if self.major == other.major:
+            if self.minor == other.minor:
+                if self.bugfix == other.bugfix:
+                    vercmp = 0
+                elif self.bugfix > other.bugfix:
+                    vercmp = 1
+                else:
+                    vercmp = -1
+            elif self.minor > other.minor:
+                vercmp = 1
+            else:
+                vercmp = -1
+        elif self.major > other.major:
+            vercmp = 1
+        else:
+            vercmp = -1
+
+        return vercmp
+
+    def _compare_pre_release(self, other):
+        """Compare alpha/beta/rc/final."""
+        if self.pre_release == other.pre_release:
+            vercmp = 0
+        elif self.pre_release == 'final':
+            vercmp = 1
+        elif other.pre_release == 'final':
+            vercmp = -1
+        elif self.pre_release > other.pre_release:
+            vercmp = 1
+        else:
+            vercmp = -1
+
+        return vercmp
+
+    def _compare(self, other):
+        if not isinstance(other, (str, NumpyVersion)):
+            raise ValueError("Invalid object to compare with NumpyVersion.")
+
+        if isinstance(other, str):
+            other = NumpyVersion(other)
+
+        vercmp = self._compare_version(other)
+        if vercmp == 0:
+            # Same x.y.z version, check for alpha/beta/rc
+            vercmp = self._compare_pre_release(other)
+            if vercmp == 0:
+                # Same version and same pre-release, check if dev version
+                if self.is_devversion is other.is_devversion:
+                    vercmp = 0
+                elif self.is_devversion:
+                    vercmp = -1
+                else:
+                    vercmp = 1
+
+        return vercmp
+
+    def __lt__(self, other):
+        return self._compare(other) < 0
+
+    def __le__(self, other):
+        return self._compare(other) <= 0
+
+    def __eq__(self, other):
+        return self._compare(other) == 0
+
+    def __ne__(self, other):
+        return self._compare(other) != 0
+
+    def __gt__(self, other):
+        return self._compare(other) > 0
+
+    def __ge__(self, other):
+        return self._compare(other) >= 0
+
+    def __repr__(self):
+        return f"NumpyVersion({self.vstring})"

numpy/lib/_version.pyi

@@ -0,0 +1,17 @@
+__all__ = ["NumpyVersion"]
+
+class NumpyVersion:
+    vstring: str
+    version: str
+    major: int
+    minor: int
+    bugfix: int
+    pre_release: str
+    is_devversion: bool
+    def __init__(self, vstring: str) -> None: ...
+    def __lt__(self, other: str | NumpyVersion) -> bool: ...
+    def __le__(self, other: str | NumpyVersion) -> bool: ...
+    def __eq__(self, other: str | NumpyVersion) -> bool: ...  # type: ignore[override]
+    def __ne__(self, other: str | NumpyVersion) -> bool: ...  # type: ignore[override]
+    def __gt__(self, other: str | NumpyVersion) -> bool: ...
+    def __ge__(self, other: str | NumpyVersion) -> bool: ...

numpy/lib/array_utils.py

@@ -0,0 +1,7 @@
+from ._array_utils_impl import (  # noqa: F401
+    __all__,
+    __doc__,
+    byte_bounds,
+    normalize_axis_index,
+    normalize_axis_tuple,
+)

numpy/lib/array_utils.pyi

@@ -0,0 +1,12 @@
+from ._array_utils_impl import (
+    __all__ as __all__,
+)
+from ._array_utils_impl import (
+    byte_bounds as byte_bounds,
+)
+from ._array_utils_impl import (
+    normalize_axis_index as normalize_axis_index,
+)
+from ._array_utils_impl import (
+    normalize_axis_tuple as normalize_axis_tuple,
+)

numpy/lib/format.py

@@ -0,0 +1,24 @@
+from ._format_impl import (  # noqa: F401
+    ARRAY_ALIGN,
+    BUFFER_SIZE,
+    EXPECTED_KEYS,
+    GROWTH_AXIS_MAX_DIGITS,
+    MAGIC_LEN,
+    MAGIC_PREFIX,
+    __all__,
+    __doc__,
+    descr_to_dtype,
+    drop_metadata,
+    dtype_to_descr,
+    header_data_from_array_1_0,
+    isfileobj,
+    magic,
+    open_memmap,
+    read_array,
+    read_array_header_1_0,
+    read_array_header_2_0,
+    read_magic,
+    write_array,
+    write_array_header_1_0,
+    write_array_header_2_0,
+)

numpy/lib/format.pyi

@@ -0,0 +1,66 @@
+from ._format_impl import (
+    ARRAY_ALIGN as ARRAY_ALIGN,
+)
+from ._format_impl import (
+    BUFFER_SIZE as BUFFER_SIZE,
+)
+from ._format_impl import (
+    EXPECTED_KEYS as EXPECTED_KEYS,
+)
+from ._format_impl import (
+    GROWTH_AXIS_MAX_DIGITS as GROWTH_AXIS_MAX_DIGITS,
+)
+from ._format_impl import (
+    MAGIC_LEN as MAGIC_LEN,
+)
+from ._format_impl import (
+    MAGIC_PREFIX as MAGIC_PREFIX,
+)
+from ._format_impl import (
+    __all__ as __all__,
+)
+from ._format_impl import (
+    __doc__ as __doc__,
+)
+from ._format_impl import (
+    descr_to_dtype as descr_to_dtype,
+)
+from ._format_impl import (
+    drop_metadata as drop_metadata,
+)
+from ._format_impl import (
+    dtype_to_descr as dtype_to_descr,
+)
+from ._format_impl import (
+    header_data_from_array_1_0 as header_data_from_array_1_0,
+)
+from ._format_impl import (
+    isfileobj as isfileobj,
+)
+from ._format_impl import (
+    magic as magic,
+)
+from ._format_impl import (
+    open_memmap as open_memmap,
+)
+from ._format_impl import (
+    read_array as read_array,
+)
+from ._format_impl import (
+    read_array_header_1_0 as read_array_header_1_0,
+)
+from ._format_impl import (
+    read_array_header_2_0 as read_array_header_2_0,
+)
+from ._format_impl import (
+    read_magic as read_magic,
+)
+from ._format_impl import (
+    write_array as write_array,
+)
+from ._format_impl import (
+    write_array_header_1_0 as write_array_header_1_0,
+)
+from ._format_impl import (
+    write_array_header_2_0 as write_array_header_2_0,
+)

numpy/lib/introspect.py

@@ -0,0 +1,95 @@
+"""
+Introspection helper functions.
+"""
+
+__all__ = ['opt_func_info']
+
+
+def opt_func_info(func_name=None, signature=None):
+    """
+    Returns a dictionary containing the currently supported CPU dispatched
+    features for all optimized functions.
+
+    Parameters
+    ----------
+    func_name : str (optional)
+        Regular expression to filter by function name.
+
+    signature : str (optional)
+        Regular expression to filter by data type.
+
+    Returns
+    -------
+    dict
+        A dictionary where keys are optimized function names and values are
+        nested dictionaries indicating supported targets based on data types.
+
+    Examples
+    --------
+    Retrieve dispatch information for functions named 'add' or 'sub' and
+    data types 'float64' or 'float32':
+
+    >>> import numpy as np
+    >>> dict = np.lib.introspect.opt_func_info(
+    ...     func_name="add|abs", signature="float64|complex64"
+    ... )
+    >>> import json
+    >>> print(json.dumps(dict, indent=2))
+        {
+          "absolute": {
+            "dd": {
+              "current": "SSE41",
+              "available": "SSE41 baseline(SSE SSE2 SSE3)"
+            },
+            "Ff": {
+              "current": "FMA3__AVX2",
+              "available": "AVX512F FMA3__AVX2 baseline(SSE SSE2 SSE3)"
+            },
+            "Dd": {
+              "current": "FMA3__AVX2",
+              "available": "AVX512F FMA3__AVX2 baseline(SSE SSE2 SSE3)"
+            }
+          },
+          "add": {
+            "ddd": {
+              "current": "FMA3__AVX2",
+              "available": "FMA3__AVX2 baseline(SSE SSE2 SSE3)"
+            },
+            "FFF": {
+              "current": "FMA3__AVX2",
+              "available": "FMA3__AVX2 baseline(SSE SSE2 SSE3)"
+            }
+          }
+        }
+
+    """
+    import re
+
+    from numpy._core._multiarray_umath import __cpu_targets_info__ as targets
+    from numpy._core._multiarray_umath import dtype
+
+    if func_name is not None:
+        func_pattern = re.compile(func_name)
+        matching_funcs = {
+            k: v for k, v in targets.items()
+            if func_pattern.search(k)
+        }
+    else:
+        matching_funcs = targets
+
+    if signature is not None:
+        sig_pattern = re.compile(signature)
+        matching_sigs = {}
+        for k, v in matching_funcs.items():
+            matching_chars = {}
+            for chars, targets in v.items():
+                if any(
+                    sig_pattern.search(c) or sig_pattern.search(dtype(c).name)
+                    for c in chars
+                ):
+                    matching_chars[chars] = targets
+            if matching_chars:
+                matching_sigs[k] = matching_chars
+    else:
+        matching_sigs = matching_funcs
+    return matching_sigs

numpy/lib/introspect.pyi

@@ -0,0 +1,3 @@
+__all__ = ["opt_func_info"]
+
+def opt_func_info(func_name: str | None = None, signature: str | None = None) -> dict[str, dict[str, dict[str, str]]]: ...

numpy/lib/mixins.py

@@ -0,0 +1,180 @@
+"""
+Mixin classes for custom array types that don't inherit from ndarray.
+"""
+
+__all__ = ['NDArrayOperatorsMixin']
+
+
+def _disables_array_ufunc(obj):
+    """True when __array_ufunc__ is set to None."""
+    try:
+        return obj.__array_ufunc__ is None
+    except AttributeError:
+        return False
+
+
+def _binary_method(ufunc, name):
+    """Implement a forward binary method with a ufunc, e.g., __add__."""
+    def func(self, other):
+        if _disables_array_ufunc(other):
+            return NotImplemented
+        return ufunc(self, other)
+    func.__name__ = f'__{name}__'
+    return func
+
+
+def _reflected_binary_method(ufunc, name):
+    """Implement a reflected binary method with a ufunc, e.g., __radd__."""
+    def func(self, other):
+        if _disables_array_ufunc(other):
+            return NotImplemented
+        return ufunc(other, self)
+    func.__name__ = f'__r{name}__'
+    return func
+
+
+def _inplace_binary_method(ufunc, name):
+    """Implement an in-place binary method with a ufunc, e.g., __iadd__."""
+    def func(self, other):
+        return ufunc(self, other, out=(self,))
+    func.__name__ = f'__i{name}__'
+    return func
+
+
+def _numeric_methods(ufunc, name):
+    """Implement forward, reflected and inplace binary methods with a ufunc."""
+    return (_binary_method(ufunc, name),
+            _reflected_binary_method(ufunc, name),
+            _inplace_binary_method(ufunc, name))
+
+
+def _unary_method(ufunc, name):
+    """Implement a unary special method with a ufunc."""
+    def func(self):
+        return ufunc(self)
+    func.__name__ = f'__{name}__'
+    return func
+
+
+class NDArrayOperatorsMixin:
+    """Mixin defining all operator special methods using __array_ufunc__.
+
+    This class implements the special methods for almost all of Python's
+    builtin operators defined in the `operator` module, including comparisons
+    (``==``, ``>``, etc.) and arithmetic (``+``, ``*``, ``-``, etc.), by
+    deferring to the ``__array_ufunc__`` method, which subclasses must
+    implement.
+
+    It is useful for writing classes that do not inherit from `numpy.ndarray`,
+    but that should support arithmetic and numpy universal functions like
+    arrays as described in :external+neps:doc:`nep-0013-ufunc-overrides`.
+
+    As an trivial example, consider this implementation of an ``ArrayLike``
+    class that simply wraps a NumPy array and ensures that the result of any
+    arithmetic operation is also an ``ArrayLike`` object:
+
+        >>> import numbers
+        >>> class ArrayLike(np.lib.mixins.NDArrayOperatorsMixin):
+        ...     def __init__(self, value):
+        ...         self.value = np.asarray(value)
+        ...
+        ...     # One might also consider adding the built-in list type to this
+        ...     # list, to support operations like np.add(array_like, list)
+        ...     _HANDLED_TYPES = (np.ndarray, numbers.Number)
+        ...
+        ...     def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
+        ...         out = kwargs.get('out', ())
+        ...         for x in inputs + out:
+        ...             # Only support operations with instances of
+        ...             # _HANDLED_TYPES. Use ArrayLike instead of type(self)
+        ...             # for isinstance to allow subclasses that don't
+        ...             # override __array_ufunc__ to handle ArrayLike objects.
+        ...             if not isinstance(
+        ...                 x, self._HANDLED_TYPES + (ArrayLike,)
+        ...             ):
+        ...                 return NotImplemented
+        ...
+        ...         # Defer to the implementation of the ufunc
+        ...         # on unwrapped values.
+        ...         inputs = tuple(x.value if isinstance(x, ArrayLike) else x
+        ...                     for x in inputs)
+        ...         if out:
+        ...             kwargs['out'] = tuple(
+        ...                 x.value if isinstance(x, ArrayLike) else x
+        ...                 for x in out)
+        ...         result = getattr(ufunc, method)(*inputs, **kwargs)
+        ...
+        ...         if type(result) is tuple:
+        ...             # multiple return values
+        ...             return tuple(type(self)(x) for x in result)
+        ...         elif method == 'at':
+        ...             # no return value
+        ...             return None
+        ...         else:
+        ...             # one return value
+        ...             return type(self)(result)
+        ...
+        ...     def __repr__(self):
+        ...         return '%s(%r)' % (type(self).__name__, self.value)
+
+    In interactions between ``ArrayLike`` objects and numbers or numpy arrays,
+    the result is always another ``ArrayLike``:
+
+        >>> x = ArrayLike([1, 2, 3])
+        >>> x - 1
+        ArrayLike(array([0, 1, 2]))
+        >>> 1 - x
+        ArrayLike(array([ 0, -1, -2]))
+        >>> np.arange(3) - x
+        ArrayLike(array([-1, -1, -1]))
+        >>> x - np.arange(3)
+        ArrayLike(array([1, 1, 1]))
+
+    Note that unlike ``numpy.ndarray``, ``ArrayLike`` does not allow operations
+    with arbitrary, unrecognized types. This ensures that interactions with
+    ArrayLike preserve a well-defined casting hierarchy.
+
+    """
+    from numpy._core import umath as um
+
+    __slots__ = ()
+    # Like np.ndarray, this mixin class implements "Option 1" from the ufunc
+    # overrides NEP.
+
+    # comparisons don't have reflected and in-place versions
+    __lt__ = _binary_method(um.less, 'lt')
+    __le__ = _binary_method(um.less_equal, 'le')
+    __eq__ = _binary_method(um.equal, 'eq')
+    __ne__ = _binary_method(um.not_equal, 'ne')
+    __gt__ = _binary_method(um.greater, 'gt')
+    __ge__ = _binary_method(um.greater_equal, 'ge')
+
+    # numeric methods
+    __add__, __radd__, __iadd__ = _numeric_methods(um.add, 'add')
+    __sub__, __rsub__, __isub__ = _numeric_methods(um.subtract, 'sub')
+    __mul__, __rmul__, __imul__ = _numeric_methods(um.multiply, 'mul')
+    __matmul__, __rmatmul__, __imatmul__ = _numeric_methods(
+        um.matmul, 'matmul')
+    __truediv__, __rtruediv__, __itruediv__ = _numeric_methods(
+        um.true_divide, 'truediv')
+    __floordiv__, __rfloordiv__, __ifloordiv__ = _numeric_methods(
+        um.floor_divide, 'floordiv')
+    __mod__, __rmod__, __imod__ = _numeric_methods(um.remainder, 'mod')
+    __divmod__ = _binary_method(um.divmod, 'divmod')
+    __rdivmod__ = _reflected_binary_method(um.divmod, 'divmod')
+    # __idivmod__ does not exist
+    # TODO: handle the optional third argument for __pow__?
+    __pow__, __rpow__, __ipow__ = _numeric_methods(um.power, 'pow')
+    __lshift__, __rlshift__, __ilshift__ = _numeric_methods(
+        um.left_shift, 'lshift')
+    __rshift__, __rrshift__, __irshift__ = _numeric_methods(
+        um.right_shift, 'rshift')
+    __and__, __rand__, __iand__ = _numeric_methods(um.bitwise_and, 'and')
+    __xor__, __rxor__, __ixor__ = _numeric_methods(um.bitwise_xor, 'xor')
+    __or__, __ror__, __ior__ = _numeric_methods(um.bitwise_or, 'or')
+
+    # unary methods
+    __neg__ = _unary_method(um.negative, 'neg')
+    __pos__ = _unary_method(um.positive, 'pos')
+    __abs__ = _unary_method(um.absolute, 'abs')
+    __invert__ = _unary_method(um.invert, 'invert')

numpy/lib/mixins.pyi

@@ -0,0 +1,77 @@
+from abc import ABC, abstractmethod
+from typing import Any
+from typing import Literal as L
+
+from numpy import ufunc
+
+__all__ = ["NDArrayOperatorsMixin"]
+
+# NOTE: `NDArrayOperatorsMixin` is not formally an abstract baseclass,
+# even though it's reliant on subclasses implementing `__array_ufunc__`
+
+# NOTE: The accepted input- and output-types of the various dunders are
+# completely dependent on how `__array_ufunc__` is implemented.
+# As such, only little type safety can be provided here.
+
+class NDArrayOperatorsMixin(ABC):
+    __slots__ = ()
+
+    @abstractmethod
+    def __array_ufunc__(
+        self,
+        ufunc: ufunc,
+        method: L["__call__", "reduce", "reduceat", "accumulate", "outer", "at"],
+        *inputs: Any,
+        **kwargs: Any,
+    ) -> Any: ...
+    def __lt__(self, other: Any) -> Any: ...
+    def __le__(self, other: Any) -> Any: ...
+    def __eq__(self, other: Any) -> Any: ...
+    def __ne__(self, other: Any) -> Any: ...
+    def __gt__(self, other: Any) -> Any: ...
+    def __ge__(self, other: Any) -> Any: ...
+    def __add__(self, other: Any) -> Any: ...
+    def __radd__(self, other: Any) -> Any: ...
+    def __iadd__(self, other: Any) -> Any: ...
+    def __sub__(self, other: Any) -> Any: ...
+    def __rsub__(self, other: Any) -> Any: ...
+    def __isub__(self, other: Any) -> Any: ...
+    def __mul__(self, other: Any) -> Any: ...
+    def __rmul__(self, other: Any) -> Any: ...
+    def __imul__(self, other: Any) -> Any: ...
+    def __matmul__(self, other: Any) -> Any: ...
+    def __rmatmul__(self, other: Any) -> Any: ...
+    def __imatmul__(self, other: Any) -> Any: ...
+    def __truediv__(self, other: Any) -> Any: ...
+    def __rtruediv__(self, other: Any) -> Any: ...
+    def __itruediv__(self, other: Any) -> Any: ...
+    def __floordiv__(self, other: Any) -> Any: ...
+    def __rfloordiv__(self, other: Any) -> Any: ...
+    def __ifloordiv__(self, other: Any) -> Any: ...
+    def __mod__(self, other: Any) -> Any: ...
+    def __rmod__(self, other: Any) -> Any: ...
+    def __imod__(self, other: Any) -> Any: ...
+    def __divmod__(self, other: Any) -> Any: ...
+    def __rdivmod__(self, other: Any) -> Any: ...
+    def __pow__(self, other: Any) -> Any: ...
+    def __rpow__(self, other: Any) -> Any: ...
+    def __ipow__(self, other: Any) -> Any: ...
+    def __lshift__(self, other: Any) -> Any: ...
+    def __rlshift__(self, other: Any) -> Any: ...
+    def __ilshift__(self, other: Any) -> Any: ...
+    def __rshift__(self, other: Any) -> Any: ...
+    def __rrshift__(self, other: Any) -> Any: ...
+    def __irshift__(self, other: Any) -> Any: ...
+    def __and__(self, other: Any) -> Any: ...
+    def __rand__(self, other: Any) -> Any: ...
+    def __iand__(self, other: Any) -> Any: ...
+    def __xor__(self, other: Any) -> Any: ...
+    def __rxor__(self, other: Any) -> Any: ...
+    def __ixor__(self, other: Any) -> Any: ...
+    def __or__(self, other: Any) -> Any: ...
+    def __ror__(self, other: Any) -> Any: ...
+    def __ior__(self, other: Any) -> Any: ...
+    def __neg__(self) -> Any: ...
+    def __pos__(self) -> Any: ...
+    def __abs__(self) -> Any: ...
+    def __invert__(self) -> Any: ...

numpy/lib/npyio.py

@@ -0,0 +1 @@
+from ._npyio_impl import DataSource, NpzFile, __doc__  # noqa: F401

numpy/lib/npyio.pyi

@@ -0,0 +1,9 @@
+from numpy.lib._npyio_impl import (
+    DataSource as DataSource,
+)
+from numpy.lib._npyio_impl import (
+    NpzFile as NpzFile,
+)
+from numpy.lib._npyio_impl import (
+    __doc__ as __doc__,
+)