numpy · ganesh-k13 · May 13, 2025 · May 13, 2025 · May 14, 2025 · May 14, 2025
diff --git a/doc/release/upcoming_changes/28949.new_function.rst b/doc/release/upcoming_changes/28949.new_function.rst
@@ -0,0 +1,22 @@
+Add ``__trunc__`` method to NumPy scalar types
+==============================================
+
+NumPy scalar floating and integer types now implement the ``__trunc__`` special method, matching Python’s built-in numeric types. This enables direct use of :func:`math.trunc` and the ``__trunc__`` dunder method on NumPy scalars:
+
+Examples
+--------
+
+.. code-block:: python
+
+    >>> import numpy as np
+    >>> import math
+    >>> math.trunc(np.float16(np.pi))
+    3
+    >>> np.float16(-np.pi).__trunc__()
+    -3
+    >>> np.int32(42).__trunc__()
+    42
+
+Attempting to truncate infinite or NaN values for floating point types will now raise the same errors as Python floats.
+
+.. versionadded:: 2.3
diff --git a/numpy/__init__.pyi b/numpy/__init__.pyi
@@ -1121,6 +1121,8 @@ class _RoundMixin:
     def __round__(self, /, ndigits: None = None) -> int: ...
     @overload
     def __round__(self, /, ndigits: SupportsIndex) -> Self: ...
+    @overload
+    def __trunc__(self, /) -> int: ...
 
 @type_check_only
 class _IntegralMixin(_RealMixin):

diff --git a/numpy/_core/_add_newdocs_scalars.py b/numpy/_core/_add_newdocs_scalars.py
@@ -369,6 +369,24 @@ def add_newdoc_for_scalar_type(obj, fixed_aliases, doc):
         False
         """))
 
+    add_newdoc('numpy._core.numerictypes', float_name, ('__trunc__',
+        f"""
+        {float_name}.__trunc__() -> int
+
+        Return the floating point number with the fractional part removed,
+        leaving the integer part.
+
+        .. versionadded:: 2.3
+
+        Examples
+        --------
+        >>> np.{float_name}(np.pi).__trunc__()
+        3
+        >>> import math
+        >>> math.trunc(np.{float_name}(-np.pi))
+        -3
+        """))
+
 for int_name in ('int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32',
         'int64', 'uint64', 'int64', 'uint64', 'int64', 'uint64'):
     # Add negative examples for signed cases by checking typecode
@@ -387,3 +405,17 @@ def add_newdoc_for_scalar_type(obj, fixed_aliases, doc):
         >>> np.{int_name}(-127).bit_count()
         7
         """ if dtype(int_name).char.islower() else "")))
+
+    add_newdoc('numpy._core.numerictypes', int_name, ('__trunc__',
+        f"""
+        {int_name}.__trunc__() -> int
+
+        Truncating an Integral returns itself.
+
+        .. versionadded:: 2.3
+
+        Examples
+        --------
+        >>> np.{int_name}(127).__trunc__()
+        127
+        """))
diff --git a/numpy/_core/src/multiarray/scalartypes.c.src b/numpy/_core/src/multiarray/scalartypes.c.src
@@ -2886,6 +2886,9 @@ static PyMethodDef @name@type_methods[] = {
     {"is_integer",
         (PyCFunction)@name@_is_integer,
         METH_NOARGS, NULL},
+    {"__trunc__",
+        (PyCFunction)gentype_int,
+        METH_NOARGS, NULL},
     /* for typing */
     {"__class_getitem__",
         (PyCFunction)numbertype_class_getitem,
@@ -2918,6 +2921,9 @@ static PyMethodDef @name@type_methods[] = {
     {"bit_count",
         (PyCFunction)npy_@name@_bit_count,
         METH_NOARGS, NULL},
+    {"__trunc__",
+        (PyCFunction)gentype_int,
+        METH_NOARGS, NULL},
     {NULL, NULL, 0, NULL} /* sentinel */
 };
 /**end repeat**/

diff --git a/numpy/_core/tests/test_scalar_methods.py b/numpy/_core/tests/test_scalar_methods.py
@@ -2,6 +2,7 @@
 Test the scalar constructors, which also do type-coercion
 """
 import fractions
+import math
 import platform
 import types
 from typing import Any
@@ -133,6 +134,36 @@ def test_false(self, code: str) -> None:
                 continue
             assert not value.is_integer()
 
+class TestTruncate:
+    @pytest.mark.parametrize("code", np.typecodes["Float"])
+    @pytest.mark.parametrize("value", [0, -0, np.pi, -np.pi])
+    def test_basic_float(self, code, value):
+        dtype_value = np.dtype(code).type(value)
+        assert math.trunc(value) == math.trunc(dtype_value)
+
+    @pytest.mark.parametrize("code", np.typecodes["AllInteger"])
+    @pytest.mark.parametrize("limit", ["min", "max"])
+    def test_edgcases_integer(self, code, limit):
+        dtype = np.dtype(code).type
+        value = getattr(np.iinfo(dtype), limit)
+        assert math.trunc(dtype(value)) == math.trunc(int(value))
+
+    @pytest.mark.parametrize("code", np.typecodes["Float"])
+    @pytest.mark.parametrize("limit", ["min", "max"])
+    def test_edgcases_float(self, code, limit):
+        dtype = np.dtype(code).type
+        value = getattr(np.finfo(dtype), limit)
+        assert math.trunc(dtype(value)) == int(value)
+
+    @pytest.mark.parametrize("str_value, exception_class, match", [
+        ("inf", OverflowError, "cannot convert (float|longdouble) infinity to integer"),
+        ("-inf", OverflowError, "cannot convert (float|longdouble) infinity to integer"),
+        ("nan", ValueError, "cannot convert (float|longdouble) NaN to integer"),
+    ])
+    @pytest.mark.parametrize("code", np.typecodes["Float"])
+    def test_special_float(self, str_value, exception_class, match, code):
+        with pytest.raises(exception_class, match=match):
+            math.trunc(np.dtype(code).type(str_value))
 
 class TestClassGetItem:
     @pytest.mark.parametrize("cls", [

diff --git a/numpy/typing/tests/data/fail/scalars.pyi b/numpy/typing/tests/data/fail/scalars.pyi
@@ -83,5 +83,4 @@ c8.__getnewargs__()  # type: ignore[attr-defined]
 f2.__getnewargs__()  # type: ignore[attr-defined]
 f2.hex()  # type: ignore[attr-defined]
 np.float16.fromhex("0x0.0p+0")  # type: ignore[attr-defined]
-f2.__trunc__()  # type: ignore[attr-defined]
 f2.__getformat__("float")  # type: ignore[attr-defined]