[3.13] gh-124385: Document and soft-deprecate PyLong_AS_LONG (GH-124386) (#124719)

miss-islington · encukou · web-flow · commit e8980b17bb72 · 2024-09-29T17:59:54.000-07:00
gh-124385: Document and soft-deprecate PyLong_AS_LONG (GH-124386) (cherry picked from commit 425587a) Co-authored-by: Petr Viktorin <encukou@gmail.com>
diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
@@ -139,7 +139,6 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionadded:: 3.13
 
 
-.. XXX alias PyLong_AS_LONG (for now)
 .. c:function:: long PyLong_AsLong(PyObject *obj)
 
    .. index::
@@ -161,6 +160,16 @@ distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
    .. versionchanged:: 3.10
       This function will no longer use :meth:`~object.__int__`.
 
+   .. c:namespace:: NULL
+
+   .. c:function:: long PyLong_AS_LONG(PyObject *obj)
+
+      A :term:`soft deprecated` alias.
+      Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
+      it can fail with :exc:`OverflowError` or another exception.
+
+      .. deprecated:: 3.14
+         The function is soft deprecated.
 
 .. c:function:: int PyLong_AsInt(PyObject *obj)
 
