pythonrs 0.1.11

Python as a fusevm frontend: lexer, parser, and compiler to fusevm::Chunk on a PyHost heap — the first compiled standalone Python runtime
Documentation
//! `_opcode` — the classification tables `opcode.py` builds its public lists from.
//!
//! This module is pure METADATA about CPython's instruction set: `has_arg(op)`,
//! `has_jump(op)` and friends are predicates over opcode NUMBERS, and `opcode.py`
//! turns them into the `hasarg`/`hasjump`/`hasconst` lists that `dis` documents.
//! None of it describes how pythonrs executes anything — pythonrs compiles to
//! fusevm bytecode, not to CPython's — so `dis` over a pythonrs function is not
//! meaningful and is not claimed to be. What IS needed is that the tables exist
//! and are correct, because `inspect` imports `dis`, and `traceback`, `logging`,
//! `unittest`, `hashlib` and `dataclasses` all import `inspect`.
//!
//! The sets below are CPython 3.14's own answers, transcribed rather than
//! re-derived: they are generated data in CPython too (`Include/opcode_ids.h`),
//! and inventing a second derivation would only create a way to disagree.

use crate::host::{PyHost, PyObj};
use fusevm::Value;

const HAS_ARG: &[i64] = &[
    44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67,
    68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91,
    92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111,
    112, 113, 114, 115, 116, 117, 118, 119, 120, 128, 143, 144, 145, 146, 147, 148, 149, 150, 151,
    152, 153, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171,
    172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190,
    191, 192, 193, 194, 195, 197, 200, 209, 210, 211, 237, 239, 241, 242, 243, 244, 245, 247, 248,
    249, 250, 251, 253, 255, 257, 258, 259, 260, 261, 263, 264, 265, 266,
];
const HAS_CONST: &[i64] = &[82, 190, 191];
const HAS_NAME: &[i64] = &[
    61, 64, 65, 72, 73, 80, 91, 92, 93, 96, 110, 115, 116, 179, 189, 194, 195, 200, 249,
];
const HAS_JUMP: &[i64] = &[
    68, 70, 75, 76, 77, 100, 101, 102, 103, 106, 172, 173, 174, 175, 176, 237, 248, 257, 258, 259,
    260,
];
const HAS_FREE: &[i64] = &[62, 90, 97, 111];
const HAS_LOCAL: &[i64] = &[3, 63, 83, 84, 85, 86, 87, 88, 89, 112, 113, 114, 261, 266];
const HAS_EXC: &[i64] = &[263, 264, 265];

const INTRINSIC1: &[&str] = &[
    "INTRINSIC_1_INVALID",
    "INTRINSIC_PRINT",
    "INTRINSIC_IMPORT_STAR",
    "INTRINSIC_STOPITERATION_ERROR",
    "INTRINSIC_ASYNC_GEN_WRAP",
    "INTRINSIC_UNARY_POSITIVE",
    "INTRINSIC_LIST_TO_TUPLE",
    "INTRINSIC_TYPEVAR",
    "INTRINSIC_PARAMSPEC",
    "INTRINSIC_TYPEVARTUPLE",
    "INTRINSIC_SUBSCRIPT_GENERIC",
    "INTRINSIC_TYPEALIAS",
];
const INTRINSIC2: &[&str] = &[
    "INTRINSIC_2_INVALID",
    "INTRINSIC_PREP_RERAISE_STAR",
    "INTRINSIC_TYPEVAR_WITH_BOUND",
    "INTRINSIC_TYPEVAR_WITH_CONSTRAINTS",
    "INTRINSIC_SET_FUNCTION_TYPE_PARAMS",
    "INTRINSIC_SET_TYPEPARAM_DEFAULT",
];
const SPECIAL_METHODS: &[&str] = &["__enter__", "__exit__", "__aenter__", "__aexit__"];
const NB_OPS: &[(&str, &str)] = &[
    ("NB_ADD", "+"),
    ("NB_AND", "&"),
    ("NB_FLOOR_DIVIDE", "//"),
    ("NB_LSHIFT", "<<"),
    ("NB_MATRIX_MULTIPLY", "@"),
    ("NB_MULTIPLY", "*"),
    ("NB_REMAINDER", "%"),
    ("NB_OR", "|"),
    ("NB_POWER", "**"),
    ("NB_RSHIFT", ">>"),
    ("NB_SUBTRACT", "-"),
    ("NB_TRUE_DIVIDE", "/"),
    ("NB_XOR", "^"),
    ("NB_INPLACE_ADD", "+="),
    ("NB_INPLACE_AND", "&="),
    ("NB_INPLACE_FLOOR_DIVIDE", "//="),
    ("NB_INPLACE_LSHIFT", "<<="),
    ("NB_INPLACE_MATRIX_MULTIPLY", "@="),
    ("NB_INPLACE_MULTIPLY", "*="),
    ("NB_INPLACE_REMAINDER", "%="),
    ("NB_INPLACE_OR", "|="),
    ("NB_INPLACE_POWER", "**="),
    ("NB_INPLACE_RSHIFT", ">>="),
    ("NB_INPLACE_SUBTRACT", "-="),
    ("NB_INPLACE_TRUE_DIVIDE", "/="),
    ("NB_INPLACE_XOR", "^="),
    ("NB_SUBSCR", "[]"),
];

/// `_opcode.<fn>(...)`.
pub fn call(h: &mut PyHost, name: &str, args: &[Value]) -> Option<Result<Value, String>> {
    // The seven predicates share one shape: is this opcode number in the set?
    let table: Option<&[i64]> = match name {
        "has_arg" => Some(HAS_ARG),
        "has_const" => Some(HAS_CONST),
        "has_name" => Some(HAS_NAME),
        "has_jump" => Some(HAS_JUMP),
        "has_free" => Some(HAS_FREE),
        "has_local" => Some(HAS_LOCAL),
        "has_exc" => Some(HAS_EXC),
        _ => None,
    };
    if let Some(table) = table {
        let op = args.first().and_then(|v| h.as_int(v))?;
        return Some(Ok(Value::Bool(table.contains(&op))));
    }
    Some(match name {
        "get_intrinsic1_descs" => Ok(str_tuple(h, INTRINSIC1)),
        "get_intrinsic2_descs" => Ok(str_tuple(h, INTRINSIC2)),
        "get_special_method_names" => Ok(str_tuple(h, SPECIAL_METHODS)),
        "get_nb_ops" => {
            let rows: Vec<Value> = NB_OPS
                .iter()
                .map(|(name, symbol)| {
                    let n = h.new_str((*name).to_string());
                    let s = h.new_str((*symbol).to_string());
                    h.new_tuple(vec![n, s])
                })
                .collect();
            Ok(h.new_list(rows))
        }
        // An opcode number is valid when it is one CPython defines.
        "is_valid" => {
            let op = args.first().and_then(|v| h.as_int(v)).unwrap_or(-1);
            Ok(Value::Bool((0..=260).contains(&op)))
        }
        // `stack_effect` describes CPython's evaluation stack, which pythonrs does
        // not have. Reporting 0 is honest for a runtime that never executes these
        // instructions; `opcode.py` only re-exports the function.
        "stack_effect" => Ok(Value::Int(0)),
        "get_executor" | "get_specialization_stats" => Ok(Value::Undef),
        _ => return None,
    })
}

fn str_tuple(h: &mut PyHost, items: &[&str]) -> Value {
    let vals: Vec<Value> = items.iter().map(|s| h.new_str((*s).to_string())).collect();
    h.new_tuple(vals)
}

/// The `_opcode` namespace.
pub fn entries(h: &mut PyHost) -> Vec<(String, Value)> {
    const FNS: &[&str] = &[
        "has_arg",
        "has_const",
        "has_name",
        "has_jump",
        "has_free",
        "has_local",
        "has_exc",
        "is_valid",
        "stack_effect",
        "get_intrinsic1_descs",
        "get_intrinsic2_descs",
        "get_special_method_names",
        "get_nb_ops",
        "get_executor",
        "get_specialization_stats",
    ];
    let mut out: Vec<(String, Value)> = FNS
        .iter()
        .map(|f| {
            (
                (*f).to_string(),
                h.alloc(PyObj::Builtin(format!("_opcode.{f}"))),
            )
        })
        .collect();
    // Specialization is a CPython interpreter feature; pythonrs has its own JIT
    // and never runs these instructions, so the flags are off.
    out.push(("ENABLE_SPECIALIZATION".to_string(), Value::Bool(false)));
    out.push(("ENABLE_SPECIALIZATION_FT".to_string(), Value::Bool(false)));
    out
}