From 2afbf33032ac0c88ac18e581f37649d5af2c1a30 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 24 Nov 2025 12:18:50 -0500 Subject: [PATCH] gh-141004: Document stack effect C APIs (GH-141843) (cherry picked from commit e1f1df4082e2bc6cdb46be9984124c88a7b2ff0f) Co-authored-by: Peter Bierma Co-authored-by: Victor Stinner --- Doc/c-api/veryhigh.rst | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst index 3b07b5fbed5959..7eb9f0b54abd4e 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