Examples: extend interop cookbook with effects (pathlib, requests)

Two entries centered on inferred effects — Pyfun's differentiator:

- read_files (pathlib): offline-runnable io-effect showcase; effect
  inference + propagation, the `let pure` rejection as the guarantee, and
  try→Result on a missing file.
- http_fetch (requests/httpx): check-valid effects/async entry (needs
  requests + network to run); io from requests.get, `->{async}` for httpx,
  and the compile-time effect guarantee.

Building these dogfooded four extern-FFI reach gaps (submodule imports,
nullary calls, builtin-type dotted targets, property access) — documented
in the cookbook README's limits and added as a consolidated ROADMAP item.
All offline examples run end-to-end; http_fetch pyfun-checks.

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

Author: simontreanor

ROADMAP.md

@@ -39,6 +39,17 @@ Keep this a *forward-looking* backlog — do not let it grow back into a changel
 - **`Format` module — dates follow-on** (S) — the numeric/string first cut shipped (`Format.fixed`/
   `thousands`/`percent`/`currency`/`grouped`/`padLeft`/`padRight`). `formatDate` is still open: it needs a
   date type or a Python `datetime` `extern`, so it was left out of the pure-stdlib first cut.
+- **Extern FFI reach** (M) — four related boundary gaps surfaced by the `examples/interop/` cookbook
+  (dogfooding real Python libraries). None blocks the showcase — each has a workaround noted in that
+  README — but together they decide how many popular libraries wrap cleanly: (1) the importer emits only
+  the *first* dotted segment (`import urllib`), so a target inside a **submodule**
+  (`urllib.request.urlopen`, `http.client.HTTPConnection`) fails at runtime — emit the full parent
+  package path instead; (2) a **nullary** Python callable can't be invoked — `f : unit -> a` lowers
+  `f ()` to `f(None)`, not `f()`; needs a zero-arg calling convention for a `unit` domain; (3) a dotted
+  target on a **builtin type** (`bytes.decode`) emits `import bytes` and fails — recognize builtins;
+  (4) object **properties/attributes** (`response.text`, `.status_code`) aren't reachable — the
+  unbound-method trick only calls real methods, so an attribute-getter extern form (or `operator.attrgetter`
+  sugar) would round it out. `DESIGN.md` §6.
 - **Larger prelude / package manager / macros** — added on demand. A future Python-side runtime package
   could default to `uv`.
 

examples/interop/README.md

@@ -1,12 +1,15 @@
 # Interop cookbook
 
-Short, runnable Pyfun programs that call **well-known Python libraries** and show what
-Pyfun's typed, effect-tracked boundary adds to the calling code. Each file runs with:
+Short Pyfun programs that call **well-known Python libraries** and show what Pyfun's
+typed, effect-tracked boundary adds to the calling code. Most run offline with:
 
 ```bash
 pyfun run examples/interop/<name>.pyfun
 ```
 
+(`http_fetch.pyfun` is the exception — it `pyfun check`s offline but needs `requests`
++ network to `run`; see the table.)
+
 ## The idea: boundary libraries, not engine libraries
 
 Popular Python libraries split in two, and only one kind showcases Pyfun:
@@ -27,14 +30,13 @@ The honest headline is therefore **not** "rewrite the popular libraries in Pyfun
 
 ## Entries
 
-| File | Library | Shows |
-|------|---------|-------|
-| [`json_decode.pyfun`](./json_decode.pyfun) | `json` (stdlib) | `try` → `Result` totality; homogeneous JSON → `List`/`Map`; total `Map.tryFind` lookup |
-| [`json_to_adt.pyfun`](./json_to_adt.pyfun) | `json` (stdlib) | **the headline** — decode a heterogeneous object into your own record, totally, via `result {}` railway composition (KeyError/ValueError → `Error`) |
-| [`sqlite_query.pyfun`](./sqlite_query.pyfun) | `sqlite3` (stdlib) | opaque handle types + unbound-method externs; rows as tuples; `List`/tuple decoding |
-
-Planned: `http_fetch` (`requests`/`httpx` — `io`/`->{async}` effects, typed responses),
-`read_files` (`pathlib` — `io` effects).
+| File | Library | Runs offline | Shows |
+|------|---------|:---:|-------|
+| [`json_decode.pyfun`](./json_decode.pyfun) | `json` (stdlib) | ✅ | `try` → `Result` totality; homogeneous JSON → `List`/`Map`; total `Map.tryFind` lookup |
+| [`json_to_adt.pyfun`](./json_to_adt.pyfun) | `json` (stdlib) | ✅ | **the headline** — decode a heterogeneous object into your own record, totally, via `result {}` railway composition (KeyError/ValueError → `Error`) |
+| [`sqlite_query.pyfun`](./sqlite_query.pyfun) | `sqlite3` (stdlib) | ✅ | opaque handle types + unbound-method externs; rows as tuples; `List`/tuple decoding |
+| [`read_files.pyfun`](./read_files.pyfun) | `pathlib` (stdlib) | ✅ | inferred `io` effect + propagation; `let pure` rejection; `try` → `Result` on a missing file |
+| [`http_fetch.pyfun`](./http_fetch.pyfun) | `requests`/`httpx` | check-only | inferred `io` / `->{async}` effects; the effect *guarantee* (`let pure` over `io` is a compile error) |
 
 ## Reusable patterns (all verified against the current compiler)
 
@@ -51,6 +53,9 @@ Planned: `http_fetch` (`requests`/`httpx` — `io`/`->{async}` effects, typed re
   (`operator.getitem`), coerce it (`int`/`str`), wrap each step in `try`, and compose on
   the `result {}` railway so the first bad field short-circuits to `Error`. See
   `json_to_adt.pyfun`; this is the shape a decoder-combinator library would generalize.
+- **Effects for free.** A plain `extern` is `io`; the checker infers and propagates it, so
+  any function touching the boundary is `io` with no annotation, and `let pure` over it is
+  a compile error. Override the boundary default with `->{async}` for async libraries.
 
 ## Honest limits (the frontier these examples expose)
 
@@ -65,3 +70,10 @@ Planned: `http_fetch` (`requests`/`httpx` — `io`/`->{async}` effects, typed re
   wrapper library would pull in the deferred package manager).
 - **Anonymous record types** aren't accepted in an extern signature, so an ad-hoc request
   or response body needs a named `type`. (Tracked separately.)
+- **Extern FFI rough edges surfaced while building these** (tracked in `ROADMAP.md`): the
+  importer emits only the *first* dotted segment (`import urllib`), so a target in a
+  **submodule** (`urllib.request.urlopen`, `http.client`) fails at runtime — which is why
+  the HTTP entry uses `requests`, not stdlib; a **nullary** Python function can't be called
+  (`gettempdir ()` passes unit as an argument); a dotted target on a **builtin type**
+  (`bytes.decode`) tries to `import bytes`; and object **properties** (`response.text`,
+  `.status_code`) aren't reachable by the unbound-method trick (only real methods are).

examples/interop/http_fetch.pyfun

@@ -0,0 +1,43 @@
+# Interop cookbook — HTTP: inferred effects (io / async), the Pyfun differentiator.
+#
+#   pyfun check examples/interop/http_fetch.pyfun     # type/effect-checks offline
+#   pyfun run   examples/interop/http_fetch.pyfun     # needs `requests`+`httpx` + network
+#
+# NOTE: unlike the other cookbook entries this one is CHECK-VALID rather than
+# offline-runnable — it calls the third-party `requests`/`httpx` against the network.
+# The point it showcases is a *compile-time* guarantee anyway: Pyfun infers effects
+# and won't let you lie about them. (Why not a stdlib HTTP client? `urllib.request` /
+# `http.client` live in submodules the extern importer doesn't yet load — see the
+# cookbook README's limits.)
+
+type Response = RespH
+
+# A plain `extern` is `io` at the boundary. `requests.get` therefore contributes an
+# `io` effect wherever it is called — no annotation required.
+extern get: string -> Response = requests.get
+# `.json()` is a real method (unbound-method trick); it returns a raw parsed value,
+# the same opaque handle json_to_adt.pyfun decodes into a typed record.
+extern getJson: Response -> a = requests.Response.json
+
+# `fetch` calls `get`, so the compiler INFERS `fetch : string -> Result Response
+# Exception` and that it performs `io` — impurity propagates outward automatically.
+# `try` makes a failed request an `Error` value instead of a raised exception.
+let fetch url = try (get url)
+
+# The effect is a checked guarantee, not documentation. Uncommenting this is a
+# compile error — "`cached` is declared `pure` but performs `io`" — because `pure`
+# forbids the `io` that `get` introduces:
+#
+#   let pure cached url = get url
+#
+# Async is a distinct effect. Annotating an extern arrow `->{async}` (overriding the
+# default `io`) marks `httpx.get` as performing `async`; any caller inherits it, so it
+# could not sit inside a `let pure` either. Async CEs (`async { let! r = … }`) then
+# compose these exactly as `result {}` composes the `Result`-returning steps elsewhere.
+extern getAsync: string ->{async} Response = httpx.get
+let fetchAsync url = getAsync url
+
+# Full application collapses to a direct n-ary Python call — `fetch "https://…"`
+# lowers to `requests.get("https://…")` wrapped in try/except, no currying overhead.
+let example = fetch "https://example.com"
+let exampleJson = Result.map getJson example    # Result a Exception, decode next

examples/interop/read_files.pyfun

@@ -0,0 +1,37 @@
+# Interop cookbook — pathlib: file I/O, with effects inferred and failure made total.
+#
+#   pyfun run examples/interop/read_files.pyfun
+#
+# `pathlib` is stdlib file I/O — the plainest kind of side effect. Two Pyfun features
+# show up here for free: the compiler *infers* that these calls are `io` and
+# propagates it (no annotation needed), and `try` turns a missing-file exception into
+# a `Result` you must handle. This file runs offline and cleans up after itself.
+
+# `pathlib.Path(str)` builds a path; the rest are unbound methods on `pathlib.Path`
+# (see sqlite_query.pyfun for the pattern). Each is `io` by the boundary default.
+type Path = PathH
+extern toPath: string -> Path = pathlib.Path
+extern writeText: Path -> string -> int = pathlib.Path.write_text
+extern readText: Path -> string = pathlib.Path.read_text
+extern unlink: Path -> unit = pathlib.Path.unlink
+
+# `roundTrip` calls `io` externs, so the compiler infers `roundTrip : string -> unit`
+# is itself `io` — impurity propagates outward with no annotation. Writing
+# `let pure roundTrip …` would be rejected: "`roundTrip` is declared `pure` but
+# performs `io`". That is the effect guarantee — purity is checked, not hoped for.
+let roundTrip name =
+  let p = toPath name
+  let _ = writeText p "hello from pyfun"
+  let back = readText p
+  let _ = unlink p
+  back
+
+# Reading a missing file is total: `try` catches the FileNotFoundError into `Error`,
+# so a bad path yields a value describing the failure rather than crashing.
+let readOrNote name =
+  match try (readText (toPath name)):
+    case Ok s: s
+    case Error e: f"(could not read {name}: {e.errorKind})"
+
+print (roundTrip "pyfun_interop_demo.txt")   # hello from pyfun
+print (readOrNote "no_such_file.txt")        # (could not read no_such_file.txt: FileNotFoundError)