Skip to content

Commit 1c15e9f

Browse files
Technologicatclaude
andcommitted
TODO_DEFERRED: split the env re-export into a doc fix and a 3.0.0 fix
Documenting that `from unpythonic import env` hands back the module is non-breaking and can land any time. Re-exporting the class so it hands back the class is not: it changes what an existing import returns, so it belongs in 3.0.0, bundled with the rest of the API-breakage debt. Also records how to find that debt rather than re-deriving it: the convention is an in-source `TODO(3.0.0)` marker plus an item here, so `grep -rn "TODO(3.0.0)"` is the inventory. Today it finds one, which is likely an undercount — a marker exists only where someone thought to leave one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent b19e711 commit 1c15e9f

1 file changed

Lines changed: 9 additions & 0 deletions

File tree

TODO_DEFERRED.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,15 @@ than next to the thing it is about.**
126126
callable". The correct form is `from unpythonic.env import env`. Nothing in the docs says this;
127127
it has to be discovered by trying it. This is the most user-facing of the four — `env` is one of the
128128
most-used things in the library.
129+
130+
**Two fixes here, and only one of them is cheap** (Juha, 2026-08-16). Documenting the gotcha at the
131+
site is non-breaking and can land in any release. *Actually* re-exporting the class would change
132+
what `from unpythonic import env` returns, which breaks anyone relying on getting the module — so
133+
the real fix waits for **3.0.0**, and wants to go in together with whatever other API-breakage debt
134+
has accumulated. Size that first: the convention is an in-source `TODO(3.0.0)` marker plus an item
135+
here, so `grep -rn "TODO(3.0.0)" unpythonic/` is the inventory command. As of 2026-08-16 it finds
136+
one (the `MonadicList` alias in `amb.py`), which is almost certainly an undercount — the markers
137+
only exist where someone remembered to leave one.
129138
- **"Not for production" is documented away from the construct.** `design-notes.md` explains that
130139
`unpythonic.amb.forall` is the overly-complicated non-macro version and `unpythonic.syntax.forall`
131140
is the clean one — but `amb`'s own docstring reads as a straight feature. Same for `prefix` and

0 commit comments

Comments
 (0)