amb: standardize MonadicList constructor, register as Sequence

MonadicList.__init__ now takes a single iterable (like list/tuple),
replacing the non-standard *elts variadic form. This makes it a
well-behaved Sequence — registered as Iterable, Sized, Sequence.
Added __reversed__, __contains__, index, count for full Sequence
compliance. Removed nil sentinel dependency (empty constructor
suffices).

Also: Assignment renamed to Choice, internal env to Scope (previous
commit); D13 added to TODO_DEFERRED.md (teaching-friendly monads).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Technologicat

TODO_DEFERRED.md

@@ -1,6 +1,6 @@
 # Deferred Issues
 
-Next unused item code: D13
+Next unused item code: D14
 
 - **D5**: `dispatch.py` — moved to GitHub issue #99. Dispatch-layer improvements for parametric ABCs (warn/error on indistinguishable multimethods). Typecheck-layer part resolved.
 
@@ -41,3 +41,6 @@ Next unused item code: D13
   **When to actually do it**: only if tier 1 coverage turns out to miss something important (a regression hits prod that tier 1 would not have caught). The in-thread server + scripted client approach already exercises most of the protocol surface; tier 2 is primarily a safety net for terminal-semantics and signal-path bugs. Until one of those bites, tier 1 is the main win. (Added 2026-04-15, alongside the tier 1 bring-up.)
 
 
+- **D13: Teaching-friendly monad abstractions**: Port the monad hacks from https://github.com/Technologicat/python-3-scicomp-intro/tree/master/examples (monads.py) into unpythonic. `MonadicList` already exists in `amb.py` as precedent; the teaching examples include additional monad abstractions that could be generally useful. Some overlap with OSlash, but unpythonic already duplicates stdlib/third-party functionality where it adds value in its own voice (conditions/restarts, fold/scan suite). (Noted 2026-04-16.)
+
+

unpythonic/amb.py

@@ -33,11 +33,10 @@
 __all__ = ["forall", "choice", "insist", "deny"]
 
 from collections import namedtuple
-from collections.abc import Callable, Container, Iterable, Iterator, Sized
+from collections.abc import Callable, Iterable, Iterator, Sequence, Sized
 from typing import Any
 
 from .arity import arity_includes, UnknownArity
-from .llist import nil  # we need a sentinel, let's recycle the existing one
 
 Choice = namedtuple("Choice", "k v")
 
@@ -219,22 +218,20 @@ def monadify(value: Any, unpack: bool = True) -> "MonadicList":
             return MonadicList.from_iterable(value)
         except TypeError:
             pass  # fall through
-    return MonadicList(value)  # unit(MonadicList, value)
+    return MonadicList((value,))  # unit
 
 class MonadicList:  # TODO: This if anything is **the** place to use @typed.
     """A monadic list."""
-    def __init__(self, *elts: Any) -> None:
-        """The unit operator. Lift value(s) into a MonadicList.
+    def __init__(self, iterable: Iterable = ()) -> None:
+        """Construct a MonadicList from an iterable.
 
-        *elts: a or [a]
+        iterable: Iterable[a]
         returns: M a
+
+        Like ``list`` and ``tuple``, accepts a single iterable argument.
+        Use ``MonadicList((value,))`` for a singleton (the unit operator).
         """
-        # Accept the sentinel nil as a special **item** that, when passed to
-        # the MonadicList constructor, produces an empty list.
-        if len(elts) == 1 and elts[0] is nil:
-            self.x = ()
-        else:
-            self.x = elts
+        self.x = tuple(iterable)
 
     def __rshift__(self, f: Callable) -> "MonadicList":
         """Monadic bind; standard notation ">>=" in Haskell.
@@ -283,13 +280,12 @@ def guard(cls, b: Any) -> "MonadicList":
           - Use `.then(...)` just after the `guard` to discard the dummy, and replace with
             the actual output you want. The value (that passed the guard) from the original
             `MonadicList` is still live in the current scope.
-              - If you just want to filter, just `MonadicList(x)` it (recall that here the
-                constructor stands for the `unit` operator).
+              - If you just want to filter, just `MonadicList((x,))` it (the unit operator).
           - When an input doesn't pass the guard, the blank output from `guard` automatically
             cancels the rest of that branch of the computation.
         """
         if b:
-            return cls(True)  # MonadicList with one element; value not intended to be actually used.
+            return cls((True,))  # MonadicList with one element; value not intended to be actually used.
         return cls()  # 0-element MonadicList; short-circuit this branch of the computation.
 
     # Sequence ABC interface.
@@ -334,15 +330,12 @@ def from_iterable(cls, iterable: Iterable) -> "MonadicList":
         Eager; the input iterable will be iterated over in its entirety
         to produce the list. If it is consumable, it will be consumed.
         """
-        try:
-            return cls(*iterable)
-        except TypeError:  # maybe a generator; try forcing it before giving up.
-            return cls(*tuple(iterable))
+        return cls(iterable)
 
     def copy(self) -> "MonadicList":
         """Return a copy of this MonadicList."""
         cls = self.__class__
-        return cls(*self.x)
+        return cls(self.x)
 
     @classmethod
     def lift(cls, f: Callable) -> Callable:
@@ -351,7 +344,7 @@ def lift(cls, f: Callable) -> Callable:
         f: a -> b
         returns: a -> M b
         """
-        return lambda x: cls(f(x))
+        return lambda x: cls((f(x),))
 
     def fmap(self, f: Callable) -> "MonadicList":
         """The map operator.
@@ -381,9 +374,8 @@ def deny(v: Any) -> Any:
     return insist(not v)
 
 # register virtual base classes
-# Not registering as Sequence: mogrify (in unpythonic.collections) expects
-# Sequence constructors to accept a single iterable, but MonadicList uses *elts.
-for _abscls in (Container, Iterable, Sized):
+# register virtual base classes
+for _abscls in (Iterable, Sized, Sequence):
     _abscls.register(MonadicList)
 del _abscls
 

unpythonic/tests/test_amb.py

@@ -4,62 +4,62 @@
 from ..test.fixtures import session, testset
 
 from ..amb import (forall, choice, insist, deny, ok, fail,
-                   Choice, MonadicList, nil)
+                   Choice, MonadicList)
 
 def runtests():
     with testset("MonadicList (internal utility)"):
-        m = MonadicList(1, 2, 3)
+        m = MonadicList([1, 2, 3])
         test[tuple(m) == (1, 2, 3)]
         test[len(m) == 3]
         test[m[0] == 1 and m[1] == 2 and m[2] == 3]
 
-        m = MonadicList(nil)  # special *item* that produces an empty *list*
+        m = MonadicList()  # empty
         test[tuple(m) == ()]
 
         # Monadic bind (for MonadicList, it's flatmap).
         # This also tests fmap and join.
-        m = MonadicList(1, 2, 3)
-        f = lambda a: MonadicList(a, 10 * a)  # a -> M b
+        m = MonadicList([1, 2, 3])
+        f = lambda a: MonadicList([a, 10 * a])  # a -> M b
         test[tuple(m >> f) == (1, 10, 2, 20, 3, 30)]
 
         # .then(...): discard current value, replace by given value.
         # The new value must be wrapped in MonadicList.
-        m = MonadicList(1, 2, 3)
-        const = MonadicList(42)  # M b
+        m = MonadicList([1, 2, 3])
+        const = MonadicList((42,))  # M b (singleton)
         test[tuple(m.then(const)) == (42, 42, 42)]  # one 42 for each element of m
 
         test_raises[TypeError, m.then(f)]  # expected a MonadicList, got a function
 
-        m1 = MonadicList(1, 2)
-        m2 = MonadicList(3, 4, 5)
+        m1 = MonadicList([1, 2])
+        m2 = MonadicList([3, 4, 5])
         test[m1 == m1]
         test[the[m2] != the[m1]]
 
-        m1 = MonadicList(1, 2)
-        m2 = MonadicList(3, 4)
-        test[m1 + m2 == MonadicList(1, 2, 3, 4)]
+        m1 = MonadicList([1, 2])
+        m2 = MonadicList([3, 4])
+        test[m1 + m2 == MonadicList([1, 2, 3, 4])]
 
-        m1 = MonadicList(1, 2)
+        m1 = MonadicList([1, 2])
         notamonadiclist = (3, 4)
         test_raises[TypeError, m1 + notamonadiclist]
 
-        test[MonadicList.from_iterable(range(3)) == MonadicList(0, 1, 2)]
+        test[MonadicList.from_iterable(range(3)) == MonadicList([0, 1, 2])]
 
-        m1 = MonadicList(1, 2, 3)
+        m1 = MonadicList([1, 2, 3])
         m2 = m1.copy()
         test[the[m2] is not the[m1] and m2 == m1]
 
         double = lambda x: 2 * x
-        m = MonadicList(1, 2, 3)
+        m = MonadicList([1, 2, 3])
         test[tuple(m >> MonadicList.lift(double)) == (2, 4, 6)]
 
-        m = MonadicList(1, 2, 3)
+        m = MonadicList([1, 2, 3])
         test_raises[TypeError, m.join()]  # join() flattens a nested list, which m isn't
 
         # Usage example for `guard`
-        m = MonadicList(1, 2, 3)
+        m = MonadicList([1, 2, 3])
         test[tuple(m >> (lambda x: MonadicList.guard(x % 2 == 1)
-                                              .then(MonadicList(x)))) == (1, 3)]
+                                          .then(MonadicList((x,))))) == (1, 3)]
 
     with testset("basic usage"):
         test[forall(choice(x=range(5)),
@@ -114,7 +114,7 @@ def runtests():
     with testset("error cases"):
         test_raises[ValueError, choice(a=1, b=2)]  # choice() takes only one binding
 
-        # To trigger this corner case, we must manually create an `Choice`
+        # To trigger this corner case, we must manually create a `Choice`
         # that has an invalid name - in normal use, `choice()` protects against
         # that by its syntax, since the name of a kwarg must be a valid identifier.
         invalid_name = "∀δ>0∃ε>0:f(x+δ)-f(x)<ε"