D13: Monads subpackage + monadic_do macro

Port seven classical monads from the python-opetus-2017 teaching code
into `unpythonic.monads`: Identity, Maybe, Either (new - Left/Right),
List, Writer, State, Reader. Plus `Monad`/`LiftableMonad` base classes
(modeled on `unpythonic.slicing.Sliced`) and `liftm`/`liftm2`/`liftm3`
helpers. Subpackage is not re-exported at top level; import directly.

`monadic_do` block macro: `with monadic_do[M] as result:` over any monad,
with body `[bindings] in result << final_expr`. Supports `:=` (primary)
and `<<` (legacy) for bindings; `_ := mexpr` for sequencing; empty
bindings allowed. Parsed via `letdoutil.canonize_bindings`, expands to
a nested lambda-bind chain. Always the innermost `with` (body shape
constraint), composes correctly with lazify / continuations / tco /
autocurry et al. between their two passes.

State.join properly implemented (teaching code had NotImplementedError):
run the outer state function, then run the inner with the threaded
state — standard "thread the state" pattern.

MonadicList was moved to `unpythonic.monads.List` with a varargs
constructor (so `List(x)` is the monadic unit). `amb.MonadicList`
remains as a silent alias with a TODO(3.0.0) for removal. Added a
`_make` classmethod on `List` so `mogrify` reconstructs containers
elementwise (matching the namedtuple convention), which is what
`forall` needs under Pytkell's `lazify`.

Brief: briefs/monads-implementation.md (already committed as 1249f9c).
Tests: 115 pure-Python + 17 macro + 14 integration (including the
critical lazify short-circuit preservation test). All green on 3.14.

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

Author: Technologicat

AUTHORS.md

@@ -2,7 +2,7 @@
 
 - Juha Jeronen (@Technologicat) - original author
 - @aisha-w - documentation improvements
-- @Technologicat with Claude (Anthropic) as AI pair programmer - CI modernization, Python 3.13–3.14 and mcpyrate 4.0.0 adaptation (2.0.0)
+- @Technologicat with Claude (Anthropic) as AI pair programmer - CI modernization, Python 3.13–3.14 and mcpyrate 4.0.0 adaptation (2.0.0); monads subpackage and `monadic_do` macro (2.1.0)
 
 **Design inspiration from the internet**:
 

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 **New**:
 
+- `unpythonic.monads`: subpackage of classical monads — `Identity`, `Maybe`, `Either` (with `Left`/`Right`), `List`, `Writer`, `State`, `Reader`. Plus `Monad`/`LiftableMonad` base classes and `liftm`/`liftm2`/`liftm3` helpers. Not re-exported at the top level; import as `from unpythonic.monads import Maybe`.
+- `monadic_do`: do-notation macro over any monad. `with monadic_do[M] as result:` with body `[bindings] in result << final_expr`; supports `:=` (primary) and `<<` (legacy) for bindings; empty bindings allowed; `_ := mexpr` for sequencing. Always used as the innermost `with` (body shape constraint), composes correctly with `lazify`/`continuations`/`tco`/`autocurry`/etc.
 - `environ_override`: context manager to temporarily override OS environment variables within a `with` block, restoring the previous state on exit.
   - Thread-safe (serialises concurrent overrides via `RLock`); same-thread nesting supported.
   - New module `unpythonic.environ`; the function is named `override` at the module level and re-exported as `environ_override` at the top level.
@@ -25,6 +27,7 @@
 
 **Changed**:
 
+- `unpythonic.amb.MonadicList`: the implementation was moved to `unpythonic.monads.List` and renamed. `MonadicList` remains as a silent alias of `List` for name compatibility, scheduled for removal in 3.0.0. The constructor uses varargs (`List(1, 2, 3)`) — the class itself is the monadic unit (`List(x)` is a singleton list). Iterable-constructor use-cases go through `List.from_iterable(iterable)`.
 - `unpythonic.net` (REPL server and client) now runs on MS Windows.
   - Previously the whole subsystem was POSIX-only because `unpythonic.net.ptyproxy` required `termios`, `tty`, and `os.openpty`.
   - A new `socket.socketpair()`-based backend stands in for the pty master/slave endpoints on Windows, plugged in via a platform dispatch in `PTYSocketProxy`.

README.md

@@ -335,6 +335,31 @@ The condition system is the clean, general solution to this problem. It automati
 
 If this sounds a lot like an exception system, that's because conditions are the supercharged sister of exceptions. The condition model cleanly separates mechanism from policy, while otherwise remaining similar to the exception model.
 </details>  
+<details><summary>Monads: Identity, Maybe, Either, List, Writer, State, Reader.</summary>
+
+[[docs](doc/features.md#monads)] [[`monadic_do` macro](doc/macros.md#monadic_do-do-notation-for-any-monad)]
+
+```python
+from unpythonic.llist import nil
+from unpythonic.monads import Maybe, List
+
+# Maybe — short-circuits on `nil`; the lambda is never called
+assert Maybe(nil) >> (lambda x: Maybe(x + 1)) == Maybe(nil)
+
+# List — flatMap. Pythagorean triples by three nested binds.
+def r(lo, hi):
+    return List.from_iterable(range(lo, hi))
+pt = r(1, 21) >> (lambda z:
+     r(1, z + 1) >> (lambda x:
+     r(x, z + 1) >> (lambda y:
+     List.guard(x*x + y*y == z*z).then(
+     List((x, y, z))))))
+assert tuple(sorted(pt)) == ((3, 4, 5), (5, 12, 13), (6, 8, 10),
+                             (8, 15, 17), (9, 12, 15), (12, 16, 20))
+```
+
+For do-notation syntax (`with monadic_do[M] as result:`), see the macro documentation. Bind is `>>` (Python's `>>=` is in-place and doesn't chain), sequence is `.then(other)`, the class itself is `unit`.
+</details>  
 <details><summary>Lispy symbol type.</summary>
 
 [[docs](doc/features.md#sym-gensym-Singleton-symbols-and-singletons)]
@@ -698,6 +723,34 @@ with lazify:
     assert my_if(False, 1/0, 42) == 42
 ```
 </details>  
+<details><summary>Monadic do-notation for any monad.</summary>
+
+[[docs](doc/macros.md#monadic_do-do-notation-for-any-monad)]
+
+```python
+from unpythonic.syntax import macros, monadic_do
+from unpythonic.monads import Maybe, List
+
+# Maybe — do-notation threads Just-values (denoted `Maybe(value)`); any Nothing (`unpythonic.nil`) short-circuits.
+with monadic_do[Maybe] as result:
+    [x := Maybe(10),
+     y := Maybe(x + 1)] in result << Maybe(x + y)
+assert result == Maybe(21)
+
+# List — Pythagorean triples via the list monad
+def r(lo, hi):
+    return List.from_iterable(range(lo, hi))
+with monadic_do[List] as pt:
+    [z := r(1, 21),
+     x := r(1, z + 1),
+     y := r(x, z + 1),
+     _ := List.guard(x*x + y*y == z*z)] in pt << List((x, y, z))
+assert tuple(sorted(pt)) == ((3, 4, 5), (5, 12, 13), (6, 8, 10),
+                             (8, 15, 17), (9, 12, 15), (12, 16, 20))
+```
+
+Body shape is a single `[bindings] in result << final_expr` statement: bindings on the left of `in`, the "send to box" exit pattern on the right. `:=` is the primary bind arrow (parsed by the same `letdoutil` machinery as the modern `let[]` syntax); `<<` also works.
+</details>  
 <details><summary>Genuine multi-shot continuations (call/cc).</summary>
 
 [[docs](doc/macros.md#continuations-callcc-for-python)]

TODO_DEFERRED.md

@@ -54,3 +54,9 @@ Next unused item code: D16
 - **D15: Audit bare `{path}` interpolation for repr/raw asymmetry on Windows**: Fleet-wide audit across all projects. The known failure mode (mcpyrate `cacbfd2`, 2026-04-15): an f-string interpolates a file path with bare `{__file__}`, producing raw backslashes (`C:\a\b`), while the other side of a comparison uses `repr()`/`unparse()` output with escaped backslashes (`C:\\a\\b`) — mismatch on Windows, passes on POSIX by accident. Fix is `{__file__!r}` so both sides speak the same dialect. The risk is NOT f-string reinterpretation (that's safe), but asymmetry when a bare-interpolated path is compared against, compiled as, or embedded into Python source. Grep hints: `__file__` in f-strings; also any path value interpolated into strings that later reach `compile()`, `eval()`, `ast.unparse()`, assertions, or similar. (Noted 2026-04-17.)
 
 
+- **D16: Remove `unpythonic.amb.MonadicList` alias (3.0.0)**: As part of D13 monads port, `MonadicList` was moved to `unpythonic.monads.List` with a varargs constructor (`List(1, 2, 3)` instead of `MonadicList([1, 2, 3])`). A silent alias `MonadicList = List` is kept in `unpythonic/amb.py` for backward-name compatibility during the 2.x series. Remove the alias in 3.0.0 along with the accompanying `TODO(3.0.0)` comment at the alias site. Users must then import `List` directly from `unpythonic.monads`. Note: this is name-only compat — the constructor signature changed at 2.0.0, so existing callers of `MonadicList([...])` already needed to switch to varargs or `from_iterable(...)` at 2.0.0. (Noted 2026-04-17.)
+
+
+- **D17: `monadic_do[List]` inside Pytkell's auto-lazify yields wrapped generators**: The Pythagorean-triples-style `monadic_do[List]` computation, when run under the Pytkell dialect (which wraps the whole module in `with lazify, autocurry:`), produces a result whose `tuple(sorted(pt))` is a 1-tuple containing a generator instead of the expected 6-tuple of triples. The `_make = from_iterable` hook on `List` (added to make `mogrify` rebuild the container elementwise) fixed the analogous `forall`-based test and the container-monad cases (`Maybe`, `Writer`, `Either` under Pytkell work fine), but something in the deeper bind-chain recursion under `lazify`'s `mogrify` still produces a generator that doesn't get forced. Workaround for now: use `monadic_do[List]` outside Pytkell, or materialize intermediate results explicitly. Debug starting point: `unpythonic/dialects/tests/test_pytkell.py`, the commented-out List-Pythagorean case in the "monadic do-notation" testset. (Noted 2026-04-17.)
+
+

doc/features.md

@@ -85,6 +85,7 @@ The exception are the features marked **[M]**, which are primarily intended as a
 - [`catch`, `throw`: escape continuations (ec)](#catch-throw-escape-continuations-ec) (as in [Lisp's `catch`/`throw`](http://www.gigamonkeys.com/book/the-special-operators.html), unlike C++ or Java)
   - [`call_ec`: first-class escape continuations](#call_ec-first-class-escape-continuations), like Racket's `call/ec`.
 - [`forall`: nondeterministic evaluation](#forall-nondeterministic-evaluation), a tuple comprehension with multiple body expressions.
+- [Monads](#monads): Identity, Maybe, Either, List, Writer, State, Reader — plus `liftm`/`liftm2`/`liftm3`. For do-notation syntax, see the [`monadic_do` macro](macros.md#monadic_do-do-notation-for-any-monad).
 - [`handlers`, `restarts`: conditions and restarts](#handlers-restarts-conditions-and-restarts), a.k.a. **resumable exceptions**.
   - [Fundamental signaling protocol](#fundamental-signaling-protocol)
   - [API summary](#api-summary)
@@ -3596,6 +3597,159 @@ The implementation is based on the List monad, and a bastardized variant of do-n
  - Last line = implicit `return ...`
 
 
+### Monads
+
+**Added in v2.1.0.**
+
+A small zoo of classical monads, living in the `unpythonic.monads` subpackage. For do-notation syntax over any of these, see the [`monadic_do` macro](macros.md#monadic_do-do-notation-for-any-monad).
+
+The subpackage is **not** re-exported at the top level — import directly as `from unpythonic.monads import Maybe, Left, Right, ...`. Same style as `from unpythonic.env import env`.
+
+Bind uses `>>` (Python's `>>=` is `__irshift__`, in-place, doesn't chain). Sequence uses `.then(other_monad)`. The class itself is the `unit` constructor, so `Identity(x)`, `Maybe(x)`, `List(x)` are the monadic unit forms.
+
+#### The base classes
+
+- `Monad` — the base class all monads inherit from. Provides default `__rshift__` (bind, via `fmap . join`) and `then` (sequence). Abstract methods: `__init__` (unit), `fmap`, `join`.
+
+- `LiftableMonad(Monad)` — adds `lift`, i.e. `(a -> b) -> (a -> M b)`. Inherited by monads where `lift` is well-defined (`Identity`, `Maybe`, `Either`, `List`, `Writer`). `State` and `Reader` inherit from `Monad` directly.
+
+Modeled on `unpythonic.slicing.Sliced`: duck-first, `@abstractmethod` as documentation marker rather than strict enforcement.
+
+#### `Identity`
+
+Pedagogical no-op — ordinary function composition dressed as a monad. Useful as a reference when building or debugging other monads.
+
+```python
+from unpythonic.monads import Identity
+
+result = Identity(2) >> (lambda x: Identity(x + 1))
+assert result == Identity(3)
+```
+
+#### `Maybe`
+
+Short-circuiting on "nothing." The unpythonic convention uses `nil` (from `unpythonic.llist`) as the "nothing" sentinel, avoiding proliferation of null singletons. `Maybe(x)` for `x is not nil` is "Just x"; `Maybe(nil)` is "Nothing."
+
+```python
+from unpythonic.llist import nil
+from unpythonic.monads import Maybe
+
+# happy path
+assert Maybe(10) >> (lambda x: Maybe(x + 1)) == Maybe(11)
+
+# short-circuit: Nothing propagates; the lambda is never called
+assert Maybe(nil) >> (lambda x: Maybe(x + 1)) == Maybe(nil)
+```
+
+Trade-off: This encoding cannot wrap ``nil`` itself as a present value (Haskell: `Just nil`). In all other cases this yields better UX vs. demanding a ``Some(...)`` wrapper per value.
+
+#### `Either`, `Left`, `Right`
+
+Maybe's richer sibling — carries an error value down the short-circuit path. `Right` is success, `Left` is failure (by Haskell convention). `Either` itself is abstract; use `Left` and `Right` directly.
+
+```python
+from unpythonic.monads import Left, Right
+
+assert Right(10) >> (lambda x: Right(x + 1)) == Right(11)
+assert Left("boom") >> (lambda x: Right(x + 1)) == Left("boom")
+```
+
+#### `List`
+
+Multivalued / nondeterministic computation. Binding through a `List` is `flatMap`: each value in the list becomes a sub-computation that produces its own list of results, and all sub-results are concatenated.
+
+Replaces `MonadicList` from `unpythonic.amb`, which is kept as a deprecated alias — see `unpythonic.amb.MonadicList` for the back-compat note.
+
+Varargs constructor — the class itself is the monadic unit. `List(1, 2, 3)` for literals; `List.from_iterable(iter)` to build from an existing iterable.
+
+```python
+from unpythonic.monads import List
+
+# bind = flatMap
+assert (List(1, 2, 3) >> (lambda x: List(x, x * 10))) == List(1, 10, 2, 20, 3, 30)
+
+# Pythagorean triples — the canonical List-monad example
+def r(lo, hi):
+    return List.from_iterable(range(lo, hi))
+pt = r(1, 21) >> (lambda z:
+     r(1, z + 1) >> (lambda x:
+     r(x, z + 1) >> (lambda y:
+     List.guard(x*x + y*y == z*z).then(
+     List((x, y, z))))))
+assert tuple(sorted(pt)) == ((3, 4, 5), (5, 12, 13), (6, 8, 10),
+                             (8, 15, 17), (9, 12, 15), (12, 16, 20))
+```
+
+Full `Sequence` ABC (`__len__`, `__getitem__`, `__contains__`, etc.); ABC registration so `isinstance(List(...), Sequence)` is `True`. Concatenation via `+`.
+
+#### `Writer`
+
+Pure-functional audit log. `Writer(value, log)` wraps a pair; binding threads the value through while concatenating logs. The log can be any type supporting `+` (default: empty `""`).
+
+```python
+from unpythonic.monads import Writer
+
+result = (Writer(10)
+          >> (lambda x: Writer(x + 1, "added 1; "))
+          >> (lambda y: Writer(y * 2, "doubled; ")))
+assert result.data == (22, "added 1; doubled; ")
+```
+
+`Writer.tell(msg)` interleaves a log entry without touching the value — useful as `computation.then(Writer.tell("done; "))`.
+
+#### `State`
+
+Threading a state value through a pure computation. Wraps a function `s -> (a, s)`: takes an input state, produces a data value, returns a new state. The state only becomes bound when the composed chain is `.run(s0)`; until then, it's a recipe.
+
+```python
+from unpythonic.monads import State
+
+bump = State(lambda s: (s, s + 1))
+chain = (bump
+         >> (lambda a: bump
+         >> (lambda b: bump
+         >> (lambda c: State.unit((a, b, c))))))
+values, final = chain.run(10)
+assert values == (10, 11, 12) and final == 13
+```
+
+Helper classmethods: `State.unit`, `State.get`, `State.put`, `State.modify`, `State.gets`. Accessors on a `State` instance: `.run(s)`, `.eval(s)` (data only), `.exec(s)` (state only).
+
+Does not inherit from `LiftableMonad` — `lift` doesn't have a canonical shape for State.
+
+#### `Reader`
+
+Read-only shared environment. Wraps a function `e -> a`. The environment threads through the chain; each step can `.ask()` for it.
+
+```python
+from unpythonic.monads import Reader
+
+config = {"multiplier": 3, "offset": 10}
+chain = (Reader.asks(lambda e: e["multiplier"])
+         >> (lambda m: Reader.asks(lambda e: e["offset"])
+         >> (lambda o: Reader.unit(m * 5 + o))))
+assert chain.run(config) == 25
+```
+
+Helper classmethods: `Reader.unit`, `Reader.ask`, `Reader.asks`. Instance methods: `.run(env)`, `.local(f)` (run in an `f`-modified environment).
+
+Does not inherit from `LiftableMonad` for the same reason as `State`.
+
+#### `liftm`, `liftm2`, `liftm3`
+
+Lift regular 1-, 2-, 3-argument functions into monadic ones. Distinct from `LiftableMonad.lift`: `lift: (a -> b) -> (a -> M b)` expects the caller to bind; `liftm: (a -> r) -> (M a -> M r)` binds internally.
+
+```python
+from unpythonic.monads import Maybe, liftm2
+
+add = lambda x, y: x + y
+add_m = liftm2(Maybe, add)
+assert add_m(Maybe(3), Maybe(4)) == Maybe(7)
+```
+
+The `M` parameter is curry-friendly (changes least often) — `functools.partial(liftm2, Maybe)` gives you a Maybe-specific lifter.
+
+
 ### `handlers`, `restarts`: conditions and restarts
 
 **Changed in v0.15.0.** *Functions `resignal_in` and `resignal` added; these perform the same job for conditions as `reraise_in` and `reraise` do for exceptions, that is, they allow you to map library exception types to semantically appropriate application exception types, with minimum boilerplate.*

doc/macros.md

@@ -65,6 +65,7 @@ Because in Python macro expansion occurs *at import time*, Python programs whose
   - [Why this syntax?](#why-this-syntax)
 - [`prefix`: prefix function call syntax for Python](#prefix-prefix-function-call-syntax-for-python)
 - [`autoreturn`: implicit `return` in tail position](#autoreturn-implicit-return-in-tail-position), like in Lisps.
+- [`monadic_do`: do-notation for any monad](#monadic_do-do-notation-for-any-monad), over [unpythonic's classical monad zoo](features.md#monads).
 - [`forall`: nondeterministic evaluation](#forall-nondeterministic-evaluation) with monadic do-notation for Python.
 
 [**Convenience features**](#convenience-features)
@@ -1809,6 +1810,64 @@ For code using **conditions and restarts**: there is no special integration betw
  - The `with handlers` form itself is just `with` block, so it also gets the `autoreturn` treatment.
 
 
+### `monadic_do`: do-notation for any monad
+
+**Added in v2.1.0.**
+
+Monadic do-notation over any of the monads in [`unpythonic.monads`](features.md#monads) (or, for that matter, any object that implements `__rshift__` as monadic bind).
+
+The body of `with monadic_do[M] as result:` must be a single statement of the form `[bindings] in result << final_expr`. Each binding is a `name := mexpr` pair; `name << mexpr` is accepted as a deprecated alternative (the same shapes `letdoutil` understands for `let[]`). The `result << final_expr` on the RHS of `in` is where the final monadic value lands; this is the "send to box" exit idiom unpythonic uses elsewhere (e.g., the condition/restart subsystem), sidestepping the stmt/expr distinction without hijacking `return`.
+
+```python
+from unpythonic.syntax import macros, monadic_do
+from unpythonic.monads import Maybe, Left, Right, List, Writer
+from unpythonic.llist import nil
+
+# Maybe — happy path
+with monadic_do[Maybe] as result:
+    [x := Maybe(10),
+     y := Maybe(x + 1)] in result << Maybe(x + y)
+assert result == Maybe(21)
+
+# Maybe — short-circuit. The `y := ...` line is never evaluated.
+with monadic_do[Maybe] as result:
+    [x := Maybe(nil),
+     y := Maybe(x + 1)] in result << Maybe(x + y)
+assert result == Maybe(nil)
+
+# List — Pythagorean triples
+def r(lo, hi):
+    return List.from_iterable(range(lo, hi))
+with monadic_do[List] as pt:
+    [z := r(1, 21),
+     x := r(1, z + 1),
+     y := r(x, z + 1),
+     _ := List.guard(x*x + y*y == z*z)] in pt << List((x, y, z))
+assert tuple(sorted(pt)) == ((3, 4, 5), (5, 12, 13), (6, 8, 10),
+                             (8, 15, 17), (9, 12, 15), (12, 16, 20))
+```
+
+Sequencing-only lines (Haskell `do { mx; ...; }` — a bind whose result is discarded) are spelled `_ := mexpr`. The throwaway `_` makes the intent visible. Empty bindings are allowed: `[] in result << M.unit(x)` reduces to `result = M.unit(x)`.
+
+Expands to a nested lambda-bind chain:
+
+```python
+result = mx >> (lambda x: my(x) >> (lambda y: final_expr))
+```
+
+**Placement in the xmas tree**: `monadic_do` is always the **innermost** `with`. Its body-shape constraint (a single `[bindings] in result << expr` statement) forbids lexically wrapping other `with` blocks inside. Outer two-pass macros (`lazify`, `continuations`, `tco`, `autocurry`, etc.) expand inner macros between their passes, so they will see and edit the expanded bind chain in the right order.
+
+```python
+with lazify:
+    with monadic_do[Maybe] as result:
+        ...
+```
+
+For the pure-Python monads themselves and the `liftm` helpers, see [features.md](features.md#monads).
+
+For the List-monad-specific do-notation that existed first, see [`forall`](#forall-nondeterministic-evaluation) below.
+
+
 ### `forall`: nondeterministic evaluation
 
 **Changed in v0.15.3.** *Env-assignment now uses the assignment expression syntax `x := range(3)`. The old syntax `x << range(3)` is still supported for backward compatibility.*