numpy 2.3.5__cp313-cp313-macosx_14_0_arm64.whl

numpy/_core/_ufunc_config.py

@@ -0,0 +1,491 @@
+"""
+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.
+
+    .. [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`.
+
+    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.
+
+    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.
+
+    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
+
+    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`.
+
+    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`.
+
+    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

numpy/_core/_ufunc_config.pyi

@@ -0,0 +1,78 @@
+from collections.abc import Callable
+from types import TracebackType
+from typing import (
+    Any,
+    Final,
+    Literal,
+    TypeAlias,
+    TypedDict,
+    TypeVar,
+    type_check_only,
+)
+
+from _typeshed import SupportsWrite
+
+__all__ = [
+    "seterr",
+    "geterr",
+    "setbufsize",
+    "getbufsize",
+    "seterrcall",
+    "geterrcall",
+    "errstate",
+]
+
+_ErrKind: TypeAlias = Literal["ignore", "warn", "raise", "call", "print", "log"]
+_ErrCall: TypeAlias = Callable[[str, int], Any] | SupportsWrite[str]
+
+_CallableT = TypeVar("_CallableT", bound=Callable[..., object])
+
+@type_check_only
+class _ErrDict(TypedDict):
+    divide: _ErrKind
+    over: _ErrKind
+    under: _ErrKind
+    invalid: _ErrKind
+
+###
+
+class _unspecified: ...
+
+_Unspecified: Final[_unspecified]
+
+class errstate:
+    __slots__ = "_all", "_call", "_divide", "_invalid", "_over", "_token", "_under"
+
+    def __init__(
+        self,
+        /,
+        *,
+        call: _ErrCall | _unspecified = ...,  # = _Unspecified
+        all: _ErrKind | None = None,
+        divide: _ErrKind | None = None,
+        over: _ErrKind | None = None,
+        under: _ErrKind | None = None,
+        invalid: _ErrKind | None = None,
+    ) -> None: ...
+    def __call__(self, /, func: _CallableT) -> _CallableT: ...
+    def __enter__(self) -> None: ...
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+        /,
+    ) -> None: ...
+
+def seterr(
+    all: _ErrKind | None = ...,
+    divide: _ErrKind | None = ...,
+    over: _ErrKind | None = ...,
+    under: _ErrKind | None = ...,
+    invalid: _ErrKind | None = ...,
+) -> _ErrDict: ...
+def geterr() -> _ErrDict: ...
+def setbufsize(size: int) -> int: ...
+def getbufsize() -> int: ...
+def seterrcall(func: _ErrCall | None) -> _ErrCall | None: ...
+def geterrcall() -> _ErrCall | None: ...