superacli 1.1.4 → 1.1.6

package/ref-monty/crates/monty/src/types/py_trait.rs

@@ -0,0 +1,322 @@
+/// Trait for heap-allocated Python values that need common operations.
+///
+/// This trait abstracts over container types (List, Tuple, Str, Bytes) stored
+/// in the heap, providing a unified interface for operations like length,
+/// equality, reference counting support, and attribute dispatch.
+///
+/// The trait is designed to work with `enum_dispatch` for efficient virtual
+/// dispatch on `HeapData` without boxing overhead.
+use std::borrow::Cow;
+use std::{cmp::Ordering, fmt::Write};
+
+use ahash::AHashSet;
+
+use super::Type;
+use crate::{
+    ResourceError,
+    args::ArgValues,
+    bytecode::{CallResult, VM},
+    exception_private::{ExcType, RunResult, SimpleException},
+    heap::{DropWithHeap, Heap, HeapId},
+    resource::ResourceTracker,
+    value::{EitherStr, Value},
+};
+
+/// Common operations for heap-allocated Python values.
+///
+/// Implementers should provide Python-compatible semantics for all operations.
+/// Most methods take a `&VM` or `&mut VM` reference to access the heap and interned
+/// strings for nested lookups in containers holding `Value::Ref` values.
+///
+/// This trait is used with `enum_dispatch` on `HeapData` to enable efficient
+/// virtual dispatch without boxing overhead.
+///
+/// Many methods are generic over `T: ResourceTracker` to work with any heap
+/// configuration. This allows the same trait to work with both unlimited and
+/// resource-limited execution contexts.
+pub trait PyTrait {
+    /// Returns the Python type name for this value (e.g., "list", "str").
+    ///
+    /// Used for error messages and the `type()` builtin.
+    /// Takes heap reference for cases where nested Value lookups are needed.
+    fn py_type(&self, heap: &Heap<impl ResourceTracker>) -> Type;
+
+    /// Returns the number of elements in this container.
+    ///
+    /// For interns, returns the number of Unicode codepoints (characters), matching Python.
+    /// Returns `None` if the type doesn't support `len()`.
+    fn py_len(&self, vm: &VM<'_, '_, impl ResourceTracker>) -> Option<usize>;
+
+    /// Python equality comparison (`==`).
+    ///
+    /// For containers, this performs element-wise comparison using the heap
+    /// to resolve nested references. Takes `&mut VM` to allow lazy hash
+    /// computation for dict key lookups and access to interned string content.
+    ///
+    /// Recursion depth is tracked via `heap.incr_recursion_depth()`.
+    ///
+    /// Returns `Ok(true)` if equal, `Ok(false)` if not equal, or
+    /// `Err(ResourceError::Recursion)` if maximum depth is exceeded.
+    fn py_eq(&self, other: &Self, vm: &mut VM<'_, '_, impl ResourceTracker>) -> Result<bool, ResourceError>;
+
+    /// Python comparison (`<`, `>`, etc.).
+    ///
+    /// For containers, this performs element-wise comparison using the heap
+    /// to resolve nested references. Takes `&mut VM` to allow lazy hash
+    /// computation for dict key lookups and access to interned string content.
+    ///
+    /// Recursion depth is tracked via `heap.incr_recursion_depth()`.
+    ///
+    /// Returns `Ok(Some(Ordering))` for comparable values, `Ok(None)` if not comparable,
+    /// or `Err(ResourceError::Recursion)` if maximum depth is exceeded.
+    fn py_cmp(
+        &self,
+        _other: &Self,
+        _vm: &mut VM<'_, '_, impl ResourceTracker>,
+    ) -> Result<Option<Ordering>, ResourceError> {
+        Ok(None)
+    }
+
+    /// Pushes any contained `HeapId`s onto the stack for reference counting.
+    ///
+    /// This is called during `dec_ref` to find nested heap references that
+    /// need their refcounts decremented when this value is freed.
+    ///
+    /// When the `ref-count-panic` feature is enabled, this method also marks all
+    /// contained `Value`s as `Dereferenced` to prevent Drop panics. This
+    /// co-locates the cleanup logic with the reference collection logic.
+    fn py_dec_ref_ids(&mut self, stack: &mut Vec<HeapId>);
+
+    /// Returns the truthiness of the value following Python semantics.
+    ///
+    /// Container types should typically report `false` when empty.
+    fn py_bool(&self, vm: &VM<'_, '_, impl ResourceTracker>) -> bool {
+        self.py_len(vm) != Some(0)
+    }
+
+    /// Writes the Python `repr()` string for this value to a formatter.
+    ///
+    /// This method enables cycle detection for self-referential structures by tracking
+    /// visited heap IDs. When a cycle is detected (ID already in `heap_ids`), implementations
+    /// should write an ellipsis (e.g., `[...]` for lists, `{...}` for dicts).
+    ///
+    /// Recursion depth is tracked via `heap.incr_recursion_depth_for_repr()`.
+    ///
+    /// # Arguments
+    /// * `f` - The formatter to write to
+    /// * `vm` - The VM for resolving value references and looking up interned strings
+    /// * `heap_ids` - Set of heap IDs currently being repr'd (for cycle detection)
+    fn py_repr_fmt(
+        &self,
+        f: &mut impl Write,
+        vm: &VM<'_, '_, impl ResourceTracker>,
+        heap_ids: &mut AHashSet<HeapId>,
+    ) -> std::fmt::Result;
+
+    /// Returns the Python `repr()` string for this value.
+    ///
+    /// Convenience wrapper around `py_repr_fmt` that returns an owned string.
+    fn py_repr(&self, vm: &VM<'_, '_, impl ResourceTracker>) -> Cow<'static, str> {
+        let mut s = String::new();
+        let mut heap_ids = AHashSet::new();
+        // Unwrap is safe: writing to String never fails
+        self.py_repr_fmt(&mut s, vm, &mut heap_ids).unwrap();
+        Cow::Owned(s)
+    }
+
+    /// Returns the Python `str()` string for this value.
+    ///
+    /// Recursion depth is tracked via the heap's recursion depth counter.
+    fn py_str(&self, vm: &VM<'_, '_, impl ResourceTracker>) -> Cow<'static, str> {
+        self.py_repr(vm)
+    }
+
+    /// Python addition (`__add__`).
+    ///
+    /// Returns `Ok(None)` if the operation is not supported for these types,
+    /// `Ok(Some(value))` on success, or `Err(ResourceError)` if allocation fails.
+    fn py_add(
+        &self,
+        _other: &Self,
+        _vm: &mut VM<'_, '_, impl ResourceTracker>,
+    ) -> Result<Option<Value>, ResourceError> {
+        Ok(None)
+    }
+
+    /// Python subtraction (`__sub__`).
+    ///
+    /// Returns `Ok(None)` if the operation is not supported for these types,
+    /// `Ok(Some(value))` on success, or `Err(ResourceError)` if allocation fails.
+    fn py_sub(
+        &self,
+        _other: &Self,
+        _vm: &mut VM<'_, '_, impl ResourceTracker>,
+    ) -> Result<Option<Value>, ResourceError> {
+        Ok(None)
+    }
+
+    /// Python modulus (`__mod__`).
+    ///
+    /// Returns `Ok(None)` if the operation is not supported for these types,
+    /// `Ok(Some(value))` on success, or `Err(RunError)` if an error occurs.
+    fn py_mod(&self, _other: &Self, _vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Option<Value>> {
+        Ok(None)
+    }
+
+    /// Optimized helper for `(a % b) == c` comparisons.
+    fn py_mod_eq(&self, _other: &Self, _right_value: i64) -> Option<bool> {
+        None
+    }
+
+    /// Python in-place addition (`__iadd__`).
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(true)` if the operation was successful, `Ok(false)` if not supported,
+    /// or `Err(ResourceError)` if allocation fails.
+    fn py_iadd(
+        &mut self,
+        _other: &Value,
+        _vm: &mut VM<'_, '_, impl ResourceTracker>,
+        _self_id: Option<HeapId>,
+    ) -> Result<bool, ResourceError> {
+        Ok(false)
+    }
+
+    /// Python multiplication (`__mul__`).
+    ///
+    /// Returns `Ok(None)` if the operation is not supported for these types.
+    /// For numeric types: Int * Int, Float * Float, Int * Float, etc.
+    /// For sequences: str * int, list * int for repetition.
+    fn py_mult(&self, _other: &Self, _vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Option<Value>> {
+        Ok(None)
+    }
+
+    /// Python true division (`__truediv__`).
+    ///
+    /// Always returns float for numeric types. Returns `Ok(None)` if not supported.
+    /// Returns `Err(ZeroDivisionError)` for division by zero.
+    fn py_div(&self, _other: &Self, _vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Option<Value>> {
+        Ok(None)
+    }
+
+    /// Python floor division (`__floordiv__`).
+    ///
+    /// Returns int for int//int, float for float operations.
+    /// Returns `Ok(None)` if not supported.
+    /// Returns `Err(ZeroDivisionError)` for division by zero.
+    fn py_floordiv(&self, _other: &Self, _vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Option<Value>> {
+        Ok(None)
+    }
+
+    /// Python power (`__pow__`).
+    ///
+    /// Int ** positive_int returns int, int ** negative_int returns float.
+    /// Returns `Ok(None)` if not supported.
+    /// Returns `Err(ZeroDivisionError)` for 0 ** negative.
+    fn py_pow(&self, _other: &Self, _vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Option<Value>> {
+        Ok(None)
+    }
+
+    /// Calls an attribute method on this value (e.g., `list.append()`), returning a
+    /// `CallResult` that may signal OS, external, or method calls.
+    ///
+    /// This method enables types to signal that they need operations the VM cannot perform
+    /// directly (OS operations, external function calls, dataclass method calls). The VM
+    /// converts the result to the appropriate `FrameExit` variant.
+    ///
+    /// Types that only support synchronous attribute calls should wrap their return value
+    /// with `CallResult::Value`. Types that need to perform OS/external operations,
+    /// intercept specific methods (e.g. `list.sort`), or detect method calls (e.g. dataclass
+    /// methods) should return the appropriate `CallResult` variant.
+    ///
+    /// # Arguments
+    /// * `self_id` - The heap ID of this value, needed by types that must reference themselves
+    ///   (e.g. dataclass method calls prepend `self` to args)
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(CallResult::Value(v))` - Method completed synchronously with value `v`
+    /// - `Ok(CallResult::OsCall(func, args))` - Method needs OS operation; VM yields to host
+    /// - `Ok(CallResult::External(name, args))` - Method needs external function call
+    /// - `Ok(CallResult::MethodCall(attr, args))` - Dataclass method call; VM yields to host
+    /// - `Err(e)` - Method call failed with error
+    fn py_call_attr(
+        &mut self,
+        _self_id: HeapId,
+        vm: &mut VM<'_, '_, impl ResourceTracker>,
+        attr: &EitherStr,
+        args: ArgValues,
+    ) -> RunResult<CallResult> {
+        // `py_call_attr` takes ownership of the argument bundle. Implementations that
+        // do not recognize the attribute still need to release those values before
+        // reporting `AttributeError`, otherwise method calls on unsupported types leak
+        // references on the error path (caught by `ref-count-panic`).
+        args.drop_with_heap(vm);
+        Err(ExcType::attribute_error(self.py_type(vm.heap), attr.as_str(vm.interns)))
+    }
+
+    /// Estimates the memory size in bytes of this value.
+    ///
+    /// Used by resource tracking to enforce memory limits. Returns the approximate
+    /// heap footprint including struct overhead and variable-length data (e.g., string
+    /// contents, list elements).
+    ///
+    /// Note: For containers holding `Value::Ref` entries, this counts the size of
+    /// the reference slots, not the referenced objects. Nested objects are sized
+    /// separately when they are allocated.
+    fn py_estimate_size(&self) -> usize;
+
+    /// Python subscript get operation (`__getitem__`), e.g., `d[key]`.
+    ///
+    /// Returns the value associated with the key, or an error if the key doesn't exist
+    /// or the type doesn't support subscripting.
+    ///
+    /// Takes `&mut VM` for proper reference counting when cloning the returned value
+    /// and access to interned string content.
+    ///
+    /// Default implementation returns TypeError.
+    fn py_getitem(&self, _key: &Value, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Value> {
+        Err(ExcType::type_error_not_sub(self.py_type(vm.heap)))
+    }
+
+    /// Python subscript set operation (`__setitem__`), e.g., `d[key] = value`.
+    ///
+    /// Sets the value associated with the key, or returns an error if the key is invalid
+    /// or the type doesn't support subscript assignment.
+    ///
+    /// Default implementation returns TypeError.
+    fn py_setitem(&mut self, key: Value, value: Value, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<()> {
+        key.drop_with_heap(vm.heap);
+        value.drop_with_heap(vm.heap);
+        Err(SimpleException::new_msg(
+            ExcType::TypeError,
+            format!("'{}' object does not support item assignment", self.py_type(vm.heap)),
+        )
+        .into())
+    }
+
+    /// Python attribute get operation (`__getattr__`), e.g., `obj.attr`.
+    ///
+    /// Returns the value associated with the attribute (owned), or `Ok(None)` if the type
+    /// doesn't support attribute access at all. Types that support attributes should return
+    /// `Err(AttributeError)` when an attribute is not found, not `Ok(None)`.
+    ///
+    /// The returned `Value` is always owned:
+    /// - For stored values (Dataclass, Module, NamedTuple fields): clone with `clone_with_heap`
+    /// - For computed values (Exception.args, Slice.start, Path.name): return newly created value
+    ///
+    /// Takes `&mut VM` to allow:
+    /// - Cloning stored values with proper reference counting
+    /// - Allocating computed values that need heap storage
+    ///
+    /// Default implementation returns `Ok(None)`, indicating the type doesn't support
+    /// attribute access and a generic `AttributeError` should be raised by the caller.
+    fn py_getattr(
+        &self,
+        _attr: &EitherStr,
+        _vm: &mut VM<'_, '_, impl ResourceTracker>,
+    ) -> RunResult<Option<CallResult>> {
+        Ok(None)
+    }
+}

package/ref-monty/crates/monty/src/types/range.rs

@@ -0,0 +1,285 @@
+//! Python range type implementation.
+//!
+//! Provides a range object that supports iteration over a sequence of integers
+//! with configurable start, stop, and step values.
+
+use std::fmt::Write;
+
+use ahash::AHashSet;
+
+use crate::{
+    args::ArgValues,
+    bytecode::VM,
+    defer_drop,
+    exception_private::{ExcType, RunResult},
+    heap::{Heap, HeapData, HeapId},
+    resource::{ResourceError, ResourceTracker},
+    types::{PyTrait, Type},
+    value::Value,
+};
+
+/// Python range object representing an immutable sequence of integers.
+///
+/// Supports three forms of construction:
+/// - `range(stop)` - integers from 0 to stop-1
+/// - `range(start, stop)` - integers from start to stop-1
+/// - `range(start, stop, step)` - integers from start, incrementing by step
+///
+/// The range is computed lazily during iteration, not stored as a list.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
+pub(crate) struct Range {
+    /// The starting value (inclusive). Defaults to 0.
+    pub start: i64,
+    /// The ending value (exclusive).
+    pub stop: i64,
+    /// The step between values. Defaults to 1. Cannot be 0.
+    pub step: i64,
+}
+
+impl Range {
+    /// Creates a new range with the given start, stop, and step.
+    ///
+    /// # Panics
+    /// Panics if step is 0. Use `new_checked` for fallible construction.
+    #[must_use]
+    fn new(start: i64, stop: i64, step: i64) -> Self {
+        debug_assert!(step != 0, "range step cannot be 0");
+        Self { start, stop, step }
+    }
+
+    /// Creates a range from just a stop value (start=0, step=1).
+    #[must_use]
+    fn from_stop(stop: i64) -> Self {
+        Self {
+            start: 0,
+            stop,
+            step: 1,
+        }
+    }
+
+    /// Creates a range from start and stop (step=1).
+    #[must_use]
+    fn from_start_stop(start: i64, stop: i64) -> Self {
+        Self { start, stop, step: 1 }
+    }
+
+    /// Returns the length of the range (number of elements it will yield).
+    #[must_use]
+    pub fn len(&self) -> usize {
+        if self.step > 0 {
+            if self.stop > self.start {
+                let len_i64 = (self.stop - self.start - 1) / self.step + 1;
+                usize::try_from(len_i64).expect("range length guaranteed non-negative")
+            } else {
+                0
+            }
+        } else {
+            // step < 0
+            if self.start > self.stop {
+                let len_i64 = (self.start - self.stop - 1) / (-self.step) + 1;
+                usize::try_from(len_i64).expect("range length guaranteed non-negative")
+            } else {
+                0
+            }
+        }
+    }
+
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// Checks if an integer value is contained within this range (O(1)).
+    ///
+    /// A value is contained if it falls within the range bounds and is aligned
+    /// with the step (i.e., `(n - start) % step == 0`).
+    #[must_use]
+    pub fn contains(&self, n: i64) -> bool {
+        if self.step > 0 {
+            // Forward range: start <= n < stop
+            if n < self.start || n >= self.stop {
+                return false;
+            }
+        } else {
+            // Backward range: stop < n <= start
+            if n > self.start || n <= self.stop {
+                return false;
+            }
+        }
+        // Check if n is on the step grid
+        (n - self.start) % self.step == 0
+    }
+
+    /// Creates a range from the `range()` constructor call.
+    ///
+    /// Supports:
+    /// - `range(stop)` - range from 0 to stop
+    /// - `range(start, stop)` - range from start to stop
+    /// - `range(start, stop, step)` - range with custom step
+    pub fn init(vm: &mut VM<'_, '_, impl ResourceTracker>, args: ArgValues) -> RunResult<Value> {
+        let heap = &mut *vm.heap;
+        let pos_args = args.into_pos_only("range", heap)?;
+        defer_drop!(pos_args, heap);
+
+        let range = match pos_args.as_slice() {
+            [] => return Err(ExcType::type_error_at_least("range", 1, 0)),
+            [first_arg] => {
+                let stop = first_arg.as_int(heap)?;
+                Self::from_stop(stop)
+            }
+            [first_arg, second_arg] => {
+                let start = first_arg.as_int(heap)?;
+                let stop = second_arg.as_int(heap)?;
+                Self::from_start_stop(start, stop)
+            }
+            [first_arg, second_arg, third_arg] => {
+                let start = first_arg.as_int(heap)?;
+                let stop = second_arg.as_int(heap)?;
+                let step = third_arg.as_int(heap)?;
+                if step == 0 {
+                    return Err(ExcType::value_error_range_step_zero());
+                }
+                Self::new(start, stop, step)
+            }
+            _ => return Err(ExcType::type_error_at_most("range", 3, pos_args.len())),
+        };
+
+        Ok(Value::Ref(heap.allocate(HeapData::Range(range))?))
+    }
+
+    /// Handles slice-based indexing for ranges.
+    ///
+    /// Returns a new range object representing the sliced view.
+    /// The new range has computed start, stop, and step values.
+    fn getitem_slice(&self, slice: &crate::types::Slice, heap: &mut Heap<impl ResourceTracker>) -> RunResult<Value> {
+        let range_len = self.len();
+        let (start, stop, step) = slice
+            .indices(range_len)
+            .map_err(|()| ExcType::value_error_slice_step_zero())?;
+
+        // Calculate the new range parameters
+        // new_start = self.start + start * self.step
+        // new_step = self.step * slice_step
+        // new_stop needs to be computed based on the number of elements
+
+        let new_step = self.step.saturating_mul(step);
+        let start_i64 = i64::try_from(start).expect("start index fits in i64");
+        let new_start = self.start.saturating_add(start_i64.saturating_mul(self.step));
+
+        // Calculate the number of elements in the sliced range
+        // try_from succeeds for non-negative step; step==0 rejected by slice.indices()
+        let num_elements = if let Ok(step_usize) = usize::try_from(step) {
+            // Forward iteration
+            if start >= stop {
+                0
+            } else {
+                ((stop - start - 1) / step_usize) + 1
+            }
+        } else {
+            // Backward iteration
+            let step_abs = usize::try_from(-step).expect("step is negative so -step is positive");
+            if stop > range_len {
+                // stop sentinel means "go to the beginning"
+                (start / step_abs) + 1
+            } else if start <= stop {
+                0
+            } else {
+                ((start - stop - 1) / step_abs) + 1
+            }
+        };
+
+        // new_stop = new_start + num_elements * new_step
+        let num_elements_i64 = i64::try_from(num_elements).expect("num_elements fits in i64");
+        let new_stop = new_start.saturating_add(num_elements_i64.saturating_mul(new_step));
+
+        let new_range = Self::new(new_start, new_stop, new_step);
+        Ok(Value::Ref(heap.allocate(HeapData::Range(new_range))?))
+    }
+}
+
+impl Default for Range {
+    fn default() -> Self {
+        Self::from_stop(0)
+    }
+}
+
+impl PyTrait for Range {
+    fn py_type(&self, _heap: &Heap<impl ResourceTracker>) -> Type {
+        Type::Range
+    }
+
+    fn py_len(&self, _vm: &VM<'_, '_, impl ResourceTracker>) -> Option<usize> {
+        Some(self.len())
+    }
+
+    fn py_getitem(&self, key: &Value, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Value> {
+        // Check for slice first (Value::Ref pointing to HeapData::Slice)
+        if let Value::Ref(id) = key
+            && let HeapData::Slice(slice) = vm.heap.get(*id)
+        {
+            // Clone the slice to release the borrow on heap before calling getitem_slice
+            let slice = slice.clone();
+            return self.getitem_slice(&slice, vm.heap);
+        }
+
+        // Extract integer index, accepting Int, Bool (True=1, False=0), and LongInt
+        let index = key.as_index(vm.heap, Type::Range)?;
+
+        // Get range length for normalization
+        let len = i64::try_from(self.len()).expect("range length exceeds i64::MAX");
+        let normalized = if index < 0 { index + len } else { index };
+
+        // Bounds check
+        if normalized < 0 || normalized >= len {
+            return Err(ExcType::range_index_error());
+        }
+
+        // Calculate: start + normalized * step
+        // Use checked arithmetic to avoid overflow in intermediate calculations
+        let offset = normalized
+            .checked_mul(self.step)
+            .and_then(|v| self.start.checked_add(v))
+            .expect("range element calculation overflowed");
+        Ok(Value::Int(offset))
+    }
+
+    fn py_eq(&self, other: &Self, _vm: &mut VM<'_, '_, impl ResourceTracker>) -> Result<bool, ResourceError> {
+        // Compare ranges by their actual sequences, not parameters.
+        // Two ranges are equal if they produce the same elements.
+        let len1 = self.len();
+        let len2 = other.len();
+        if len1 != len2 {
+            return Ok(false);
+        }
+        // Same length - compare first element and step (if non-empty)
+        if len1 == 0 {
+            return Ok(true); // Both empty
+        }
+        Ok(self.start == other.start && self.step == other.step)
+    }
+
+    fn py_bool(&self, _vm: &VM<'_, '_, impl ResourceTracker>) -> bool {
+        !self.is_empty()
+    }
+
+    fn py_repr_fmt(
+        &self,
+        f: &mut impl Write,
+        _vm: &VM<'_, '_, impl ResourceTracker>,
+        _heap_ids: &mut AHashSet<HeapId>,
+    ) -> std::fmt::Result {
+        if self.step == 1 {
+            write!(f, "range({}, {})", self.start, self.stop)
+        } else {
+            write!(f, "range({}, {}, {})", self.start, self.stop, self.step)
+        }
+    }
+
+    fn py_dec_ref_ids(&mut self, _stack: &mut Vec<HeapId>) {
+        // Range doesn't contain heap references, nothing to do
+    }
+
+    fn py_estimate_size(&self) -> usize {
+        std::mem::size_of::<Self>()
+    }
+}