numpy 2.4.1__pp311-pypy311_pp73-macosx_14_0_arm64.whl

numpy/_utils/__init__.py

@@ -0,0 +1,95 @@
+"""
+This is a module for defining private helpers which do not depend on the
+rest of NumPy.
+
+Everything in here must be self-contained so that it can be
+imported anywhere else without creating circular imports.
+If a utility requires the import of NumPy, it probably belongs
+in ``numpy._core``.
+"""
+
+import functools
+import warnings
+
+from ._convertions import asbytes, asunicode
+
+
+def set_module(module):
+    """Private decorator for overriding __module__ on a function or class.
+
+    Example usage::
+
+        @set_module('numpy')
+        def example():
+            pass
+
+        assert example.__module__ == 'numpy'
+    """
+    def decorator(func):
+        if module is not None:
+            if isinstance(func, type):
+                try:
+                    func._module_source = func.__module__
+                except (AttributeError):
+                    pass
+
+            func.__module__ = module
+        return func
+    return decorator
+
+
+def _rename_parameter(old_names, new_names, dep_version=None):
+    """
+    Generate decorator for backward-compatible keyword renaming.
+
+    Apply the decorator generated by `_rename_parameter` to functions with a
+    renamed parameter to maintain backward-compatibility.
+
+    After decoration, the function behaves as follows:
+    If only the new parameter is passed into the function, behave as usual.
+    If only the old parameter is passed into the function (as a keyword), raise
+    a DeprecationWarning if `dep_version` is provided, and behave as usual
+    otherwise.
+    If both old and new parameters are passed into the function, raise a
+    DeprecationWarning if `dep_version` is provided, and raise the appropriate
+    TypeError (function got multiple values for argument).
+
+    Parameters
+    ----------
+    old_names : list of str
+        Old names of parameters
+    new_name : list of str
+        New names of parameters
+    dep_version : str, optional
+        Version of NumPy in which old parameter was deprecated in the format
+        'X.Y.Z'. If supplied, the deprecation message will indicate that
+        support for the old parameter will be removed in version 'X.Y+2.Z'
+
+    Notes
+    -----
+    Untested with functions that accept *args. Probably won't work as written.
+
+    """
+    def decorator(fun):
+        @functools.wraps(fun)
+        def wrapper(*args, **kwargs):
+            __tracebackhide__ = True  # Hide traceback for py.test
+            for old_name, new_name in zip(old_names, new_names):
+                if old_name in kwargs:
+                    if dep_version:
+                        end_version = dep_version.split('.')
+                        end_version[1] = str(int(end_version[1]) + 2)
+                        end_version = '.'.join(end_version)
+                        msg = (f"Use of keyword argument `{old_name}` is "
+                               f"deprecated and replaced by `{new_name}`. "
+                               f"Support for `{old_name}` will be removed "
+                               f"in NumPy {end_version}.")
+                        warnings.warn(msg, DeprecationWarning, stacklevel=2)
+                    if new_name in kwargs:
+                        msg = (f"{fun.__name__}() got multiple values for "
+                               f"argument now known as `{new_name}`")
+                        raise TypeError(msg)
+                    kwargs[new_name] = kwargs.pop(old_name)
+            return fun(*args, **kwargs)
+        return wrapper
+    return decorator

numpy/_utils/__init__.pyi

@@ -0,0 +1,28 @@
+from _typeshed import IdentityFunction
+from collections.abc import Callable, Iterable
+from typing import Protocol, TypeVar, overload, type_check_only
+
+from ._convertions import asbytes as asbytes, asunicode as asunicode
+
+###
+
+_T = TypeVar("_T")
+_HasModuleT = TypeVar("_HasModuleT", bound=_HasModule)
+
+@type_check_only
+class _HasModule(Protocol):
+    __module__: str
+
+###
+
+@overload
+def set_module(module: None) -> IdentityFunction: ...
+@overload
+def set_module(module: str) -> Callable[[_HasModuleT], _HasModuleT]: ...
+
+#
+def _rename_parameter(
+    old_names: Iterable[str],
+    new_names: Iterable[str],
+    dep_version: str | None = None,
+) -> Callable[[Callable[..., _T]], Callable[..., _T]]: ...

numpy/_utils/_convertions.py

@@ -0,0 +1,18 @@
+"""
+A set of methods retained from np.compat module that
+are still used across codebase.
+"""
+
+__all__ = ["asunicode", "asbytes"]
+
+
+def asunicode(s):
+    if isinstance(s, bytes):
+        return s.decode('latin1')
+    return str(s)
+
+
+def asbytes(s):
+    if isinstance(s, bytes):
+        return s
+    return str(s).encode('latin1')

numpy/_utils/_convertions.pyi

@@ -0,0 +1,4 @@
+__all__ = ["asbytes", "asunicode"]
+
+def asunicode(s: bytes | str) -> str: ...
+def asbytes(s: bytes | str) -> str: ...

numpy/_utils/_inspect.py

@@ -0,0 +1,192 @@
+"""Subset of inspect module from upstream python
+
+We use this instead of upstream because upstream inspect is slow to import, and
+significantly contributes to numpy import times. Importing this copy has almost
+no overhead.
+
+"""
+import types
+
+__all__ = ['getargspec', 'formatargspec']
+
+# ----------------------------------------------------------- type-checking
+def ismethod(object):
+    """Return true if the object is an instance method.
+
+    Instance method objects provide these attributes:
+        __doc__         documentation string
+        __name__        name with which this method was defined
+        im_class        class object in which this method belongs
+        im_func         function object containing implementation of method
+        im_self         instance to which this method is bound, or None
+
+    """
+    return isinstance(object, types.MethodType)
+
+def isfunction(object):
+    """Return true if the object is a user-defined function.
+
+    Function objects provide these attributes:
+        __doc__         documentation string
+        __name__        name with which this function was defined
+        func_code       code object containing compiled function bytecode
+        func_defaults   tuple of any default values for arguments
+        func_doc        (same as __doc__)
+        func_globals    global namespace in which this function was defined
+        func_name       (same as __name__)
+
+    """
+    return isinstance(object, types.FunctionType)
+
+def iscode(object):
+    """Return true if the object is a code object.
+
+    Code objects provide these attributes:
+        co_argcount     number of arguments (not including * or ** args)
+        co_code         string of raw compiled bytecode
+        co_consts       tuple of constants used in the bytecode
+        co_filename     name of file in which this code object was created
+        co_firstlineno  number of first line in Python source code
+        co_flags        bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
+        co_lnotab       encoded mapping of line numbers to bytecode indices
+        co_name         name with which this code object was defined
+        co_names        tuple of names of local variables
+        co_nlocals      number of local variables
+        co_stacksize    virtual machine stack space required
+        co_varnames     tuple of names of arguments and local variables
+
+    """
+    return isinstance(object, types.CodeType)
+
+
+# ------------------------------------------------ argument list extraction
+# These constants are from Python's compile.h.
+CO_OPTIMIZED, CO_NEWLOCALS, CO_VARARGS, CO_VARKEYWORDS = 1, 2, 4, 8
+
+def getargs(co):
+    """Get information about the arguments accepted by a code object.
+
+    Three things are returned: (args, varargs, varkw), where 'args' is
+    a list of argument names (possibly containing nested lists), and
+    'varargs' and 'varkw' are the names of the * and ** arguments or None.
+
+    """
+
+    if not iscode(co):
+        raise TypeError('arg is not a code object')
+
+    nargs = co.co_argcount
+    names = co.co_varnames
+    args = list(names[:nargs])
+
+    # The following acrobatics are for anonymous (tuple) arguments.
+    # Which we do not need to support, so remove to avoid importing
+    # the dis module.
+    for i in range(nargs):
+        if args[i][:1] in ['', '.']:
+            raise TypeError("tuple function arguments are not supported")
+    varargs = None
+    if co.co_flags & CO_VARARGS:
+        varargs = co.co_varnames[nargs]
+        nargs = nargs + 1
+    varkw = None
+    if co.co_flags & CO_VARKEYWORDS:
+        varkw = co.co_varnames[nargs]
+    return args, varargs, varkw
+
+def getargspec(func):
+    """Get the names and default values of a function's arguments.
+
+    A tuple of four things is returned: (args, varargs, varkw, defaults).
+    'args' is a list of the argument names (it may contain nested lists).
+    'varargs' and 'varkw' are the names of the * and ** arguments or None.
+    'defaults' is an n-tuple of the default values of the last n arguments.
+
+    """
+
+    if ismethod(func):
+        func = func.__func__
+    if not isfunction(func):
+        raise TypeError('arg is not a Python function')
+    args, varargs, varkw = getargs(func.__code__)
+    return args, varargs, varkw, func.__defaults__
+
+def getargvalues(frame):
+    """Get information about arguments passed into a particular frame.
+
+    A tuple of four things is returned: (args, varargs, varkw, locals).
+    'args' is a list of the argument names (it may contain nested lists).
+    'varargs' and 'varkw' are the names of the * and ** arguments or None.
+    'locals' is the locals dictionary of the given frame.
+
+    """
+    args, varargs, varkw = getargs(frame.f_code)
+    return args, varargs, varkw, frame.f_locals
+
+def joinseq(seq):
+    if len(seq) == 1:
+        return '(' + seq[0] + ',)'
+    else:
+        return '(' + ', '.join(seq) + ')'
+
+def strseq(object, convert, join=joinseq):
+    """Recursively walk a sequence, stringifying each element.
+
+    """
+    if type(object) in [list, tuple]:
+        return join([strseq(_o, convert, join) for _o in object])
+    else:
+        return convert(object)
+
+def formatargspec(args, varargs=None, varkw=None, defaults=None,
+                  formatarg=str,
+                  formatvarargs=lambda name: '*' + name,
+                  formatvarkw=lambda name: '**' + name,
+                  formatvalue=lambda value: '=' + repr(value),
+                  join=joinseq):
+    """Format an argument spec from the 4 values returned by getargspec.
+
+    The first four arguments are (args, varargs, varkw, defaults).  The
+    other four arguments are the corresponding optional formatting functions
+    that are called to turn names and values into strings.  The ninth
+    argument is an optional function to format the sequence of arguments.
+
+    """
+    specs = []
+    if defaults:
+        firstdefault = len(args) - len(defaults)
+    for i in range(len(args)):
+        spec = strseq(args[i], formatarg, join)
+        if defaults and i >= firstdefault:
+            spec = spec + formatvalue(defaults[i - firstdefault])
+        specs.append(spec)
+    if varargs is not None:
+        specs.append(formatvarargs(varargs))
+    if varkw is not None:
+        specs.append(formatvarkw(varkw))
+    return '(' + ', '.join(specs) + ')'
+
+def formatargvalues(args, varargs, varkw, locals,
+                    formatarg=str,
+                    formatvarargs=lambda name: '*' + name,
+                    formatvarkw=lambda name: '**' + name,
+                    formatvalue=lambda value: '=' + repr(value),
+                    join=joinseq):
+    """Format an argument spec from the 4 values returned by getargvalues.
+
+    The first four arguments are (args, varargs, varkw, locals).  The
+    next four arguments are the corresponding optional formatting functions
+    that are called to turn names and values into strings.  The ninth
+    argument is an optional function to format the sequence of arguments.
+
+    """
+    def convert(name, locals=locals,
+                formatarg=formatarg, formatvalue=formatvalue):
+        return formatarg(name) + formatvalue(locals[name])
+    specs = [strseq(arg, convert, join) for arg in args]
+
+    if varargs:
+        specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
+    if varkw:
+        specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
+    return '(' + ', '.join(specs) + ')'

numpy/_utils/_inspect.pyi

@@ -0,0 +1,70 @@
+import types
+from _typeshed import SupportsLenAndGetItem
+from collections.abc import Callable, Mapping
+from typing import Any, Final, TypeAlias, TypeVar, overload
+from typing_extensions import TypeIs
+
+__all__ = ["formatargspec", "getargspec"]
+
+###
+
+_T = TypeVar("_T")
+_RT = TypeVar("_RT")
+
+_StrSeq: TypeAlias = SupportsLenAndGetItem[str]
+_NestedSeq: TypeAlias = list[_T | _NestedSeq[_T]] | tuple[_T | _NestedSeq[_T], ...]
+
+_JoinFunc: TypeAlias = Callable[[list[_T]], _T]
+_FormatFunc: TypeAlias = Callable[[_T], str]
+
+###
+
+CO_OPTIMIZED: Final = 1
+CO_NEWLOCALS: Final = 2
+CO_VARARGS: Final = 4
+CO_VARKEYWORDS: Final = 8
+
+###
+
+def ismethod(object: object) -> TypeIs[types.MethodType]: ...
+def isfunction(object: object) -> TypeIs[types.FunctionType]: ...
+def iscode(object: object) -> TypeIs[types.CodeType]: ...
+
+###
+
+def getargs(co: types.CodeType) -> tuple[list[str], str | None, str | None]: ...
+def getargspec(func: types.MethodType | types.FunctionType) -> tuple[list[str], str | None, str | None, tuple[Any, ...]]: ...
+def getargvalues(frame: types.FrameType) -> tuple[list[str], str | None, str | None, dict[str, Any]]: ...
+
+#
+def joinseq(seq: _StrSeq) -> str: ...
+
+#
+@overload
+def strseq(object: _NestedSeq[str], convert: Callable[[Any], Any], join: _JoinFunc[str] = ...) -> str: ...
+@overload
+def strseq(object: _NestedSeq[_T], convert: Callable[[_T], _RT], join: _JoinFunc[_RT]) -> _RT: ...
+
+#
+def formatargspec(
+    args: _StrSeq,
+    varargs: str | None = None,
+    varkw: str | None = None,
+    defaults: SupportsLenAndGetItem[object] | None = None,
+    formatarg: _FormatFunc[str] = ...,  # str
+    formatvarargs: _FormatFunc[str] = ...,  # "*{}".format
+    formatvarkw: _FormatFunc[str] = ...,  # "**{}".format
+    formatvalue: _FormatFunc[object] = ...,  # "={!r}".format
+    join: _JoinFunc[str] = ...,  # joinseq
+) -> str: ...
+def formatargvalues(
+    args: _StrSeq,
+    varargs: str | None,
+    varkw: str | None,
+    locals: Mapping[str, object] | None,
+    formatarg: _FormatFunc[str] = ...,  # str
+    formatvarargs: _FormatFunc[str] = ...,  # "*{}".format
+    formatvarkw: _FormatFunc[str] = ...,  # "**{}".format
+    formatvalue: _FormatFunc[object] = ...,  # "={!r}".format
+    join: _JoinFunc[str] = ...,  # joinseq
+) -> str: ...