gh-126061: Add PyLong_IsPositive/Zero/Negative() functions

Doc/c-api/long.rst

@@ -571,6 +571,42 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.14
 
 
+.. c:function:: int PyLong_IsPositive(PyObject *obj)
+
+   Check if the integer object *obj* is positive.
+
+   On success, return 1 if *obj* is positive, and 0 otherwise.
+
+   On failure, return -1 with an exception set.  This function always succeeds
+   if *obj* is a :c:type:`PyLongObject` or its subtype.
+
+   .. versionadded:: 3.14
+
+
+.. c:function:: int PyLong_IsNegative(PyObject *obj)
+
+   Check if the integer object *obj* is negative.
+
+   On success, return 1 if *obj* is negative, and 0 otherwise.
+
+   On failure, return -1 with an exception set.  This function always succeeds
+   if *obj* is a :c:type:`PyLongObject` or its subtype.
+
+   .. versionadded:: 3.14
+
+
+.. c:function:: int PyLong_IsZero(PyObject *obj)
+
+   Check if the integer object *obj* is zero.
+
+   On success, return 1 if *obj* is zero, and 0 if it is non-zero.
+
+   On failure, return -1 with an exception set.  This function always succeeds
+   if *obj* is a :c:type:`PyLongObject` or its subtype.
+
+   .. versionadded:: 3.14
+
+
 .. c:function:: PyObject* PyLong_GetInfo(void)
 
    On success, return a read only :term:`named tuple`, that holds

Doc/whatsnew/3.14.rst

@@ -479,6 +479,11 @@ New Features
   an interned string and deallocate it during module shutdown.
   (Contribued by Eddie Elizondo in :gh:`113601`.)
 
+* Add :c:func:`PyLong_IsPositive`, :c:func:`PyLong_IsNegative`
+  and :c:func:`PyLong_IsZero` for checking if :c:type:`PyLongObject`
+  is positive, negative, or zero.
+  (Contribued by James Roy in :gh:`126061`.)
+
 * Add new functions to convert C ``<stdint.h>`` numbers from/to Python
   :class:`int`:
 

Include/cpython/longobject.h

@@ -58,6 +58,24 @@ PyAPI_FUNC(PyObject*) PyLong_FromUnsignedNativeBytes(const void* buffer,
 PyAPI_FUNC(int) PyUnstable_Long_IsCompact(const PyLongObject* op);
 PyAPI_FUNC(Py_ssize_t) PyUnstable_Long_CompactValue(const PyLongObject* op);
 
+/* PyLong_IsPositive.  Check if the integer object is positive.
+
+   - On success, return 1 if *obj is positive, and 0 otherwise.
+   - On failure, set an exception, and return -1. */
+PyAPI_FUNC(int) PyLong_IsPositive(PyObject *obj);
+
+/* PyLong_IsNegative.  Check if the integer object is negative.
+
+   - On success, return 1 if *obj is negative, and 0 otherwise.
+   - On failure, set an exception, and return -1. */
+PyAPI_FUNC(int) PyLong_IsNegative(PyObject *obj);
+
+/* PyLong_IsZero.  Check if the integer object is zero.
+
+   - On success, return 1 if *obj is zero, and 0 if it is non-zero.
+   - On failure, set an exception, and return -1. */
+PyAPI_FUNC(int) PyLong_IsZero(PyObject *obj);
+
 /* PyLong_GetSign.  Get the sign of an integer object:
    0, -1 or +1 for zero, negative or positive integer, respectively.
 

Misc/NEWS.d/next/C_API/2024-10-28-15-56-03.gh-issue-126061.Py51_1.rst

@@ -0,0 +1,3 @@
+Add :c:func:`PyLong_IsPositive`, :c:func:`PyLong_IsNegative`
+and :c:func:`PyLong_IsZero` for checking if :c:type:`PyLongObject`
+is positive, negative, or zero.

Objects/longobject.c

@@ -769,6 +769,36 @@ PyLong_AsUnsignedLongMask(PyObject *op)
     return val;
 }
 
+int
+PyLong_IsPositive(PyObject *obj)
+{
+    if (!PyLong_Check(obj)) {
+        PyErr_Format(PyExc_TypeError, "expect int, got %T", obj);
+        return -1;
+    }
+    return _PyLong_IsPositive((PyLongObject *)obj);
+}
+
+int
+PyLong_IsNegative(PyObject *obj)
+{
+    if (!PyLong_Check(obj)) {
+        PyErr_Format(PyExc_TypeError, "expect int, got %T", obj);
+        return -1;
+    }
+    return _PyLong_IsNegative((PyLongObject *)obj);
+}
+
+int
+PyLong_IsZero(PyObject *obj)
+{
+    if (!PyLong_Check(obj)) {
+        PyErr_Format(PyExc_TypeError, "expect int, got %T", obj);
+        return -1;
+    }
+    return _PyLong_IsZero((PyLongObject *)obj);
+}
+
 int
 _PyLong_Sign(PyObject *vv)
 {