From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Mon, 17 Mar 2025 12:59:12 +0000 (+0200)
Subject: [3.12] gh-124385: Document and soft-deprecate PyLong_AS_LONG (GH-124386) (#130549)
X-Git-Tag: v3.12.10~88
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4c1d52934da853cdf42cf735689bae62d66c193e;p=thirdparty%2FPython%2Fcpython.git

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

(cherry picked from commit 425587a110eb214a097c634d4b6d944ac478923e)

Co-authored-by: Petr Viktorin <encukou@gmail.com>
---

diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst
index 972d69a51945..6e1cd1ece850 100644
--- a/Doc/c-api/long.rst
+++ b/Doc/c-api/long.rst
@@ -135,6 +135,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:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)