superacli 1.1.4 → 1.1.6

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

@@ -0,0 +1,879 @@
+use std::{
+    collections::hash_map::DefaultHasher,
+    fmt::Write,
+    hash::{Hash, Hasher},
+};
+
+use ahash::AHashSet;
+use hashbrown::{HashTable, hash_table::Entry};
+use smallvec::smallvec;
+
+use super::{DictItemsView, DictKeysView, DictValuesView, MontyIter, PyTrait, allocate_tuple};
+use crate::{
+    args::{ArgValues, KwargsValues},
+    bytecode::{CallResult, VM},
+    defer_drop, defer_drop_mut,
+    exception_private::{ExcType, RunResult},
+    heap::{ContainsHeap, DropWithHeap, Heap, HeapData, HeapGuard, HeapId},
+    intern::{Interns, StaticStrings},
+    resource::{ResourceError, ResourceTracker},
+    types::Type,
+    value::{EitherStr, Value},
+};
+
+/// Python dict type preserving insertion order.
+///
+/// This type provides Python dict semantics including dynamic key-value namespaces,
+/// reference counting for heap values, and standard dict methods.
+///
+/// # Implemented Methods
+/// - `get(key[, default])` - Get value or default
+/// - `keys()` - Return view of keys
+/// - `values()` - Return view of values
+/// - `items()` - Return view of (key, value) pairs
+/// - `pop(key[, default])` - Remove and return value
+/// - `clear()` - Remove all items
+/// - `copy()` - Shallow copy
+/// - `update(other)` - Update from dict or iterable of pairs
+/// - `setdefault(key[, default])` - Get or set default value
+/// - `popitem()` - Remove and return last (key, value) pair
+/// - `fromkeys(iterable[, value])` - Create dict from keys (classmethod)
+///
+/// All dict methods from Python's builtins are implemented.
+///
+/// # Storage Strategy
+/// Uses a `HashTable<usize>` for hash lookups combined with a dense `Vec<DictEntry>`
+/// to preserve insertion order (matching Python 3.7+ behavior). The hash table maps
+/// key hashes to indices in the entries vector. This design provides O(1) lookups
+/// while maintaining insertion order for iteration.
+///
+/// # Reference Counting
+/// When values are added via `set()`, their reference counts are incremented.
+/// When using `from_pairs()`, ownership is transferred without incrementing refcounts
+/// (caller must ensure values' refcounts account for the dict's reference).
+///
+/// # GC Optimization
+/// The `contains_refs` flag tracks whether the dict contains any `Value::Ref` items.
+/// This allows `collect_child_ids` and `py_dec_ref_ids` to skip iteration when the
+/// dict contains only primitive values (ints, bools, None, etc.), significantly
+/// improving GC performance for dicts of primitives.
+#[derive(Debug, Default)]
+pub(crate) struct Dict {
+    /// indices mapping from the entry hash to its index.
+    indices: HashTable<usize>,
+    /// entries is a dense vec maintaining entry order.
+    entries: Vec<DictEntry>,
+    /// True if any key or value in the dict is a `Value::Ref`. Used to skip iteration
+    /// in `collect_child_ids` and `py_dec_ref_ids` when no refs are present.
+    /// Only transitions from false to true (never back) since tracking removals would be O(n).
+    contains_refs: bool,
+}
+
+#[derive(Debug, serde::Serialize, serde::Deserialize)]
+struct DictEntry {
+    key: Value,
+    value: Value,
+    /// the hash is needed here for correct use of insert_unique
+    hash: u64,
+}
+
+impl Dict {
+    /// Creates a new empty dict.
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_capacity(capacity: usize) -> Self {
+        Self {
+            indices: HashTable::with_capacity(capacity),
+            entries: Vec::with_capacity(capacity),
+            contains_refs: false,
+        }
+    }
+
+    /// Returns whether this dict contains any heap references (`Value::Ref`).
+    ///
+    /// Used during allocation to determine if this container could create cycles,
+    /// and in `collect_child_ids` and `py_dec_ref_ids` to skip iteration when no refs
+    /// are present.
+    ///
+    /// Note: This flag only transitions from false to true (never back). When a ref is
+    /// removed via `pop()`, we do NOT recompute the flag because that would be O(n).
+    /// This is conservative - we may iterate unnecessarily if all refs were removed,
+    /// but we'll never skip iteration when refs exist.
+    #[inline]
+    #[must_use]
+    pub fn has_refs(&self) -> bool {
+        self.contains_refs
+    }
+
+    /// Creates a dict from a vector of (key, value) pairs.
+    ///
+    /// Assumes the caller is transferring ownership of all keys and values in the pairs.
+    /// Does NOT increment reference counts since ownership is being transferred.
+    /// Returns Err if any key is unhashable (e.g., list, dict).
+    pub fn from_pairs(pairs: Vec<(Value, Value)>, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Self> {
+        let pairs_iter = pairs.into_iter();
+        defer_drop_mut!(pairs_iter, vm);
+        let dict = Self::with_capacity(pairs_iter.len());
+        let mut dict_guard = HeapGuard::new(dict, vm);
+        let (dict, vm) = dict_guard.as_parts_mut();
+        for (key, value) in pairs_iter {
+            if let Some(old_value) = dict.set(key, value, vm)? {
+                old_value.drop_with_heap(vm);
+            }
+        }
+        Ok(dict_guard.into_inner())
+    }
+
+    /// Gets a value from the dict by key.
+    ///
+    /// Returns Ok(Some(value)) if key exists, Ok(None) if key doesn't exist.
+    /// Returns Err if key is unhashable.
+    pub fn get(&self, key: &Value, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Option<&Value>> {
+        if let Some(index) = self.find_index_hash(key, vm)?.0 {
+            Ok(Some(&self.entries[index].value))
+        } else {
+            Ok(None)
+        }
+    }
+
+    /// Gets a value from the dict by string key name (immutable lookup).
+    ///
+    /// This is an O(1) lookup that doesn't require mutable heap access.
+    /// Only works for string keys - returns None if the key is not found.
+    pub fn get_by_str(&self, key_str: &str, heap: &Heap<impl ResourceTracker>, interns: &Interns) -> Option<&Value> {
+        // Compute hash for the string key
+        let mut hasher = DefaultHasher::new();
+        key_str.hash(&mut hasher);
+        let hash = hasher.finish();
+
+        // Find entry with matching hash and key
+        self.indices
+            .find(hash, |&idx| {
+                let entry_key = &self.entries[idx].key;
+                match entry_key {
+                    Value::InternString(id) => interns.get_str(*id) == key_str,
+                    Value::Ref(id) => {
+                        if let HeapData::Str(s) = heap.get(*id) {
+                            s.as_str() == key_str
+                        } else {
+                            false
+                        }
+                    }
+                    _ => false,
+                }
+            })
+            .map(|&idx| &self.entries[idx].value)
+    }
+
+    /// Sets a key-value pair in the dict.
+    ///
+    /// The caller transfers ownership of `key` and `value` to the dict. Their refcounts
+    /// are NOT incremented here - the caller is responsible for ensuring the refcounts
+    /// were already incremented (e.g., via `clone_with_heap` or `evaluate_use`).
+    ///
+    /// If the key already exists, replaces the old value and returns it (caller now
+    /// owns the old value and is responsible for its refcount).
+    /// Returns Err if key is unhashable.
+    pub fn set(
+        &mut self,
+        key: Value,
+        value: Value,
+        vm: &mut VM<'_, '_, impl ResourceTracker>,
+    ) -> RunResult<Option<Value>> {
+        // Track if we're adding a reference for GC optimization
+        if matches!(key, Value::Ref(_)) || matches!(value, Value::Ref(_)) {
+            self.contains_refs = true;
+        }
+
+        // Handle hash computation errors explicitly so we can drop key/value properly
+        let (opt_index, hash) = match self.find_index_hash(&key, vm) {
+            Ok(result) => result,
+            Err(e) => {
+                // Drop the key and value before returning the error
+                key.drop_with_heap(vm);
+                value.drop_with_heap(vm);
+                return Err(e);
+            }
+        };
+
+        let entry = DictEntry { key, value, hash };
+        if let Some(index) = opt_index {
+            // Key exists, replace in place to preserve insertion order
+            let old_entry = std::mem::replace(&mut self.entries[index], entry);
+
+            // Decrement refcount for old key (we're discarding it)
+            old_entry.key.drop_with_heap(vm);
+            // Transfer ownership of the old value to caller (no clone needed)
+            Ok(Some(old_entry.value))
+        } else {
+            // Key doesn't exist, add new pair to indices and entries
+            let index = self.entries.len();
+            self.entries.push(entry);
+            self.indices
+                .insert_unique(hash, index, |index| self.entries[*index].hash);
+            Ok(None)
+        }
+    }
+
+    /// Removes and returns a key-value pair from the dict.
+    ///
+    /// Returns Ok(Some((key, value))) if key exists, Ok(None) if key doesn't exist.
+    /// Returns Err if key is unhashable.
+    ///
+    /// Reference counting: does not decrement refcounts for removed key and value;
+    /// caller assumes ownership and is responsible for managing their refcounts.
+    pub fn pop(&mut self, key: &Value, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Option<(Value, Value)>> {
+        let hash = key
+            .py_hash(vm.heap, vm.interns)?
+            .ok_or_else(|| ExcType::type_error_unhashable_dict_key(key.py_type(vm.heap)))?;
+
+        let entry = self.indices.entry(
+            hash,
+            |v| key.py_eq(&self.entries[*v].key, vm).unwrap_or(false),
+            |index| self.entries[*index].hash,
+        );
+
+        if let Entry::Occupied(occ_entry) = entry {
+            let entry = self.entries.remove(*occ_entry.get());
+            occ_entry.remove();
+            // Don't decrement refcounts - caller now owns the values
+            Ok(Some((entry.key, entry.value)))
+        } else {
+            Ok(None)
+        }
+    }
+
+    /// Returns the number of key-value pairs in the dict.
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// Returns true if the dict is empty.
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// Returns an iterator over references to (key, value) pairs.
+    pub fn iter(&self) -> DictIter<'_> {
+        self.into_iter()
+    }
+
+    /// Returns the key at the given iteration index, or None if out of bounds.
+    ///
+    /// Used for index-based iteration in for loops. Returns a reference to
+    /// the key at the given position in insertion order.
+    pub fn key_at(&self, index: usize) -> Option<&Value> {
+        self.entries.get(index).map(|e| &e.key)
+    }
+
+    /// Returns the value at the given iteration index, or None if out of bounds.
+    ///
+    /// Dictionary views use this to produce live `dict_values` iteration directly
+    /// from the underlying storage without copying the dictionary.
+    pub fn value_at(&self, index: usize) -> Option<&Value> {
+        self.entries.get(index).map(|e| &e.value)
+    }
+
+    /// Returns the key-value pair at the given iteration index, or None if out of bounds.
+    ///
+    /// This accessor keeps dict-view iteration logic out of the storage internals
+    /// while still allowing `dict_items` to produce tuples on demand.
+    pub fn item_at(&self, index: usize) -> Option<(&Value, &Value)> {
+        self.entries.get(index).map(|entry| (&entry.key, &entry.value))
+    }
+
+    /// Creates a dict from the `dict([mapping_or_pairs], **kwargs)` constructor call.
+    ///
+    /// Supported forms:
+    /// - `dict()` returns an empty dict.
+    /// - `dict(existing_dict)` returns a shallow copy of the dict.
+    /// - `dict(iterable_of_pairs)` consumes `(key, value)` pairs from the iterable.
+    /// - `dict(**kwargs)` inserts keyword arguments as string keys.
+    ///
+    /// Keyword arguments are applied after the optional positional source, matching
+    /// CPython precedence (`dict([('a', 1)], a=2)` yields `{'a': 2}`).
+    ///
+    /// For now, only real `dict` values use mapping-copy semantics; other values
+    /// are interpreted as iterables of pairs.
+    pub fn init(vm: &mut VM<'_, '_, impl ResourceTracker>, args: ArgValues) -> RunResult<Value> {
+        let dict = Self::new();
+        let mut dict_guard = HeapGuard::new(dict, vm);
+
+        {
+            let (dict, vm) = dict_guard.as_parts_mut();
+            let (pos_iter, kwargs) = args.into_parts();
+            defer_drop_mut!(pos_iter, vm);
+            let mut kwargs_guard = HeapGuard::new(kwargs, vm);
+
+            if let Some(other_value) = pos_iter.next() {
+                let other_value_guard = HeapGuard::new(other_value, kwargs_guard.heap());
+                if pos_iter.len() != 0 {
+                    return Err(ExcType::type_error_at_most("dict", 1, pos_iter.len() + 1));
+                }
+                let other_value = other_value_guard.into_inner();
+                dict_merge_from_value(dict, other_value, kwargs_guard.heap())?;
+            }
+
+            let kwargs = kwargs_guard.into_inner();
+            dict_merge_from_kwargs(dict, kwargs, vm)?;
+        }
+
+        let dict = dict_guard.into_inner();
+        let heap_id = vm.heap.allocate(HeapData::Dict(dict))?;
+        Ok(Value::Ref(heap_id))
+    }
+
+    fn find_index_hash(
+        &self,
+        key: &Value,
+        vm: &mut VM<'_, '_, impl ResourceTracker>,
+    ) -> RunResult<(Option<usize>, u64)> {
+        let hash = key
+            .py_hash(vm.heap, vm.interns)?
+            .ok_or_else(|| ExcType::type_error_unhashable_dict_key(key.py_type(vm.heap)))?;
+
+        // Dict keys are typically shallow (strings, ints, tuples of primitives),
+        // so recursion errors are unlikely. If one occurs, treat it as "not equal" -
+        // the key lookup fails but doesn't crash.
+        let opt_index = self
+            .indices
+            .find(hash, |v| key.py_eq(&self.entries[*v].key, vm).unwrap_or(false))
+            .copied();
+        Ok((opt_index, hash))
+    }
+}
+
+/// Iterator over borrowed (key, value) pairs in a dict.
+pub(crate) struct DictIter<'a>(std::slice::Iter<'a, DictEntry>);
+
+impl<'a> Iterator for DictIter<'a> {
+    type Item = (&'a Value, &'a Value);
+    fn next(&mut self) -> Option<Self::Item> {
+        self.0.next().map(|e| (&e.key, &e.value))
+    }
+}
+
+impl<'a> IntoIterator for &'a Dict {
+    type Item = (&'a Value, &'a Value);
+    type IntoIter = DictIter<'a>;
+    fn into_iter(self) -> Self::IntoIter {
+        DictIter(self.entries.iter())
+    }
+}
+
+/// Iterator over owned (key, value) pairs from a consumed dict.
+pub(crate) struct DictIntoIter(std::vec::IntoIter<DictEntry>);
+
+impl Iterator for DictIntoIter {
+    type Item = (Value, Value);
+
+    fn next(&mut self) -> Option<Self::Item> {
+        self.0.next().map(|e| (e.key, e.value))
+    }
+
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        self.0.size_hint()
+    }
+}
+
+impl ExactSizeIterator for DictIntoIter {}
+
+impl IntoIterator for Dict {
+    type Item = (Value, Value);
+    type IntoIter = DictIntoIter;
+    fn into_iter(self) -> Self::IntoIter {
+        DictIntoIter(self.entries.into_iter())
+    }
+}
+
+impl PyTrait for Dict {
+    fn py_type(&self, _heap: &Heap<impl ResourceTracker>) -> Type {
+        Type::Dict
+    }
+
+    fn py_estimate_size(&self) -> usize {
+        // Dict size: struct overhead + entries (2 Values per entry for key+value)
+        std::mem::size_of::<Self>() + self.len() * 2 * std::mem::size_of::<Value>()
+    }
+
+    fn py_len(&self, _vm: &VM<'_, '_, impl ResourceTracker>) -> Option<usize> {
+        Some(self.len())
+    }
+
+    fn py_eq(&self, other: &Self, vm: &mut VM<'_, '_, impl ResourceTracker>) -> Result<bool, ResourceError> {
+        if self.len() != other.len() {
+            return Ok(false);
+        }
+
+        let token = vm.heap.incr_recursion_depth()?;
+        defer_drop!(token, vm);
+        for entry in &self.entries {
+            vm.heap.check_time()?;
+            if let Ok(Some(other_v)) = other.get(&entry.key, vm) {
+                if !entry.value.py_eq(other_v, vm)? {
+                    return Ok(false);
+                }
+            } else {
+                return Ok(false);
+            }
+        }
+        Ok(true)
+    }
+
+    fn py_dec_ref_ids(&mut self, stack: &mut Vec<HeapId>) {
+        // Skip iteration if no refs - major GC optimization for dicts of primitives
+        if !self.contains_refs {
+            return;
+        }
+        for entry in &mut self.entries {
+            if let Value::Ref(id) = &entry.key {
+                stack.push(*id);
+                #[cfg(feature = "ref-count-panic")]
+                entry.key.dec_ref_forget();
+            }
+            if let Value::Ref(id) = &entry.value {
+                stack.push(*id);
+                #[cfg(feature = "ref-count-panic")]
+                entry.value.dec_ref_forget();
+            }
+        }
+    }
+
+    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.is_empty() {
+            return f.write_str("{}");
+        }
+
+        let heap = &*vm.heap;
+        // Check depth limit before recursing
+        let Some(token) = heap.incr_recursion_depth_for_repr() else {
+            return f.write_str("{...}");
+        };
+        crate::defer_drop_immutable_heap!(token, heap);
+
+        f.write_char('{')?;
+        let mut first = true;
+        for entry in &self.entries {
+            if !first {
+                if heap.check_time().is_err() {
+                    f.write_str(", ...[timeout]")?;
+                    break;
+                }
+                f.write_str(", ")?;
+            }
+            first = false;
+            entry.key.py_repr_fmt(f, vm, heap_ids)?;
+            f.write_str(": ")?;
+            entry.value.py_repr_fmt(f, vm, heap_ids)?;
+        }
+        f.write_char('}')?;
+
+        Ok(())
+    }
+
+    fn py_getitem(&self, key: &Value, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Value> {
+        match self.get(key, vm)? {
+            Some(value) => Ok(value.clone_with_heap(vm)),
+            None => Err(ExcType::key_error(key, vm)),
+        }
+    }
+
+    fn py_setitem(&mut self, key: Value, value: Value, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<()> {
+        // Drop the old value if one was replaced
+        if let Some(old_value) = self.set(key, value, vm)? {
+            old_value.drop_with_heap(vm);
+        }
+        Ok(())
+    }
+
+    fn py_call_attr(
+        &mut self,
+        self_id: HeapId,
+        vm: &mut VM<'_, '_, impl ResourceTracker>,
+        attr: &EitherStr,
+        args: ArgValues,
+    ) -> RunResult<CallResult> {
+        let Some(method) = attr.static_string() else {
+            args.drop_with_heap(vm.heap);
+            return Err(ExcType::attribute_error(Type::Dict, attr.as_str(vm.interns)));
+        };
+
+        let value = match method {
+            StaticStrings::Get => {
+                // dict.get() accepts 1 or 2 arguments
+                let (key, default) = args.get_one_two_args("get", vm.heap)?;
+                defer_drop!(key, vm);
+                let default = default.unwrap_or(Value::None);
+                let mut default_guard = HeapGuard::new(default, vm);
+                let vm = default_guard.heap();
+                // Handle the lookup - may fail for unhashable keys
+                let value = match self.get(key, vm)? {
+                    Some(v) => v.clone_with_heap(vm),
+                    None => default_guard.into_inner(),
+                };
+                Ok(value)
+            }
+            StaticStrings::Keys => {
+                args.check_zero_args("dict.keys", vm.heap)?;
+                let view_id = vm.heap.allocate(HeapData::DictKeysView(DictKeysView::new(self_id)))?;
+                vm.heap.inc_ref(self_id);
+                Ok(Value::Ref(view_id))
+            }
+            StaticStrings::Values => {
+                args.check_zero_args("dict.values", vm.heap)?;
+                let view_id = vm
+                    .heap
+                    .allocate(HeapData::DictValuesView(DictValuesView::new(self_id)))?;
+                vm.heap.inc_ref(self_id);
+                Ok(Value::Ref(view_id))
+            }
+            StaticStrings::Items => {
+                args.check_zero_args("dict.items", vm.heap)?;
+                let view_id = vm.heap.allocate(HeapData::DictItemsView(DictItemsView::new(self_id)))?;
+                vm.heap.inc_ref(self_id);
+                Ok(Value::Ref(view_id))
+            }
+            StaticStrings::Pop => {
+                // dict.pop() accepts 1 or 2 arguments (key, optional default)
+                let (key, default) = args.get_one_two_args("pop", vm.heap)?;
+                defer_drop!(key, vm);
+                let mut default_guard = HeapGuard::new(default, vm);
+                let vm = default_guard.heap();
+                if let Some((old_key, value)) = self.pop(key, vm)? {
+                    // Drop the old key - we don't need it
+                    old_key.drop_with_heap(vm);
+                    Ok(value)
+                } else {
+                    let (default, vm) = default_guard.into_parts();
+                    // No matching key - return default if provided, else KeyError
+                    if let Some(d) = default {
+                        Ok(d)
+                    } else {
+                        Err(ExcType::key_error(key, vm))
+                    }
+                }
+            }
+            StaticStrings::Clear => {
+                args.check_zero_args("dict.clear", vm.heap)?;
+                dict_clear(self, vm.heap);
+                Ok(Value::None)
+            }
+            StaticStrings::Copy => {
+                args.check_zero_args("dict.copy", vm.heap)?;
+                dict_copy(self, vm)
+            }
+            StaticStrings::Update => dict_update(self, args, vm),
+            StaticStrings::Setdefault => dict_setdefault(self, args, vm),
+            StaticStrings::Popitem => {
+                args.check_zero_args("dict.popitem", vm.heap)?;
+                dict_popitem(self, vm.heap)
+            }
+            // fromkeys is a classmethod but also accessible on instances
+            StaticStrings::Fromkeys => dict_fromkeys(args, vm),
+            _ => {
+                args.drop_with_heap(vm.heap);
+                return Err(ExcType::attribute_error(Type::Dict, attr.as_str(vm.interns)));
+            }
+        };
+        value.map(CallResult::Value)
+    }
+}
+
+impl DropWithHeap for Dict {
+    fn drop_with_heap<H: ContainsHeap>(self, heap: &mut H) {
+        self.entries.drop_with_heap(heap);
+    }
+}
+
+impl DropWithHeap for DictEntry {
+    fn drop_with_heap<H: ContainsHeap>(self, heap: &mut H) {
+        self.key.drop_with_heap(heap);
+        self.value.drop_with_heap(heap);
+    }
+}
+
+/// Implements Python's `dict.clear()` method.
+///
+/// Removes all items from the dict.
+fn dict_clear(dict: &mut Dict, heap: &mut Heap<impl ResourceTracker>) {
+    dict.entries.drain(..).drop_with_heap(heap);
+    dict.indices.clear();
+    // Note: contains_refs stays true even if all refs removed, per conservative GC strategy
+}
+
+/// Implements Python's `dict.copy()` method.
+///
+/// Returns a shallow copy of the dict.
+fn dict_copy(dict: &Dict, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Value> {
+    // Copy all key-value pairs (incrementing refcounts)
+    let pairs: Vec<(Value, Value)> = dict
+        .iter()
+        .map(|(k, v)| (k.clone_with_heap(vm), v.clone_with_heap(vm)))
+        .collect();
+
+    let new_dict = Dict::from_pairs(pairs, vm)?;
+    let heap_id = vm.heap.allocate(HeapData::Dict(new_dict))?;
+    Ok(Value::Ref(heap_id))
+}
+
+/// Implements Python's `dict.update([other], **kwargs)` method.
+///
+/// Updates the dict with key-value pairs from `other` and/or `kwargs`.
+/// If `other` is a dict, copies its key-value pairs.
+/// If `other` is an iterable, expects pairs of (key, value).
+/// Keyword arguments are also added to the dict.
+fn dict_update(dict: &mut Dict, args: ArgValues, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Value> {
+    let (pos_iter, kwargs) = args.into_parts();
+    defer_drop_mut!(pos_iter, vm);
+    let mut kwargs_guard = HeapGuard::new(kwargs, vm);
+
+    if let Some(other_value) = pos_iter.next() {
+        let other_value_guard = HeapGuard::new(other_value, kwargs_guard.heap());
+        if pos_iter.len() != 0 {
+            return Err(ExcType::type_error_at_most("dict.update", 1, pos_iter.len() + 1));
+        }
+        let other_value = other_value_guard.into_inner();
+        dict_merge_from_value(dict, other_value, kwargs_guard.heap())?;
+    }
+
+    let kwargs = kwargs_guard.into_inner();
+    dict_merge_from_kwargs(dict, kwargs, vm)?;
+    Ok(Value::None)
+}
+
+/// Merges key-value pairs from either a dict or an iterable of 2-item pairs.
+///
+/// This is shared between `dict()` construction and `dict.update()` so both
+/// entry points follow identical positional-source semantics.
+fn dict_merge_from_value(
+    dict: &mut Dict,
+    other_value: Value,
+    vm: &mut VM<'_, '_, impl ResourceTracker>,
+) -> RunResult<()> {
+    let mut other_value_guard = HeapGuard::new(other_value, vm);
+    {
+        let (other_value, vm) = other_value_guard.as_parts();
+        if let Value::Ref(id) = other_value
+            && let HeapData::Dict(src_dict) = vm.heap.get(*id)
+        {
+            // Clone key-value pairs from the source dict.
+            let pairs: Vec<(Value, Value)> = src_dict
+                .iter()
+                .map(|(k, v)| (k.clone_with_heap(vm.heap), v.clone_with_heap(vm.heap)))
+                .collect();
+
+            // Apply pairs into the target dict.
+            for (key, value) in pairs {
+                let old_value = dict.set(key, value, vm)?;
+                old_value.drop_with_heap(vm.heap);
+            }
+            return Ok(());
+        }
+    }
+
+    // Non-dict values are interpreted as iterable-of-pairs.
+    let other_value = other_value_guard.into_inner();
+    dict_merge_from_iterable_pairs(dict, other_value, vm)
+}
+
+/// Merges key-value pairs from an iterable of 2-item iterables.
+///
+/// Each item from `iterable` is treated as `(key, value)`. Items with length 0, 1,
+/// or greater than 2 raise the same TypeError messages used by `dict.update()`.
+fn dict_merge_from_iterable_pairs(
+    dict: &mut Dict,
+    iterable: Value,
+    vm: &mut VM<'_, '_, impl ResourceTracker>,
+) -> RunResult<()> {
+    let iter = MontyIter::new(iterable, vm)?;
+    defer_drop_mut!(iter, vm);
+
+    while let Some(item) = iter.for_next(vm)? {
+        // Each item should be a pair (iterable of 2 elements).
+        let pair_iter = MontyIter::new(item, vm)?;
+        defer_drop_mut!(pair_iter, vm);
+
+        let Some(key) = pair_iter.for_next(vm)? else {
+            return Err(ExcType::type_error(
+                "dictionary update sequence element has length 0; 2 is required",
+            ));
+        };
+        let mut key_guard = HeapGuard::new(key, vm);
+
+        let Some(value) = pair_iter.for_next(key_guard.heap())? else {
+            return Err(ExcType::type_error(
+                "dictionary update sequence element has length 1; 2 is required",
+            ));
+        };
+        let mut value_guard = HeapGuard::new(value, key_guard.heap());
+
+        if let Some(extra) = pair_iter.for_next(value_guard.heap())? {
+            extra.drop_with_heap(value_guard.heap());
+            return Err(ExcType::type_error(
+                "dictionary update sequence element has length > 2; 2 is required",
+            ));
+        }
+
+        let value = value_guard.into_inner();
+        let key = key_guard.into_inner();
+
+        if let Some(old_value) = dict.set(key, value, vm)? {
+            old_value.drop_with_heap(vm);
+        }
+    }
+
+    Ok(())
+}
+
+/// Merges keyword arguments into a dict.
+///
+/// This helper drains `kwargs` safely on error so all values are dropped
+/// correctly, then inserts each key-value pair into `dict`.
+fn dict_merge_from_kwargs(
+    dict: &mut Dict,
+    kwargs: KwargsValues,
+    vm: &mut VM<'_, '_, impl ResourceTracker>,
+) -> RunResult<()> {
+    let kwargs_iter = kwargs.into_iter();
+    defer_drop_mut!(kwargs_iter, vm);
+    for (key, value) in kwargs_iter {
+        let old_value = dict.set(key, value, vm)?;
+        old_value.drop_with_heap(vm);
+    }
+    Ok(())
+}
+
+/// Implements Python's `dict.setdefault(key[, default])` method.
+///
+/// If key is in the dict, return its value.
+/// If not, insert key with a value of default (or None) and return default.
+fn dict_setdefault(dict: &mut Dict, args: ArgValues, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Value> {
+    let (key, default) = args.get_one_two_args("setdefault", vm.heap)?;
+    let default = default.unwrap_or(Value::None);
+    let mut key_guard = HeapGuard::new(key, vm);
+    let (key, vm) = key_guard.as_parts();
+
+    if let Some(existing) = dict.get(key, vm)? {
+        // Key exists - return its value (cloned)
+        let value = existing.clone_with_heap(vm);
+        default.drop_with_heap(vm);
+        Ok(value)
+    } else {
+        // Key doesn't exist - insert default and return it (cloned before insertion)
+        let return_value = default.clone_with_heap(vm);
+        let (key, vm) = key_guard.into_parts();
+        if let Some(old_value) = dict.set(key, default, vm)? {
+            // This shouldn't happen since we checked, but handle it anyway
+            old_value.drop_with_heap(vm);
+        }
+        Ok(return_value)
+    }
+}
+
+/// Implements Python's `dict.popitem()` method.
+///
+/// Removes and returns the last inserted key-value pair as a tuple.
+/// Raises KeyError if the dict is empty.
+fn dict_popitem(dict: &mut Dict, heap: &mut Heap<impl ResourceTracker>) -> RunResult<Value> {
+    if dict.is_empty() {
+        return Err(ExcType::key_error_popitem_empty_dict());
+    }
+
+    // Remove the last entry (LIFO order)
+    let entry = dict.entries.pop().expect("dict is not empty");
+
+    // Remove from indices - need to find the entry with this index
+    // Since we removed the last entry, we need to clear and rebuild indices
+    // (This is simpler than trying to find and remove the specific hash entry)
+    // TODO: This O(n) rebuild could be optimized by finding and removing the
+    // specific hash entry directly from the hashbrown table.
+    dict.indices.clear();
+    for (idx, e) in dict.entries.iter().enumerate() {
+        dict.indices.insert_unique(e.hash, idx, |&i| dict.entries[i].hash);
+    }
+
+    // Create tuple (key, value)
+    Ok(allocate_tuple(smallvec![entry.key, entry.value], heap)?)
+}
+
+// Custom serde implementation for Dict.
+// Serializes entries and contains_refs; rebuilds the indices hash table on deserialize.
+impl serde::Serialize for Dict {
+    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        use serde::ser::SerializeStruct;
+        let mut state = serializer.serialize_struct("Dict", 2)?;
+        state.serialize_field("entries", &self.entries)?;
+        state.serialize_field("contains_refs", &self.contains_refs)?;
+        state.end()
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for Dict {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        #[derive(serde::Deserialize)]
+        struct DictFields {
+            entries: Vec<DictEntry>,
+            contains_refs: bool,
+        }
+        let fields = DictFields::deserialize(deserializer)?;
+        // Rebuild the indices hash table from the entries
+        let mut indices = HashTable::with_capacity(fields.entries.len());
+        for (idx, entry) in fields.entries.iter().enumerate() {
+            indices.insert_unique(entry.hash, idx, |&i| fields.entries[i].hash);
+        }
+        Ok(Self {
+            indices,
+            entries: fields.entries,
+            contains_refs: fields.contains_refs,
+        })
+    }
+}
+
+/// Implements Python's `dict.fromkeys(iterable[, value])` classmethod.
+///
+/// Creates a new dictionary with keys from `iterable` and all values set to `value`
+/// (default: None).
+///
+/// This is a classmethod that can be called directly on the dict type:
+/// ```python
+/// dict.fromkeys(['a', 'b', 'c'])  # {'a': None, 'b': None, 'c': None}
+/// dict.fromkeys(['a', 'b'], 0)    # {'a': 0, 'b': 0}
+/// ```
+pub fn dict_fromkeys(args: ArgValues, vm: &mut VM<'_, '_, impl ResourceTracker>) -> RunResult<Value> {
+    let (iterable, default) = args.get_one_two_args("dict.fromkeys", vm.heap)?;
+    let default = default.unwrap_or(Value::None);
+    defer_drop!(default, vm);
+
+    let iter = MontyIter::new(iterable, vm)?;
+    defer_drop_mut!(iter, vm);
+
+    let dict = Dict::new();
+    let mut dict_guard = HeapGuard::new(dict, vm);
+
+    {
+        let (dict, vm) = dict_guard.as_parts_mut();
+
+        while let Some(key) = iter.for_next(vm)? {
+            let old_value = dict.set(key, default.clone_with_heap(vm), vm)?;
+            old_value.drop_with_heap(vm);
+        }
+    }
+
+    let dict = dict_guard.into_inner();
+    let heap_id = vm.heap.allocate(HeapData::Dict(dict))?;
+    Ok(Value::Ref(heap_id))
+}