Merge pull request numpy#20201 from BvB93/machar2

DEP: Deprecate `np.MachAr`

Author: charris

.gitignore

@@ -220,3 +220,4 @@ numpy/core/src/umath/loops_arithm_fp.dispatch.c
 numpy/core/src/umath/loops_arithmetic.dispatch.c
 numpy/core/src/umath/loops_trigonometric.dispatch.c
 numpy/core/src/umath/loops_exponent_log.dispatch.c
+numpy/core/src/umath/loops_umath_fp.dispatch.c

doc/release/upcoming_changes/20201.deprecation.rst

@@ -0,0 +1,5 @@
+The ``np.MachAr`` class has been deprecated
+-------------------------------------------
+The `~numpy.MachAr` class and `finfo.machar <numpy.finfo>` attribute have
+been deprecated. Users are encouraged to access the property if interest
+directly from the corresponding `~numpy.finfo` attribute.

numpy/__init__.py

@@ -188,12 +188,19 @@
         n: (getattr(_builtins, n), _msg.format(n=n, extended_msg=extended_msg))
         for n, extended_msg in _type_info
     })
+
     # Numpy 1.20.0, 2020-10-19
     __deprecated_attrs__["typeDict"] = (
         core.numerictypes.typeDict,
         "`np.typeDict` is a deprecated alias for `np.sctypeDict`."
     )
 
+    # NumPy 1.22, 2021-10-20
+    __deprecated_attrs__["MachAr"] = (
+        core._machar.MachAr,
+        "`np.MachAr` is deprecated (NumPy 1.22)."
+    )
+
     _msg = (
         "`np.{n}` is a deprecated alias for `np.compat.{n}`. "
         "To silence this warning, use `np.compat.{n}` by itself. "

numpy/__init__.pyi

@@ -14,7 +14,6 @@ if sys.version_info >= (3, 9):
 
 from numpy._pytesttester import PytestTester
 from numpy.core._internal import _ctypes
-from numpy.core.getlimits import MachArLike
 
 from numpy.typing import (
     # Arrays
@@ -665,17 +664,6 @@ test: PytestTester
 # their annotations are properly implemented
 #
 # Placeholders for classes
-# TODO: Remove `__getattr__` once the classes are stubbed out
-class MachAr:
-    def __init__(
-        self,
-        float_conv: Any = ...,
-        int_conv: Any = ...,
-        float_to_float: Any = ...,
-        float_to_str: Any = ...,
-        title: Any = ...,
-    ) -> None: ...
-    def __getattr__(self, key: str) -> Any: ...
 
 # Some of these are aliases; others are wrappers with an identical signature
 round = around
@@ -3395,14 +3383,6 @@ class finfo(Generic[_FloatType]):
     def smallest_normal(self) -> _FloatType: ...
     @property
     def tiny(self) -> _FloatType: ...
-
-    # NOTE: Not technically a property, but this is the only way we can
-    # access the precision of the underlying float
-    @property
-    def machar(self: finfo[floating[_NBit1]]) -> MachArLike[_NBit1]: ...
-    @machar.setter
-    def machar(self: finfo[floating[_NBit1]], value: MachArLike[_NBit1]) -> None: ...
-
     @overload
     def __new__(
         cls, dtype: inexact[_NBit1] | _DTypeLike[inexact[_NBit1]]
@@ -4335,3 +4315,6 @@ class chararray(ndarray[_ShapeType, _CharDType]):
     def isupper(self) -> ndarray[_ShapeType, dtype[bool_]]: ...
     def isnumeric(self) -> ndarray[_ShapeType, dtype[bool_]]: ...
     def isdecimal(self) -> ndarray[_ShapeType, dtype[bool_]]: ...
+
+# NOTE: Deprecated
+# class MachAr: ...

numpy/core/__init__.py

@@ -9,6 +9,7 @@
 from numpy.version import version as __version__
 
 import os
+import warnings
 
 # disables OpenBLAS affinity setting of the main thread that limits
 # python threads or processes to one core
@@ -80,8 +81,8 @@
 from .defchararray import chararray
 from . import function_base
 from .function_base import *
-from . import machar
-from .machar import *
+from . import _machar
+from ._machar import *
 from . import getlimits
 from .getlimits import *
 from . import shape_base
@@ -109,7 +110,6 @@
 __all__ += ['record', 'recarray', 'format_parser']
 __all__ += ['chararray']
 __all__ += function_base.__all__
-__all__ += machar.__all__
 __all__ += getlimits.__all__
 __all__ += shape_base.__all__
 __all__ += einsumfunc.__all__
@@ -151,6 +151,17 @@ def _DType_reduce(DType):
     return _DType_reconstruct, (scalar_type,)
 
 
+def __getattr__(name):
+    # Deprecated 2021-10-20, NumPy 1.22
+    if name == "machar":
+        warnings.warn(
+            "The `np.core.machar` module is deprecated (NumPy 1.22)",
+            DeprecationWarning, stacklevel=2,
+        )
+        return _machar
+    raise AttributeError(f"Module {__name__!r} has no attribute {name!r}")
+
+
 import copyreg
 
 copyreg.pickle(ufunc, _ufunc_reduce)

numpy/core/machar.py renamed to numpy/core/_machar.py

@@ -13,6 +13,7 @@
 
 # Need to speed this up...especially for longfloat
 
+# Deprecated 2021-10-20, NumPy 1.22
 @set_module('numpy')
 class MachAr:
     """

numpy/core/getlimits.py

@@ -5,7 +5,7 @@
 
 import warnings
 
-from .machar import MachAr
+from ._machar import MachAr
 from .overrides import set_module
 from . import numeric
 from . import numerictypes as ntypes
@@ -385,6 +385,8 @@ class finfo:
     machar : MachAr
         The object which calculated these parameters and holds more
         detailed information.
+
+        .. deprecated:: 1.22
     machep : int
         The exponent that yields `eps`.
     max : floating point number of the appropriate type
@@ -501,7 +503,7 @@ def _init(self, dtype):
         self.eps = machar.eps.flat[0]
         self.nexp = machar.iexp
         self.nmant = machar.it
-        self.machar = machar
+        self._machar = machar
         self._str_tiny = machar._str_xmin.strip()
         self._str_max = machar._str_xmax.strip()
         self._str_epsneg = machar._str_epsneg.strip()
@@ -551,11 +553,11 @@ def smallest_normal(self):
         """
         # This check is necessary because the value for smallest_normal is
         # platform dependent for longdouble types.
-        if isnan(self.machar.smallest_normal.flat[0]):
+        if isnan(self._machar.smallest_normal.flat[0]):
             warnings.warn(
                 'The value of smallest normal is undefined for double double',
                 UserWarning, stacklevel=2)
-        return self.machar.smallest_normal.flat[0]
+        return self._machar.smallest_normal.flat[0]
 
     @property
     def tiny(self):
@@ -574,6 +576,20 @@ def tiny(self):
         """
         return self.smallest_normal
 
+    @property
+    def machar(self):
+        """The object which calculated these parameters and holds more
+        detailed information.
+
+        .. deprecated:: 1.22
+        """
+        # Deprecated 2021-10-27, NumPy 1.22
+        warnings.warn(
+            "`finfo.machar` is deprecated (NumPy 1.22)",
+            DeprecationWarning, stacklevel=2,
+        )
+        return self._machar
+
 
 @set_module('numpy')
 class iinfo:

numpy/core/getlimits.pyi

@@ -1,58 +1,8 @@
-from typing import Any, Generic, List, Type, TypeVar
+from typing import List
 
 from numpy import (
     finfo as finfo,
     iinfo as iinfo,
-    floating,
-    signedinteger,
 )
 
-from numpy.typing import NBitBase, NDArray
-
-_NBit = TypeVar("_NBit", bound=NBitBase)
-
 __all__: List[str]
-
-class MachArLike(Generic[_NBit]):
-    def __init__(
-        self,
-        ftype: Type[floating[_NBit]],
-        *,
-        eps: floating[Any],
-        epsneg: floating[Any],
-        huge: floating[Any],
-        tiny: floating[Any],
-        ibeta: int,
-        smallest_subnormal: None | floating[Any] = ...,
-        # Expand `**kwargs` into keyword-only arguments
-        machep: int,
-        negep: int,
-        minexp: int,
-        maxexp: int,
-        it: int,
-        iexp: int,
-        irnd: int,
-        ngrd: int,
-    ) -> None: ...
-    @property
-    def smallest_subnormal(self) -> NDArray[floating[_NBit]]: ...
-    eps: NDArray[floating[_NBit]]
-    epsilon: NDArray[floating[_NBit]]
-    epsneg: NDArray[floating[_NBit]]
-    huge: NDArray[floating[_NBit]]
-    ibeta: signedinteger[_NBit]
-    iexp: int
-    irnd: int
-    it: int
-    machep: int
-    maxexp: int
-    minexp: int
-    negep: int
-    ngrd: int
-    precision: int
-    resolution: NDArray[floating[_NBit]]
-    smallest_normal: NDArray[floating[_NBit]]
-    tiny: NDArray[floating[_NBit]]
-    title: str
-    xmax: NDArray[floating[_NBit]]
-    xmin: NDArray[floating[_NBit]]

numpy/core/tests/test_deprecations.py

@@ -1215,3 +1215,18 @@ def test_deprecated(self, func):
     def test_not_deprecated(self, func):
         self.assert_not_deprecated(lambda: func(1))
         self.assert_not_deprecated(lambda: func([0, 1]))
+
+
+class TestMachAr(_DeprecationTestCase):
+    # Deprecated 2021-10-19, NumPy 1.22
+    warning_cls = DeprecationWarning
+
+    def test_deprecated(self):
+        self.assert_deprecated(lambda: np.MachAr)
+
+    def test_deprecated_module(self):
+        self.assert_deprecated(lambda: getattr(np.core, "machar"))
+
+    def test_deprecated_attr(self):
+        finfo = np.finfo(float)
+        self.assert_deprecated(lambda: getattr(finfo, "machar"))

numpy/core/tests/test_getlimits.py

@@ -46,7 +46,7 @@ def test_basic(self):
                        [np.float16, np.float32, np.float64, np.complex64,
                         np.complex128]))
         for dt1, dt2 in dts:
-            for attr in ('bits', 'eps', 'epsneg', 'iexp', 'machar', 'machep',
+            for attr in ('bits', 'eps', 'epsneg', 'iexp', 'machep',
                          'max', 'maxexp', 'min', 'minexp', 'negep', 'nexp',
                          'nmant', 'precision', 'resolution', 'tiny',
                          'smallest_normal', 'smallest_subnormal'):