gh-105481: expose opcode metadata via the _opcode module (#106688)

2 files changed, 407 insertions, 1 deletions

diff --git a/Modules/_opcode.c b/Modules/_opcode.c
index 3c0fce4..b3b9873 100644
--- a/Modules/_opcode.c
+++ b/Modules/_opcode.c
@@ -1,4 +1,5 @@
 #include "Python.h"
+#include "compile.h"
 #include "opcode.h"
 #include "internal/pycore_code.h"
 
@@ -61,6 +62,91 @@ _opcode_stack_effect_impl(PyObject *module, int opcode, PyObject *oparg,
 
 /*[clinic input]
 
+_opcode.is_valid -> bool
+
+  opcode: int
+
+Return True if opcode is valid, False otherwise.
+[clinic start generated code]*/
+
+static int
+_opcode_is_valid_impl(PyObject *module, int opcode)
+/*[clinic end generated code: output=b0d918ea1d073f65 input=fe23e0aa194ddae0]*/
+{
+    return PyUnstable_OpcodeIsValid(opcode);
+}
+
+/*[clinic input]
+
+_opcode.has_arg -> bool
+
+  opcode: int
+
+Return True if the opcode uses its oparg, False otherwise.
+[clinic start generated code]*/
+
+static int
+_opcode_has_arg_impl(PyObject *module, int opcode)
+/*[clinic end generated code: output=7a062d3b2dcc0815 input=93d878ba6361db5f]*/
+{
+    return PyUnstable_OpcodeIsValid(opcode) &&
+           PyUnstable_OpcodeHasArg(opcode);
+}
+
+/*[clinic input]
+
+_opcode.has_const -> bool
+
+  opcode: int
+
+Return True if the opcode accesses a constant, False otherwise.
+[clinic start generated code]*/
+
+static int
+_opcode_has_const_impl(PyObject *module, int opcode)
+/*[clinic end generated code: output=c646d5027c634120 input=a6999e4cf13f9410]*/
+{
+    return PyUnstable_OpcodeIsValid(opcode) &&
+           PyUnstable_OpcodeHasConst(opcode);
+}
+
+/*[clinic input]
+
+_opcode.has_name -> bool
+
+  opcode: int
+
+Return True if the opcode accesses an attribute by name, False otherwise.
+[clinic start generated code]*/
+
+static int
+_opcode_has_name_impl(PyObject *module, int opcode)
+/*[clinic end generated code: output=b49a83555c2fa517 input=448aa5e4bcc947ba]*/
+{
+    return PyUnstable_OpcodeIsValid(opcode) &&
+           PyUnstable_OpcodeHasName(opcode);
+}
+
+/*[clinic input]
+
+_opcode.has_jump -> bool
+
+  opcode: int
+
+Return True if the opcode has a jump target, False otherwise.
+[clinic start generated code]*/
+
+static int
+_opcode_has_jump_impl(PyObject *module, int opcode)
+/*[clinic end generated code: output=e9c583c669f1c46a input=35f711274357a0c3]*/
+{
+    return PyUnstable_OpcodeIsValid(opcode) &&
+           PyUnstable_OpcodeHasJump(opcode);
+
+}
+
+/*[clinic input]
+
 _opcode.get_specialization_stats
 
 Return the specialization stats
@@ -80,6 +166,11 @@ _opcode_get_specialization_stats_impl(PyObject *module)
 static PyMethodDef
 opcode_functions[] =  {
     _OPCODE_STACK_EFFECT_METHODDEF
+    _OPCODE_IS_VALID_METHODDEF
+    _OPCODE_HAS_ARG_METHODDEF
+    _OPCODE_HAS_CONST_METHODDEF
+    _OPCODE_HAS_NAME_METHODDEF
+    _OPCODE_HAS_JUMP_METHODDEF
     _OPCODE_GET_SPECIALIZATION_STATS_METHODDEF
     {NULL, NULL, 0, NULL}
 };
diff --git a/Modules/clinic/_opcode.c.h b/Modules/clinic/_opcode.c.h
index 3bd3ba0..3eb050e 100644
--- a/Modules/clinic/_opcode.c.h
+++ b/Modules/clinic/_opcode.c.h
@@ -86,6 +86,321 @@ exit:
     return return_value;
 }
 
+PyDoc_STRVAR(_opcode_is_valid__doc__,
+"is_valid($module, /, opcode)\n"
+"--\n"
+"\n"
+"Return True if opcode is valid, False otherwise.");
+
+#define _OPCODE_IS_VALID_METHODDEF    \
+    {"is_valid", _PyCFunction_CAST(_opcode_is_valid), METH_FASTCALL|METH_KEYWORDS, _opcode_is_valid__doc__},
+
+static int
+_opcode_is_valid_impl(PyObject *module, int opcode);
+
+static PyObject *
+_opcode_is_valid(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
+{
+    PyObject *return_value = NULL;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 1
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_item = { &_Py_ID(opcode), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"opcode", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "is_valid",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[1];
+    int opcode;
+    int _return_value;
+
+    args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 1, 1, 0, argsbuf);
+    if (!args) {
+        goto exit;
+    }
+    opcode = _PyLong_AsInt(args[0]);
+    if (opcode == -1 && PyErr_Occurred()) {
+        goto exit;
+    }
+    _return_value = _opcode_is_valid_impl(module, opcode);
+    if ((_return_value == -1) && PyErr_Occurred()) {
+        goto exit;
+    }
+    return_value = PyBool_FromLong((long)_return_value);
+
+exit:
+    return return_value;
+}
+
+PyDoc_STRVAR(_opcode_has_arg__doc__,
+"has_arg($module, /, opcode)\n"
+"--\n"
+"\n"
+"Return True if the opcode uses its oparg, False otherwise.");
+
+#define _OPCODE_HAS_ARG_METHODDEF    \
+    {"has_arg", _PyCFunction_CAST(_opcode_has_arg), METH_FASTCALL|METH_KEYWORDS, _opcode_has_arg__doc__},
+
+static int
+_opcode_has_arg_impl(PyObject *module, int opcode);
+
+static PyObject *
+_opcode_has_arg(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
+{
+    PyObject *return_value = NULL;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 1
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_item = { &_Py_ID(opcode), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"opcode", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "has_arg",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[1];
+    int opcode;
+    int _return_value;
+
+    args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 1, 1, 0, argsbuf);
+    if (!args) {
+        goto exit;
+    }
+    opcode = _PyLong_AsInt(args[0]);
+    if (opcode == -1 && PyErr_Occurred()) {
+        goto exit;
+    }
+    _return_value = _opcode_has_arg_impl(module, opcode);
+    if ((_return_value == -1) && PyErr_Occurred()) {
+        goto exit;
+    }
+    return_value = PyBool_FromLong((long)_return_value);
+
+exit:
+    return return_value;
+}
+
+PyDoc_STRVAR(_opcode_has_const__doc__,
+"has_const($module, /, opcode)\n"
+"--\n"
+"\n"
+"Return True if the opcode accesses a constant, False otherwise.");
+
+#define _OPCODE_HAS_CONST_METHODDEF    \
+    {"has_const", _PyCFunction_CAST(_opcode_has_const), METH_FASTCALL|METH_KEYWORDS, _opcode_has_const__doc__},
+
+static int
+_opcode_has_const_impl(PyObject *module, int opcode);
+
+static PyObject *
+_opcode_has_const(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
+{
+    PyObject *return_value = NULL;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 1
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_item = { &_Py_ID(opcode), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"opcode", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "has_const",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[1];
+    int opcode;
+    int _return_value;
+
+    args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 1, 1, 0, argsbuf);
+    if (!args) {
+        goto exit;
+    }
+    opcode = _PyLong_AsInt(args[0]);
+    if (opcode == -1 && PyErr_Occurred()) {
+        goto exit;
+    }
+    _return_value = _opcode_has_const_impl(module, opcode);
+    if ((_return_value == -1) && PyErr_Occurred()) {
+        goto exit;
+    }
+    return_value = PyBool_FromLong((long)_return_value);
+
+exit:
+    return return_value;
+}
+
+PyDoc_STRVAR(_opcode_has_name__doc__,
+"has_name($module, /, opcode)\n"
+"--\n"
+"\n"
+"Return True if the opcode accesses an attribute by name, False otherwise.");
+
+#define _OPCODE_HAS_NAME_METHODDEF    \
+    {"has_name", _PyCFunction_CAST(_opcode_has_name), METH_FASTCALL|METH_KEYWORDS, _opcode_has_name__doc__},
+
+static int
+_opcode_has_name_impl(PyObject *module, int opcode);
+
+static PyObject *
+_opcode_has_name(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
+{
+    PyObject *return_value = NULL;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 1
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_item = { &_Py_ID(opcode), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"opcode", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "has_name",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[1];
+    int opcode;
+    int _return_value;
+
+    args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 1, 1, 0, argsbuf);
+    if (!args) {
+        goto exit;
+    }
+    opcode = _PyLong_AsInt(args[0]);
+    if (opcode == -1 && PyErr_Occurred()) {
+        goto exit;
+    }
+    _return_value = _opcode_has_name_impl(module, opcode);
+    if ((_return_value == -1) && PyErr_Occurred()) {
+        goto exit;
+    }
+    return_value = PyBool_FromLong((long)_return_value);
+
+exit:
+    return return_value;
+}
+
+PyDoc_STRVAR(_opcode_has_jump__doc__,
+"has_jump($module, /, opcode)\n"
+"--\n"
+"\n"
+"Return True if the opcode has a jump target, False otherwise.");
+
+#define _OPCODE_HAS_JUMP_METHODDEF    \
+    {"has_jump", _PyCFunction_CAST(_opcode_has_jump), METH_FASTCALL|METH_KEYWORDS, _opcode_has_jump__doc__},
+
+static int
+_opcode_has_jump_impl(PyObject *module, int opcode);
+
+static PyObject *
+_opcode_has_jump(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
+{
+    PyObject *return_value = NULL;
+    #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
+
+    #define NUM_KEYWORDS 1
+    static struct {
+        PyGC_Head _this_is_not_used;
+        PyObject_VAR_HEAD
+        PyObject *ob_item[NUM_KEYWORDS];
+    } _kwtuple = {
+        .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
+        .ob_item = { &_Py_ID(opcode), },
+    };
+    #undef NUM_KEYWORDS
+    #define KWTUPLE (&_kwtuple.ob_base.ob_base)
+
+    #else  // !Py_BUILD_CORE
+    #  define KWTUPLE NULL
+    #endif  // !Py_BUILD_CORE
+
+    static const char * const _keywords[] = {"opcode", NULL};
+    static _PyArg_Parser _parser = {
+        .keywords = _keywords,
+        .fname = "has_jump",
+        .kwtuple = KWTUPLE,
+    };
+    #undef KWTUPLE
+    PyObject *argsbuf[1];
+    int opcode;
+    int _return_value;
+
+    args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 1, 1, 0, argsbuf);
+    if (!args) {
+        goto exit;
+    }
+    opcode = _PyLong_AsInt(args[0]);
+    if (opcode == -1 && PyErr_Occurred()) {
+        goto exit;
+    }
+    _return_value = _opcode_has_jump_impl(module, opcode);
+    if ((_return_value == -1) && PyErr_Occurred()) {
+        goto exit;
+    }
+    return_value = PyBool_FromLong((long)_return_value);
+
+exit:
+    return return_value;
+}
+
 PyDoc_STRVAR(_opcode_get_specialization_stats__doc__,
 "get_specialization_stats($module, /)\n"
 "--\n"
@@ -103,4 +418,4 @@ _opcode_get_specialization_stats(PyObject *module, PyObject *Py_UNUSED(ignored))
 {
     return _opcode_get_specialization_stats_impl(module);
 }
-/*[clinic end generated code: output=21e3d53a659c651a input=a9049054013a1b77]*/
+/*[clinic end generated code: output=ae2b2ef56d582180 input=a9049054013a1b77]*/