Add PyLong_IsPositive/Negative/Zero() functions (#119)

Co-authored-by: Victor Stinner <[email protected]>

docs/api.rst

@@ -29,6 +29,18 @@ Latest version of the header file:
 Python 3.14
 -----------
 
+.. c:function:: int PyLong_IsPositive(PyObject *obj)
+
+   See `PyLong_IsPositive() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLong_IsPositive>`__.
+
+.. c:function:: int PyLong_IsNegative(PyObject *obj)
+
+   See `PyLong_IsNegative() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLong_IsNegative>`__.
+
+.. c:function:: int PyLong_IsZero(PyObject *obj)
+
+   See `PyLong_IsZero() documentation  <https://docs.python.org/dev/c-api/long.html#c.PyLong_IsZero>`__.
+
 .. c:function:: int PyLong_GetSign(PyObject *obj, int *sign)
 
    See `PyLong_GetSign() documentation <https://docs.python.org/dev/c-api/long.html#c.PyLong_GetSign>`__.

docs/changelog.rst

@@ -1,6 +1,12 @@
 Changelog
 =========
 
+* 2024-11-12: Add functions:
+
+  * ``PyLong_IsPositive()``
+  * ``PyLong_IsNegative()``
+  * ``PyLong_IsZero()``
+
 * 2024-10-09: Add functions:
 
   * ``PyBytes_Join()``

pythoncapi_compat.h

@@ -1520,6 +1520,36 @@ static inline int PyLong_GetSign(PyObject *obj, int *sign)
 }
 #endif
 
+// gh-126061 added PyLong_IsPositive/Negative/Zero() to Python in 3.14.0a2
+#if PY_VERSION_HEX < 0x030E00A2
+static inline int PyLong_IsPositive(PyObject *obj)
+{
+    if (!PyLong_Check(obj)) {
+        PyErr_Format(PyExc_TypeError, "expected int, got %s", Py_TYPE(obj)->tp_name);
+        return -1;
+    }
+    return _PyLong_Sign(obj) == 1;
+}
+
+static inline int PyLong_IsNegative(PyObject *obj)
+{
+    if (!PyLong_Check(obj)) {
+        PyErr_Format(PyExc_TypeError, "expected int, got %s", Py_TYPE(obj)->tp_name);
+        return -1;
+    }
+    return _PyLong_Sign(obj) == -1;
+}
+
+static inline int PyLong_IsZero(PyObject *obj)
+{
+    if (!PyLong_Check(obj)) {
+        PyErr_Format(PyExc_TypeError, "expected int, got %s", Py_TYPE(obj)->tp_name);
+        return -1;
+    }
+    return _PyLong_Sign(obj) == 0;
+}
+#endif
+
 
 // gh-124502 added PyUnicode_Equal() to Python 3.14.0a0
 #if PY_VERSION_HEX < 0x030E00A0

tests/test_pythoncapi_compat_cext.c

@@ -1421,6 +1421,11 @@ test_long_api(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
     assert(PyLong_GetSign(obj, &sign) == 0);
     assert(sign == 1);
 
+    // test PyLong_IsPositive(), PyLong_IsNegative() and PyLong_IsZero()
+    assert(PyLong_IsPositive(obj) == 1);
+    assert(PyLong_IsNegative(obj) == 0);
+    assert(PyLong_IsZero(obj) == 0);
+
     Py_RETURN_NONE;
 }