From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Mon, 24 Nov 2025 17:24:41 +0000 (+0100)
Subject: [3.14] gh-141004: Document stack effect C APIs (GH-141843) (GH-141916)
X-Git-Tag: v3.14.1~49
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0f2f4c0e607246ba7e1f34e591dddfe033458cff;p=thirdparty%2FPython%2Fcpython.git

[3.14] gh-141004: Document stack effect C APIs (GH-141843) (GH-141916)

gh-141004: Document stack effect C APIs (GH-141843)
(cherry picked from commit e1f1df4082e2bc6cdb46be9984124c88a7b2ff0f)

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
---

diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 3b07b5fbed59..7eb9f0b54abd 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -396,3 +396,43 @@ Available start symbols
       * :pep:`484`
 
    .. versionadded:: 3.8
+
+
+Stack Effects
+^^^^^^^^^^^^^
+
+.. seealso::
+   :py:func:`dis.stack_effect`
+
+
+.. c:macro:: PY_INVALID_STACK_EFFECT
+
+   Sentinel value representing an invalid stack effect.
+
+   This is currently equivalent to ``INT_MAX``.
+
+   .. versionadded:: 3.8
+
+
+.. c:function:: int PyCompile_OpcodeStackEffect(int opcode, int oparg)
+
+   Compute the stack effect of *opcode* with argument *oparg*.
+
+   On success, this function returns the stack effect; on failure, this
+   returns :c:macro:`PY_INVALID_STACK_EFFECT`.
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)
+
+   Similar to :c:func:`PyCompile_OpcodeStackEffect`, but don't include the
+   stack effect of jumping if *jump* is zero.
+
+   If *jump* is ``0``, this will not include the stack effect of jumping, but
+   if *jump* is ``1`` or ``-1``, this will include it.
+
+   On success, this function returns the stack effect; on failure, this
+   returns :c:macro:`PY_INVALID_STACK_EFFECT`.
+
+   .. versionadded:: 3.8