Rename the enums

youknowone · Jan 14, 2026 · Jan 11, 2026 · Jan 11, 2026 · Jan 11, 2026 · Jan 12, 2026
commit 1f8722a9ad18bde3dc5b0b54e426b697ce5c5b35
diff --git a/crates/codegen/src/compile.rs b/crates/codegen/src/compile.rs
diff --git a/crates/codegen/src/ir.rs b/crates/codegen/src/ir.rs
@@ -5,9 +5,9 @@ use crate::{IndexMap, IndexSet, error::InternalError};
 use rustpython_compiler_core::{
     OneIndexed, SourceLocation,
     bytecode::{
-        Arg, CodeFlags, CodeObject, CodeUnit, CodeUnits, ConstantData, ExceptionTableEntry,
-        InstrDisplayContext, Instruction, InstructionMetadata, Label, OpArg, PseudoInstruction,
-        PyCodeLocationInfoKind, RealInstruction, encode_exception_table, encode_load_attr_arg,
+        AnyInstruction, Arg, CodeFlags, CodeObject, CodeUnit, CodeUnits, ConstantData,
+        ExceptionTableEntry, InstrDisplayContext, Instruction, InstructionMetadata, Label, OpArg,
+        PseudoInstruction, PyCodeLocationInfoKind, encode_exception_table, encode_load_attr_arg,
         encode_load_super_attr_arg,
     },
     varint::{write_signed_varint, write_varint},
@@ -87,7 +87,7 @@ impl ops::IndexMut<BlockIdx> for Vec<Block> {
 
 #[derive(Debug, Clone)]
 pub struct InstructionInfo {
-    pub instr: Instruction,
+    pub instr: AnyInstruction,
     pub arg: OpArg,
     pub target: BlockIdx,
     pub location: SourceLocation,
@@ -198,24 +198,23 @@ impl CodeInfo {
         {
             for info in &mut block.instructions {
                 // Special case for:
-                // - `RealInstruction::LoadAttr`
-                // - `RealInstruction::LoadSuperAttr`
+                // - `Instruction::LoadAttr`
+                // - `Instruction::LoadSuperAttr`
 
                 if let Some(instr) = info.instr.real() {
                     match instr {
                         // LOAD_ATTR → encode with method flag=0
-                        RealInstruction::LoadAttr { idx } => {
+                        Instruction::LoadAttr { idx } => {
                             let encoded = encode_load_attr_arg(idx.get(info.arg), false);
                             info.arg = OpArg(encoded);
-                            info.instr = RealInstruction::LoadAttr { idx: Arg::marker() }.into();
+                            info.instr = Instruction::LoadAttr { idx: Arg::marker() }.into();
                         }
                         // LOAD_SUPER_ATTR → encode with flags=0b10 (method=0, class=1)
-                        RealInstruction::LoadSuperAttr { arg: idx } => {
+                        Instruction::LoadSuperAttr { arg: idx } => {
                             let encoded =
                                 encode_load_super_attr_arg(idx.get(info.arg), false, true);
                             info.arg = OpArg(encoded);
-                            info.instr =
-                                RealInstruction::LoadSuperAttr { arg: Arg::marker() }.into();
+                            info.instr = Instruction::LoadSuperAttr { arg: Arg::marker() }.into();
                         }
                         _ => {}
                     }
@@ -230,29 +229,29 @@ impl CodeInfo {
                     PseudoInstruction::LoadAttrMethod { idx } => {
                         let encoded = encode_load_attr_arg(idx.get(info.arg), true);
                         info.arg = OpArg(encoded);
-                        info.instr = RealInstruction::LoadAttr { idx: Arg::marker() }.into();
+                        info.instr = Instruction::LoadAttr { idx: Arg::marker() }.into();
                     }
                     // POP_BLOCK pseudo → NOP
                     PseudoInstruction::PopBlock => {
-                        info.instr = RealInstruction::Nop.into();
+                        info.instr = Instruction::Nop.into();
                     }
                     // LOAD_SUPER_METHOD pseudo → LOAD_SUPER_ATTR (flags=0b11: method=1, class=1)
                     PseudoInstruction::LoadSuperMethod { idx } => {
                         let encoded = encode_load_super_attr_arg(idx.get(info.arg), true, true);
                         info.arg = OpArg(encoded);
-                        info.instr = RealInstruction::LoadSuperAttr { arg: Arg::marker() }.into();
+                        info.instr = Instruction::LoadSuperAttr { arg: Arg::marker() }.into();
                     }
                     // LOAD_ZERO_SUPER_ATTR pseudo → LOAD_SUPER_ATTR (flags=0b00: method=0, class=0)
                     PseudoInstruction::LoadZeroSuperAttr { idx } => {
                         let encoded = encode_load_super_attr_arg(idx.get(info.arg), false, false);
                         info.arg = OpArg(encoded);
-                        info.instr = RealInstruction::LoadSuperAttr { arg: Arg::marker() }.into();
+                        info.instr = Instruction::LoadSuperAttr { arg: Arg::marker() }.into();
                     }
                     // LOAD_ZERO_SUPER_METHOD pseudo → LOAD_SUPER_ATTR (flags=0b01: method=1, class=0)
                     PseudoInstruction::LoadZeroSuperMethod { idx } => {
                         let encoded = encode_load_super_attr_arg(idx.get(info.arg), true, false);
                         info.arg = OpArg(encoded);
-                        info.instr = RealInstruction::LoadSuperAttr { arg: Arg::marker() }.into();
+                        info.instr = Instruction::LoadSuperAttr { arg: Arg::marker() }.into();
                     }
                     PseudoInstruction::Jump { .. } => {
                         // PseudoInstruction::Jump instructions are handled later
@@ -305,16 +304,16 @@ impl CodeInfo {
 
                     // Convert JUMP pseudo to real instructions (direction depends on offset)
                     let op = match info.instr {
-                        Instruction::Pseudo(PseudoInstruction::Jump { .. })
+                        AnyInstruction::Pseudo(PseudoInstruction::Jump { .. })
                             if target != BlockIdx::NULL =>
                         {
                             let target_offset = block_to_offset[target.idx()].0;
                             if target_offset > current_offset {
-                                RealInstruction::JumpForward {
+                                Instruction::JumpForward {
                                     target: Arg::marker(),
                                 }
                             } else {
-                                RealInstruction::JumpBackward {
+                                Instruction::JumpBackward {
                                     target: Arg::marker(),
                                 }
                             }
@@ -329,7 +328,7 @@ impl CodeInfo {
                     ));
                     instructions.extend(
                         extras
-                            .map(|byte| CodeUnit::new(RealInstruction::ExtendedArg, byte))
+                            .map(|byte| CodeUnit::new(Instruction::ExtendedArg, byte))
                             .chain([CodeUnit { op, arg: lo_arg }]),
                     );
                     current_offset += info.arg.instr_size() as u32;

diff --git a/crates/compiler-core/src/bytecode.rs b/crates/compiler-core/src/bytecode.rs
@@ -16,7 +16,7 @@ use rustpython_wtf8::{Wtf8, Wtf8Buf};
 
 pub use crate::bytecode::{
     instruction::{
-        Arg, Instruction, InstructionMetadata, PseudoInstruction, RealInstruction,
+        AnyInstruction, Arg, Instruction, InstructionMetadata, PseudoInstruction,
         decode_load_attr_arg, decode_load_super_attr_arg, encode_load_attr_arg,
         encode_load_super_attr_arg,
     },
@@ -303,14 +303,14 @@ bitflags! {
 #[derive(Copy, Clone)]
 #[repr(C)]
 pub struct CodeUnit {
-    pub op: RealInstruction,
+    pub op: Instruction,
     pub arg: OpArgByte,
 }
 
 const _: () = assert!(mem::size_of::<CodeUnit>() == 2);
 
 impl CodeUnit {
-    pub const fn new(op: RealInstruction, arg: OpArgByte) -> Self {
+    pub const fn new(op: Instruction, arg: OpArgByte) -> Self {
         Self { op, arg }
     }
 }

diff --git a/crates/compiler-core/src/bytecode/instruction.rs b/crates/compiler-core/src/bytecode/instruction.rs
@@ -12,11 +12,15 @@ use crate::{
     marshal::MarshalError,
 };
 
-/// A Single bytecode instruction.
-/// All instructions above 44 have an argument.
+/// A Single bytecode instruction that are executed by the VM.
+///
+/// Currently aligned with CPython 3.13.
+///
+/// ## See also
+/// - [CPython opcode IDs](https://github.com/python/cpython/blob/627894459a84be3488a1789919679c997056a03c/Include/opcode_ids.h)
 #[derive(Clone, Copy, Debug)]
 #[repr(u8)]
-pub enum RealInstruction {
+pub enum Instruction {
     // ==================== No-argument instructions (opcode < 44) ====================
     Cache = 0, // Placeholder
     BeforeAsyncWith = 1,
@@ -275,20 +279,21 @@ pub enum RealInstruction {
     JumpIfNotExcMatch(Arg<Label>) = 131,
     SetExcInfo = 134,
     Subscript = 135,
+    // Pseudos (needs to be moved to `PseudoInstruction` enum.
     LoadClosure(Arg<NameIdx>) = 253, // TODO: Move to pseudos
 }
 
-const _: () = assert!(mem::size_of::<RealInstruction>() == 1);
+const _: () = assert!(mem::size_of::<Instruction>() == 1);
 
-impl From<RealInstruction> for u8 {
+impl From<Instruction> for u8 {
     #[inline]
-    fn from(ins: RealInstruction) -> Self {
+    fn from(ins: Instruction) -> Self {
         // SAFETY: there's no padding bits
-        unsafe { core::mem::transmute::<RealInstruction, Self>(ins) }
+        unsafe { mem::transmute::<Instruction, Self>(ins) }
     }
 }
 
-impl TryFrom<u8> for RealInstruction {
+impl TryFrom<u8> for Instruction {
     type Error = MarshalError;
 
     #[inline]
@@ -341,14 +346,14 @@ impl TryFrom<u8> for RealInstruction {
             || value == load_closure
             || custom_ops.contains(&value)
         {
-            Ok(unsafe { core::mem::transmute::<u8, Self>(value) })
+            Ok(unsafe { mem::transmute::<u8, Self>(value) })
         } else {
             Err(Self::Error::InvalidBytecode)
         }
     }
 }
 
-impl InstructionMetadata for RealInstruction {
+impl InstructionMetadata for Instruction {
     #[inline]
     fn label_arg(&self) -> Option<Arg<Label>> {
         match self {
@@ -783,6 +788,7 @@ impl InstructionMetadata for RealInstruction {
     }
 }
 
+/// Instructions used by the compiler. They are not executed by the VM.
 #[derive(Clone, Copy, Debug)]
 #[repr(u16)]
 pub enum PseudoInstruction {
@@ -821,7 +827,7 @@ impl From<PseudoInstruction> for u16 {
     #[inline]
     fn from(ins: PseudoInstruction) -> Self {
         // SAFETY: there's no padding bits
-        unsafe { core::mem::transmute::<PseudoInstruction, Self>(ins) }
+        unsafe { mem::transmute::<PseudoInstruction, Self>(ins) }
     }
 }
 
@@ -836,7 +842,7 @@ impl TryFrom<u16> for PseudoInstruction {
         let end = u16::from(Self::StoreFastMaybeNull);
 
         if (start..=end).contains(&value) {
-            Ok(unsafe { core::mem::transmute::<u16, Self>(value) })
+            Ok(unsafe { mem::transmute::<u16, Self>(value) })
         } else {
             Err(Self::Error::InvalidBytecode)
         }
@@ -886,32 +892,32 @@ impl InstructionMetadata for PseudoInstruction {
 }
-    fn fmt_dis(
-        &self,
-        _arg: OpArg,
-        _f: &mut fmt::Formatter<'_>,
-        _ctx: &impl InstrDisplayContext,
-        _expand_code_objects: bool,
-        _pad: usize,
-        _level: usize,
-    ) -> fmt::Result {
-        unimplemented!()
-    }
-}
+    fn fmt_dis(
+        &self,
+        arg: OpArg,
+        f: &mut fmt::Formatter<'_>,
+        _ctx: &impl InstrDisplayContext,
+        _expand_code_objects: bool,
+        pad: usize,
+        _level: usize,
+    ) -> fmt::Result {
+        match self {
+            Self::Jump { target } => write!(f, "{:pad$}({})", "JUMP", target.get(arg)),
+            Self::JumpNoInterrupt { target } => write!(f, "{:pad$}({})", "JUMP_NO_INTERRUPT", target.get(arg)),
+            Self::LoadAttrMethod { idx } => write!(f, "{:pad$}({})", "LOAD_ATTR_METHOD", idx.get(arg)),
+            Self::LoadSuperMethod { idx } => write!(f, "{:pad$}({})", "LOAD_SUPER_METHOD", idx.get(arg)),
+            Self::LoadZeroSuperAttr { idx } => write!(f, "{:pad$}({})", "LOAD_ZERO_SUPER_ATTR", idx.get(arg)),
+            Self::LoadZeroSuperMethod { idx } => write!(f, "{:pad$}({})", "LOAD_ZERO_SUPER_METHOD", idx.get(arg)),
+            Self::PopBlock => write!(f, "POP_BLOCK"),
+            _ => write!(f, "PSEUDO_PLACEHOLDER"),
+        }
+    }
+}
-    fn fmt_dis(
-        &self,
-        _arg: OpArg,
-        _f: &mut fmt::Formatter<'_>,
-        _ctx: &impl InstrDisplayContext,
-        _expand_code_objects: bool,
-        _pad: usize,
-        _level: usize,
-    ) -> fmt::Result {
-        unimplemented!()
-    }
-}
+    fn fmt_dis(
+        &self,
+        arg: OpArg,
+        f: &mut fmt::Formatter<'_>,
+        _ctx: &impl InstrDisplayContext,
+        _expand_code_objects: bool,
+        pad: usize,
+        _level: usize,
+    ) -> fmt::Result {
+        match self {
+            Self::Jump { target } => write!(f, "{:pad$}({})", "JUMP", target.get(arg)),
+            Self::JumpNoInterrupt { target } => write!(f, "{:pad$}({})", "JUMP_NO_INTERRUPT", target.get(arg)),
+            Self::LoadAttrMethod { idx } => write!(f, "{:pad$}({})", "LOAD_ATTR_METHOD", idx.get(arg)),
+            Self::LoadSuperMethod { idx } => write!(f, "{:pad$}({})", "LOAD_SUPER_METHOD", idx.get(arg)),
+            Self::LoadZeroSuperAttr { idx } => write!(f, "{:pad$}({})", "LOAD_ZERO_SUPER_ATTR", idx.get(arg)),
+            Self::LoadZeroSuperMethod { idx } => write!(f, "{:pad$}({})", "LOAD_ZERO_SUPER_METHOD", idx.get(arg)),
+            Self::PopBlock => write!(f, "POP_BLOCK"),
+            _ => write!(f, "PSEUDO_PLACEHOLDER"),
+        }
+    }
+}
 
 #[derive(Clone, Copy, Debug)]
-pub enum Instruction {
-    Real(RealInstruction),
+pub enum AnyInstruction {
+    Real(Instruction),
     Pseudo(PseudoInstruction),
 }
 
-impl From<RealInstruction> for Instruction {
-    fn from(value: RealInstruction) -> Self {
+impl From<Instruction> for AnyInstruction {
+    fn from(value: Instruction) -> Self {
         Self::Real(value)
     }
 }
 
-impl From<PseudoInstruction> for Instruction {
+impl From<PseudoInstruction> for AnyInstruction {
     fn from(value: PseudoInstruction) -> Self {
         Self::Pseudo(value)
     }
 }
 
-impl TryFrom<u8> for Instruction {
+impl TryFrom<u8> for AnyInstruction {
     type Error = MarshalError;
 
     fn try_from(value: u8) -> Result<Self, Self::Error> {
-        Ok(RealInstruction::try_from(value)?.into())
+        Ok(Instruction::try_from(value)?.into())
     }
 }
 
-impl TryFrom<u16> for Instruction {
+impl TryFrom<u16> for AnyInstruction {
     type Error = MarshalError;
 
     fn try_from(value: u16) -> Result<Self, Self::Error> {
@@ -933,7 +939,7 @@ macro_rules! inst_either {
     };
 }
 
-impl InstructionMetadata for Instruction {
+impl InstructionMetadata for AnyInstruction {
     inst_either!(fn label_arg(&self) -> Option<Arg<Label>>);
 
     inst_either!(fn unconditional_branch(&self) -> bool);
@@ -951,9 +957,9 @@ impl InstructionMetadata for Instruction {
     ) -> fmt::Result);
 }
 
-impl Instruction {
+impl AnyInstruction {
     /// Gets the inner value of [`Self::Real`].
-    pub const fn real(self) -> Option<RealInstruction> {
+    pub const fn real(self) -> Option<Instruction> {
         match self {
             Self::Real(ins) => Some(ins),
             _ => None,
@@ -973,7 +979,7 @@ impl Instruction {
     /// # Panics
     ///
     /// If was called on something else other than [`Self::Real`].
-    pub const fn expect_real(self) -> RealInstruction {
+    pub const fn expect_real(self) -> Instruction {
         self.real()
             .expect("Expected Instruction::Real, found Instruction::Pseudo")
     }
@@ -998,8 +1004,8 @@ pub trait InstructionMetadata {
     /// # Examples
     ///
     /// ```
-    /// use rustpython_compiler_core::bytecode::{Arg, RealInstruction, InstructionMetadata};
-    /// let jump_inst = RealInstruction::JumpForward { target: Arg::marker() };
+    /// use rustpython_compiler_core::bytecode::{Arg, Instruction, InstructionMetadata};
+    /// let jump_inst = Instruction::JumpForward { target: Arg::marker() };
     /// assert!(jump_inst.unconditional_branch())
     /// ```
     fn unconditional_branch(&self) -> bool;
@@ -1009,9 +1015,9 @@ pub trait InstructionMetadata {
     /// # Examples
     ///
     /// ```
-    /// use rustpython_compiler_core::bytecode::{Arg, RealInstruction, Label, InstructionMetadata};
+    /// use rustpython_compiler_core::bytecode::{Arg, Instruction, Label, InstructionMetadata};
     /// let (target, jump_arg) = Arg::new(Label(0xF));
-    /// let jump_instruction = RealInstruction::JumpForward { target };
+    /// let jump_instruction = Instruction::JumpForward { target };
     /// assert_eq!(jump_instruction.stack_effect(jump_arg, true), 0);
     /// ```
     fn stack_effect(&self, arg: OpArg, jump: bool) -> i32;

diff --git a/crates/compiler-core/src/bytecode/oparg.rs b/crates/compiler-core/src/bytecode/oparg.rs
@@ -2,7 +2,7 @@ use bitflags::bitflags;
 
 use core::{fmt, num::NonZeroU8};
 
-use crate::bytecode::{CodeUnit, instruction::RealInstruction};
+use crate::bytecode::{CodeUnit, instruction::Instruction};
 
 pub trait OpArgType: Copy {
     fn from_op_arg(x: u32) -> Option<Self>;
@@ -78,9 +78,9 @@ pub struct OpArgState {
 
 impl OpArgState {
     #[inline(always)]
-    pub fn get(&mut self, ins: CodeUnit) -> (RealInstruction, OpArg) {
+    pub fn get(&mut self, ins: CodeUnit) -> (Instruction, OpArg) {
         let arg = self.extend(ins.arg);
-        if !matches!(ins.op, RealInstruction::ExtendedArg) {
+        if !matches!(ins.op, Instruction::ExtendedArg) {
             self.reset();
         }
         (ins.op, arg)
@@ -98,7 +98,7 @@ impl OpArgState {
     }
 }
 
-/// Oparg values for [`RealInstruction::ConvertValue`].
+/// Oparg values for [`Instruction::ConvertValue`].
 ///
 /// ## See also
 ///
@@ -142,7 +142,7 @@ impl fmt::Display for ConvertValueOparg {
             Self::Str => "1 (str)",
             Self::Repr => "2 (repr)",
             Self::Ascii => "3 (ascii)",
-            // We should never reach this. `FVC_NONE` are being handled by `RealInstruction::FormatSimple`
+            // We should never reach this. `FVC_NONE` are being handled by `Instruction::FormatSimple`
             Self::None => "",
         };
 
@@ -364,9 +364,9 @@ op_arg_enum!(
     /// # Examples
     ///
     /// ```rust
-    /// use rustpython_compiler_core::bytecode::{Arg, BinaryOperator, RealInstruction};
+    /// use rustpython_compiler_core::bytecode::{Arg, BinaryOperator, Instruction};
     /// let (op, _) = Arg::new(BinaryOperator::Add);
-    /// let instruction = RealInstruction::BinaryOp { op };
+    /// let instruction = Instruction::BinaryOp { op };
     /// ```
     ///
     /// See also: