Support user iteration protocol, frozenset, and attribute builtins

Author: kidoz

src/DotPython.Runtime.Managed/Execution/ManagedObjectProtocols.cs

@@ -23,6 +23,15 @@ internal enum PythonRichComparison
     GreaterThanOrEqual,
 }
 
+/// <summary>
+/// Resolves a user-defined instance into an iterator by running its `__iter__` on the
+/// owning VM; the static protocol layer cannot execute frames itself.
+/// </summary>
+internal delegate PythonIteratorValue UserIterationDispatcher(
+    PythonManagedObjectValue instance,
+    TextSpan span
+);
+
 /// <summary>
 /// Central protocol dispatch for managed values exposed through a native-compatibility boundary.
 /// </summary>
@@ -139,7 +148,7 @@ .. template.Interpolations.Select(interpolation => interpolation.Value),
             case PythonTemplateValue:
                 throw Fault(
                     "DPY4023",
-                    $"'Template' object has no attribute '{name}'.",
+                    $"'Template' object has no attribute '{name}'",
                     span,
                     "AttributeError"
                 );
@@ -172,7 +181,7 @@ .. template.Interpolations.Select(interpolation => interpolation.Value),
                     ),
                     _ => throw Fault(
                         "DPY4023",
-                        $"'{generator.TypeName}' object has no attribute '{name}'.",
+                        $"'{generator.TypeName}' object has no attribute '{name}'",
                         span,
                         "AttributeError"
                     ),
@@ -188,7 +197,7 @@ .. template.Interpolations.Select(interpolation => interpolation.Value),
                     "format_spec" => new PythonTextValue(interpolation.FormatSpecification),
                     _ => throw Fault(
                         "DPY4023",
-                        $"'Interpolation' object has no attribute '{name}'.",
+                        $"'Interpolation' object has no attribute '{name}'",
                         span,
                         "AttributeError"
                     ),
@@ -201,7 +210,7 @@ .. template.Interpolations.Select(interpolation => interpolation.Value),
 
                 throw Fault(
                     "DPY4023",
-                    $"'{GetTypeName(builtin)}' object has no attribute '{name}'.",
+                    $"'{GetTypeName(builtin)}' object has no attribute '{name}'",
                     span,
                     "AttributeError"
                 );
@@ -470,13 +479,22 @@ private static PythonNoneValue CloseGenerator(PythonGeneratorValue generator, Te
         }
     }
 
-    internal static PythonIteratorValue GetIterator(PythonValue value, TextSpan span = default)
+    internal static PythonIteratorValue GetIterator(
+        PythonValue value,
+        TextSpan span = default,
+        UserIterationDispatcher? userIteration = null
+    )
     {
         if (value is PythonIteratorValue iterator)
         {
             return iterator;
         }
 
+        if (value is PythonManagedObjectValue instance && userIteration is not null)
+        {
+            return userIteration(instance, span);
+        }
+
         if (value is PythonGeneratorValue generatorValue)
         {
             if (generatorValue.IsCoroutine)
@@ -525,7 +543,12 @@ or PythonSetValue
             )
         )
         {
-            throw Fault("DPY4015", "This value is not iterable.", span, "TypeError");
+            throw Fault(
+                "DPY4015",
+                $"'{GetTypeName(value)}' object is not iterable",
+                span,
+                "TypeError"
+            );
         }
 
         return new PythonIteratorValue(
@@ -672,6 +695,17 @@ internal static bool TryGetNext(
                 }
 
                 break;
+            case PythonUserIteratorSourceValue userSource:
+            {
+                var step = userSource.MoveNext();
+                if (step.HasValue)
+                {
+                    value = step.Value;
+                    return true;
+                }
+
+                break;
+            }
         }
 
         value = PythonNoneValue.Instance;
@@ -857,7 +891,12 @@ internal static void SetTupleItem(
         tuple.Elements[index] = value;
     }
 
-    internal static bool Contains(PythonValue container, PythonValue item, TextSpan span = default)
+    internal static bool Contains(
+        PythonValue container,
+        PythonValue item,
+        TextSpan span = default,
+        UserIterationDispatcher? userIteration = null
+    )
     {
         ArgumentNullException.ThrowIfNull(container);
         ArgumentNullException.ThrowIfNull(item);
@@ -881,7 +920,7 @@ internal static bool Contains(PythonValue container, PythonValue item, TextSpan
             return TryFindDictionaryItem(dictionary, item, out _);
         }
 
-        var iterator = GetIterator(container, span);
+        var iterator = GetIterator(container, span, userIteration);
         while (TryGetNext(iterator, out var candidate, span))
         {
             if (AreEqual(candidate, item))
@@ -1058,9 +1097,14 @@ when TryFindDictionaryItem(dictionary, index, out var item):
         }
     }
 
-    internal static void ExtendList(PythonListValue list, PythonValue iterable, TextSpan span)
+    internal static void ExtendList(
+        PythonListValue list,
+        PythonValue iterable,
+        TextSpan span,
+        UserIterationDispatcher? userIteration = null
+    )
     {
-        var values = MaterializeValues(iterable, span);
+        var values = MaterializeValues(iterable, span, userIteration);
         list.Elements.AddRange(values);
     }
 
@@ -1094,7 +1138,12 @@ internal static void AddToSet(PythonSetValue set, PythonValue value, TextSpan sp
     {
         if (!IsHashable(value))
         {
-            throw Fault("DPY4014", $"Unhashable type: '{GetTypeName(value)}'.", span, "TypeError");
+            throw Fault(
+                "DPY4014",
+                $"cannot use '{GetTypeName(value)}' as a set element (unhashable type: '{GetTypeName(value)}')",
+                span,
+                "TypeError"
+            );
         }
 
         foreach (var element in set.Elements)
@@ -1119,10 +1168,14 @@ internal static PythonSetValue CreateSet(IReadOnlyList<PythonValue> values, Text
         return set;
     }
 
-    internal static List<PythonValue> MaterializeValues(PythonValue iterable, TextSpan span)
+    internal static List<PythonValue> MaterializeValues(
+        PythonValue iterable,
+        TextSpan span,
+        UserIterationDispatcher? userIteration = null
+    )
     {
         var values = new List<PythonValue>();
-        var iterator = GetIterator(iterable, span);
+        var iterator = GetIterator(iterable, span, userIteration);
         while (TryGetNext(iterator, out var value, span))
         {
             values.Add(value);
@@ -1250,16 +1303,29 @@ internal static int GetPythonHash(PythonValue value, TextSpan span = default)
                 RuntimeHelpers.GetHashCode(method.Function)
             ),
             PythonModuleValue module => RuntimeHelpers.GetHashCode(module),
-            PythonListValue or PythonDictionaryValue => throw Fault(
+            PythonSetValue { IsFrozen: true } frozen => GetFrozenSetHash(frozen, span),
+            PythonListValue or PythonDictionaryValue or PythonSetValue => throw Fault(
                 "DPY4014",
-                "This managed value is not hashable.",
+                $"unhashable type: '{GetTypeName(value)}'",
                 span,
                 "TypeError"
             ),
             _ => RuntimeHelpers.GetHashCode(value),
         };
     }
 
+    private static int GetFrozenSetHash(PythonSetValue frozen, TextSpan span)
+    {
+        // Order-insensitive combination so equal frozensets hash equally.
+        var hash = 0;
+        foreach (var element in frozen.Elements)
+        {
+            hash ^= GetPythonHash(element, span);
+        }
+
+        return HashCode.Combine(hash, frozen.Elements.Count);
+    }
+
     internal static byte[] GetBytes(PythonByteSequenceValue value)
     {
         ArgumentNullException.ThrowIfNull(value);
@@ -1286,7 +1352,7 @@ internal static string GetTypeName(PythonValue value) =>
             PythonTupleValue => "tuple",
             PythonDictionaryValue => "dict",
             PythonSliceValue => "slice",
-            PythonSetValue => "set",
+            PythonSetValue set => set.IsFrozen ? "frozenset" : "set",
             PythonDictionaryViewValue view => view.Kind,
             PythonRangeValue => "range",
             PythonEnumerateSourceValue => "enumerate",
@@ -1426,7 +1492,12 @@ TextSpan span
     {
         if (!IsHashable(key))
         {
-            throw Fault("DPY4014", "The dictionary key is not hashable.", span, "TypeError");
+            throw Fault(
+                "DPY4014",
+                $"cannot use '{GetTypeName(key)}' as a dict key (unhashable type: '{GetTypeName(key)}')",
+                span,
+                "TypeError"
+            );
         }
 
         if (TryFindDictionaryItem(dictionary, key, out var item))
@@ -1461,7 +1532,8 @@ out PythonDictionaryItemValue item
     internal static bool IsHashable(PythonValue value) =>
         value switch
         {
-            PythonListValue or PythonDictionaryValue or PythonSetValue => false,
+            PythonSetValue set => set.IsFrozen,
+            PythonListValue or PythonDictionaryValue => false,
             PythonTupleValue tuple => tuple.Elements.All(IsHashable),
             _ => true,
         };
@@ -1747,11 +1819,11 @@ private static Complex ToComplex(PythonValue value) =>
             _ => throw new ArgumentOutOfRangeException(nameof(value)),
         };
 
-    private static PythonRuntimeException MissingAttribute(
+    internal static PythonRuntimeException MissingAttribute(
         string typeName,
         string name,
         TextSpan span
-    ) => Fault("DPY4022", $"'{typeName}' has no attribute '{name}'.", span, "AttributeError");
+    ) => Fault("DPY4022", $"'{typeName}' object has no attribute '{name}'", span, "AttributeError");
 
     internal static PythonRuntimeException Fault(
         string code,

src/DotPython.Runtime.Managed/Execution/PythonBuiltinMethods.cs

@@ -553,6 +553,18 @@ out var item
         ["copy"] = Set("copy", 0, 0, (set, _) => new PythonSetValue([.. set.Elements])),
     };
 
+    private static readonly Dictionary<string, PythonProtocolFunctionValue> FrozenSetMethods = new(
+        StringComparer.Ordinal
+    )
+    {
+        ["copy"] = Set(
+            "copy",
+            0,
+            0,
+            (set, _) => new PythonSetValue([.. set.Elements]) { IsFrozen = true }
+        ),
+    };
+
     internal static bool TryGet(
         PythonValue target,
         string name,
@@ -565,6 +577,7 @@ out PythonProtocolFunctionValue method
             PythonListValue => ListMethods,
             PythonDictionaryValue => DictionaryMethods,
             PythonTupleValue => TupleMethods,
+            PythonSetValue { IsFrozen: true } => FrozenSetMethods,
             PythonSetValue => SetMethods,
             _ => null,
         };

src/DotPython.Runtime.Managed/Execution/PythonBuiltinTypes.cs

@@ -17,11 +17,15 @@ internal static class PythonBuiltinTypes
     internal static readonly PythonBuiltinTypeValue Int = new("int", ConstructInt);
     internal static readonly PythonBuiltinTypeValue List = new("list", ConstructList);
     internal static readonly PythonBuiltinTypeValue Set = new("set", ConstructSet);
+    internal static readonly PythonBuiltinTypeValue Frozenset = new(
+        "frozenset",
+        ConstructFrozenset
+    );
     internal static readonly PythonBuiltinTypeValue Str = new("str", ConstructStr);
     internal static readonly PythonBuiltinTypeValue Tuple = new("tuple", ConstructTuple);
 
     internal static IEnumerable<PythonBuiltinTypeValue> All =>
-        [Bool, Dict, Float, Int, List, Set, Str, Tuple];
+        [Bool, Dict, Float, Frozenset, Int, List, Set, Str, Tuple];
 
     internal static PythonBuiltinTypeValue CreateOpaque(string name) =>
         new(
@@ -45,7 +49,8 @@ internal static bool IsInstance(PythonValue value, PythonBuiltinTypeValue type)
             "list" => value is PythonListValue,
             "tuple" => value is PythonTupleValue,
             "dict" => value is PythonDictionaryValue,
-            "set" => value is PythonSetValue,
+            "set" => value is PythonSetValue { IsFrozen: false },
+            "frozenset" => value is PythonSetValue { IsFrozen: true },
             _ => false,
         };
 
@@ -200,6 +205,22 @@ private static PythonSetValue ConstructSet(IReadOnlyList<PythonValue> arguments,
             );
     }
 
+    private static PythonSetValue ConstructFrozenset(
+        IReadOnlyList<PythonValue> arguments,
+        TextSpan span
+    )
+    {
+        RequireArguments("frozenset", arguments, 0, 1, span);
+        var deduplicated =
+            arguments.Count == 0
+                ? new PythonSetValue([])
+                : ManagedObjectProtocols.CreateSet(
+                    ManagedObjectProtocols.MaterializeValues(arguments[0], span),
+                    span
+                );
+        return new PythonSetValue(deduplicated.Elements) { IsFrozen = true };
+    }
+
     private static PythonTextValue ConstructStr(IReadOnlyList<PythonValue> arguments, TextSpan span)
     {
         RequireArguments("str", arguments, 0, 1, span);

src/DotPython.Runtime.Managed/Execution/PythonValue.cs

@@ -597,23 +597,28 @@ PythonIteratorValue Inner
 
 internal sealed record PythonSetValue(List<PythonValue> Elements) : PythonValue
 {
+    /// <summary>Whether this value is a `frozenset` (immutable, hashable) rather than a `set`.</summary>
+    internal bool IsFrozen { get; init; }
+
     internal override string ToDisplayString()
     {
         if (Elements.Count == 0)
         {
-            return "set()";
+            return IsFrozen ? "frozenset()" : "set()";
         }
 
         if (!PythonRepresentationGuard.TryEnter(this))
         {
-            return "{...}";
+            return IsFrozen ? "frozenset({...})" : "{...}";
         }
 
         try
         {
-            return "{"
+            var elements =
+                "{"
                 + string.Join(", ", Elements.Select(element => element.ToRepresentationString()))
                 + "}";
+            return IsFrozen ? $"frozenset({elements})" : elements;
         }
         finally
         {
@@ -622,6 +627,17 @@ internal override string ToDisplayString()
     }
 }
 
+/// <summary>
+/// A lazy iteration source over a user-defined iterator: `MoveNext` captures the VM
+/// and the bound `__next__`, converting a raised StopIteration into exhaustion.
+/// </summary>
+internal sealed record PythonUserIteratorSourceValue(
+    Func<(bool HasValue, PythonValue Value)> MoveNext
+) : PythonValue
+{
+    internal override string ToDisplayString() => "<iterator>";
+}
+
 internal sealed record PythonSliceValue(PythonValue Start, PythonValue Stop, PythonValue Step)
     : PythonValue
 {