From c6ecec44bc9204ee0b2eb1f19e03ba71df9c3e91 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 20 Jun 2026 17:55:58 +0000 Subject: [PATCH 1/2] docs: correct REPL autocomplete claim in README adventures The declared-fields payoff is editor (Pylance) autocomplete, not REPL tab-completion. Clarify that REPL completion is a separate readline/ rlcompleter feature and show how to enable it for a session. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01AHAkhfmfcCdWTHZuvRcJNF --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f72c61e..f235686 100644 --- a/README.md +++ b/README.md @@ -75,9 +75,15 @@ python >>> Sector(bering=1, level=2) # a typo is a TypeError, not a silent new key ``` -Tab-completion works on every attribute because the fields are *declared*. Read -[`docs/concepts/typed-vs-dicts.md`](docs/concepts/typed-vs-dicts.md) for what this buys -you over a dictionary, then look at how the builder rejects out-of-range values in +The real payoff of *declared* fields is in your **editor**: type `platform.` in a `.py` +file and VS Code (Pylance) offers every attribute, statically, before the code even runs — +that's what the declarations buy you. (In the bare `python` REPL you may also get attribute +completion, but it's a separate `readline`/`rlcompleter` feature that introspects the live +object at runtime; if `` doesn't complete, enable it for the session with +`import readline, rlcompleter; readline.parse_and_bind("tab: complete")`.) + +Read [`docs/concepts/typed-vs-dicts.md`](docs/concepts/typed-vs-dicts.md) for what declared +fields buy you over a dictionary, then look at how the builder rejects out-of-range values in `src/acoustic_dataset/build.py`. ### Adventure 3 — Reverse-engineer the data classes from the schema From f28ae427c78dd8462037c69affad381545d07292 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 20 Jun 2026 17:58:13 +0000 Subject: [PATCH 2/2] docs: add editor-autocomplete step with a scratch file to Adventure 2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add examples/explore_platform.py — a runnable, freely-editable file that builds a typed Platform — and a README step walking through experiencing Pylance autocomplete on it in VS Code. Reframe the REPL completion note as the separate runtime feature it is. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01AHAkhfmfcCdWTHZuvRcJNF --- README.md | 32 ++++++++++++++++++++++++-------- examples/explore_platform.py | 22 ++++++++++++++++++++++ 2 files changed, 46 insertions(+), 8 deletions(-) create mode 100644 examples/explore_platform.py diff --git a/README.md b/README.md index f235686..78c3a07 100644 --- a/README.md +++ b/README.md @@ -56,10 +56,28 @@ explains why "schema-valid" and "correct" are two different checks. The code liv `src/acoustic_dataset/validate.py` and `compare.py`, dispatched from [`cli.py`](src/acoustic_dataset/cli.py). -### Adventure 2 — Explore a typed Python data class in the REPL +### Adventure 2 — Explore a typed Python data class The pipeline never carries data in a loose `dict`; it builds **one typed object that -meets the schema**. Feel the difference yourself: +meets the schema**. Feel the difference yourself. + +**First, experience editor autocomplete.** Open +[`examples/explore_platform.py`](examples/explore_platform.py) in VS Code (the Codespace +ships Pylance). Find the `# platform.` line, delete the `#`, put your cursor right after the +dot, and type: VS Code pops up the object's *declared* attributes (`radiated_noise`, +`sensors`, …) — statically, before the code has even run. Keep drilling +(`platform.radiated_noise.band[0].`) and it completes all the way down. That instant, +schema-shaped autocomplete is the real payoff of declared fields. Run the file any time with: + +```bash +python examples/explore_platform.py +``` + +> If autocomplete doesn't appear, give Pylance a moment to index, and make sure VS Code's +> Python interpreter is set to the Codespace's 3.9 (bottom-right status bar / *Python: Select +> Interpreter*). + +**Then poke at it in the REPL:** ```bash python @@ -75,12 +93,10 @@ python >>> Sector(bering=1, level=2) # a typo is a TypeError, not a silent new key ``` -The real payoff of *declared* fields is in your **editor**: type `platform.` in a `.py` -file and VS Code (Pylance) offers every attribute, statically, before the code even runs — -that's what the declarations buy you. (In the bare `python` REPL you may also get attribute -completion, but it's a separate `readline`/`rlcompleter` feature that introspects the live -object at runtime; if `` doesn't complete, enable it for the session with -`import readline, rlcompleter; readline.parse_and_bind("tab: complete")`.) +The REPL can also complete attributes, but that's a separate `readline`/`rlcompleter` +feature that introspects the live object at runtime — not the static, declared-field +completion you saw in the editor. If `` doesn't complete, enable it for the session +with `import readline, rlcompleter; readline.parse_and_bind("tab: complete")`. Read [`docs/concepts/typed-vs-dicts.md`](docs/concepts/typed-vs-dicts.md) for what declared fields buy you over a dictionary, then look at how the builder rejects out-of-range values in diff --git a/examples/explore_platform.py b/examples/explore_platform.py new file mode 100644 index 0000000..10db168 --- /dev/null +++ b/examples/explore_platform.py @@ -0,0 +1,22 @@ +"""Scratch file for Adventure 2 — experience editor autocomplete on a typed object. + +Open this file in VS Code (the Codespace has Pylance), then follow the TODO below. +It is safe to edit freely; nothing else imports it. Run it any time with: + + python examples/explore_platform.py +""" + +from acoustic_dataset import build + +# `platform` is a fully-typed `Platform` built from the example input. Pylance knows +# its type from the function's return annotation — no need to run anything first. +platform = build.build_platform_from_file("examples/calculation_input.xml") + +# TODO: put your cursor at the end of the next line, after the dot, and type. +# VS Code should pop up the declared attributes (radiated_noise, sensors, ...). +# Keep drilling — `platform.radiated_noise.band[0].` completes too, all the way down. +# platform. + +# A couple of fully-typed accesses to confirm it ran (delete or extend these freely): +print("type:", type(platform).__name__) +print("first band centre frequency:", platform.radiated_noise.band[0].centre_frequency)