From 269bfd962b64ac1b01ecfadeb076496fa19979b1 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Fri, 9 Oct 2026 14:52:02 -0500 Subject: [PATCH 1/6] Pin what a list[float] message parameter receives today: one atom, as a symbol (9.1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Before plan 9.1 changes it — a last parameter hinted list[...] or np.ndarray is to take the remaining atoms — the test states today's behavior: one numeric atom arrives as the empty symbol, and more atoms than parameters are refused. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- core/tests/CMakeLists.txt | 1 + core/tests/python/list_params.py | 8 +++++++ core/tests/test_output.cpp | 37 ++++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+) create mode 100644 core/tests/python/list_params.py create mode 100644 core/tests/test_output.cpp diff --git a/core/tests/CMakeLists.txt b/core/tests/CMakeLists.txt index 0bfa08d..970df17 100644 --- a/core/tests/CMakeLists.txt +++ b/core/tests/CMakeLists.txt @@ -37,6 +37,7 @@ add_executable(tap_python_core_tests test_channels.cpp test_worker.cpp test_console.cpp + test_output.cpp ) target_link_libraries(tap_python_core_tests PRIVATE tap::python Python3::Python Catch2::Catch2WithMain) diff --git a/core/tests/python/list_params.py b/core/tests/python/list_params.py new file mode 100644 index 0000000..85f38e1 --- /dev/null +++ b/core/tests/python/list_params.py @@ -0,0 +1,8 @@ +# Test fixture: message parameters hinted list[...] or np.ndarray (plan 9.1). + + +class list_params: + got: str = "" + + def take(self, values: list[float]) -> None: + self.got = repr(values) diff --git a/core/tests/test_output.cpp b/core/tests/test_output.cpp new file mode 100644 index 0000000..44d4e78 --- /dev/null +++ b/core/tests/test_output.cpp @@ -0,0 +1,37 @@ +/// @file test_output.cpp +/// @brief tap.python's output (plan 9.1): what a method returns, converted for the host's outlets; +/// the outlet count from the return hints; the audio option; list parameters. +// SPDX-License-Identifier: MIT +// Copyright 2022-2026 Timothy Place. + +#include +#include + +#include "support.h" + +using namespace tap::python; +using namespace tap::python::test; + +namespace { + + std::string got(processor& p) { + return std::get(*p.get_attribute("got", value_type::symbol)); + } + +} // namespace + +// Pinned before plan 9.1 changes it: a parameter hinted list[float] is not a list to the bridge, so +// one atom arrives coerced to a symbol — a number becomes the empty symbol, as atom_getsym() says — +// and more atoms than parameters are refused. +SCENARIO("Today, a message parameter hinted list[float] receives one atom as a symbol") { + ensure_runtime(); + log_capture log; + processor p{"list_params", log.sink()}; + REQUIRE(p.load()); + + REQUIRE(p.call("take", std::vector{1.5})); + CHECK(got(p) == "''"); + + CHECK_FALSE(p.call("take", std::vector{1.0, 2.0, 3.0})); + CHECK(log.contains("take: expected 1 argument(s), got 3", log_level::error)); +} From 7440431dd3423dc2e98711359351f1df931a2934 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Fri, 9 Oct 2026 15:02:28 -0500 Subject: [PATCH 2/6] The core for tap.python: what a method returns, as output; outlets from the hints; the audio option (9.1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What docs/TAP-PYTHON-PLAN.md's "The core" asks of 9.1, host-independent and tested here: - value.h: output_item (a selector and its atoms: a number, a list, or the message a selector names) and output, what each outlet outputs from one call. - processor::call_with_output() beside call(): the method's result converted by the output table — None nothing; a bool, number or str one value (a str as `symbol `, plan 9.0); a list, unhinted tuple, range or 1-D array a list, or the message its first str names; a 0-d array its value; a return hinted tuple[...] one value per outlet. What an outlet cannot carry — an integer past 64 bits, a list holding None or a list, a dict, a 2-D array — is reported and nothing is output. numpy's types are known by name, without importing numpy, and no CPython data symbol is used (the delay-loaded Windows external). - message_info::return_count and spreads, and outlet_count(): the widest return hint. The support module's return_shape() splits a hint written as a string at its top level only (audit m4). - The constructor's bind_audio: off (tap.python), process() and prepare() are messages like any other; a tuple hint that does not say how many values is output as a list, and said once. - A last parameter hinted list[...] or np.ndarray takes the atoms left after the others — for tap.python~ too: a change to the class contract, pinned by the test first and recorded in CHANGELOG.md (2.0.0) and the ReadMe. - Announce-once per kind (audit M5): what depends on how an object binds the class — a name its host reserves, process() and tuple returns — is said once per (save, kind), even when an object of the other kind ran the file; the Loaded line stays once per save and says what that object bound ("5 messages, 2 outlets"). test_output.cpp: the output table as one data-driven test over its edges (64-bit limits, NaN and infinity, numpy scalars, 0-d and 2-D arrays, nested lists), tuple hints of each length against results of the wrong length, outlet counts from object and string hints, both kinds on one file, the list and array parameters, a raising method, and a call racing a reload. tap.python~'s battery is unchanged and green (108/108). Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- CHANGELOG.md | 18 + ReadMe.md | 2 +- core/include/tap/python/processor.h | 635 ++++++++++++++++++++++++---- core/include/tap/python/runtime.h | 77 +++- core/include/tap/python/value.h | 19 + core/tests/python/array_params.py | 13 + core/tests/python/kinds.py | 13 + core/tests/python/list_params.py | 24 +- core/tests/python/outputs.py | 93 ++++ core/tests/python/wide.py | 13 + core/tests/python/wide_strings.py | 19 + core/tests/test_output.cpp | 446 ++++++++++++++++++- 12 files changed, 1273 insertions(+), 99 deletions(-) create mode 100644 core/tests/python/array_params.py create mode 100644 core/tests/python/kinds.py create mode 100644 core/tests/python/outputs.py create mode 100644 core/tests/python/wide.py create mode 100644 core/tests/python/wide_strings.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 6501597..d7b61f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,24 @@ breaking changes to the contract were allowed where they bought correctness (D5 `docs/PRODUCTION-PLAN.md`); each is recorded here. From 1.0.0, a change to the class contract is a major version. +## 2.0.0 — unreleased + +The release that brings `tap.python`, a Python class as a Max object without audio +(`docs/TAP-PYTHON-PLAN.md`, Phase 9 of the production plan). Its entries are added as the phase +lands. + +### Changed — a last parameter hinted `list[…]` or `np.ndarray` takes the remaining atoms + +- **A message's last parameter hinted `list[float]`, `list[int]`, `list[str]`, `list` or + `np.ndarray`** — with no `*args` after it — now takes every atom left after the parameters before + it: as one list, each atom converted by the element hint as a single parameter's would be, or as + a float64 array. `def taps(self, values: list[float])` answers `taps 0.1 0.2 0.3`, and `def + list(self, values: np.ndarray)` a whole list message. With no atoms left it is an empty list, or + its default if it has one. Before, such a parameter took one atom, converted as a `str` — so a + number arrived as the empty string — and a message with more atoms than the method has + parameters was refused. A class that relied on that now receives a list. It is a change to the + class contract, and so the release is 2.0.0 (plan 9.1; decided 2026-10-09). + ## 1.0.2 — 2026-10-08 1.0.1 was tagged but never released: its Windows package still had the first fault below. Its diff --git a/ReadMe.md b/ReadMe.md index bcd00be..ff2422b 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -89,7 +89,7 @@ Without a runtime the object still loads, and says in the Max console what is mi Python sources live in the package's `python` folder. `[tap.python~ name]` loads `python/name.py` and instantiates the class `name` defined in it (the file, class, and argument must share the same name, which must be a valid Python identifier; with no argument, `default` is loaded). The file is loaded by its path, never through `import`, so a file named like a standard-library module (`random.py`, `json.py`) works and does not shadow that module for anyone else. Other files in the `python` folder can be imported by your class as helper modules (the folder is on `sys.path`, after the standard library) — a helper is imported afresh whenever a class file that changed is saved (the loader forgets every module imported from the folder first), but a save of the helper alone is not watched: save the class file too, with a change, to pick it up. No bytecode is written for anything in the folder. Text is UTF-8: the interpreter runs in Python's UTF-8 mode, so `open()` reads and writes UTF-8 unless you pass another `encoding`, whatever the machine's locale. - **Attributes** — class-level annotated fields (e.g. via `attrs`) become Max attributes. `int` maps to a Max `long`, `float` to `float64`, `bool` to an on/off `long` (your field receives a real `bool`), anything else to a symbol; `Optional[X]`, `X | None`, `Annotated[X, …]` and `Final[X]` count as `X`, a subclass of one of those types (`np.float64`, an `IntEnum`) as its base, and numpy's scalar types (`np.int64`, `np.bool_`) as the kind they hold. A union of several kinds (`float | int`, `str | float`) is a symbol attribute in Max whose value reaches your field as the atom carried it — an `int`, `float` or `str` — like an unannotated parameter. Names starting with `_` are private, and `ClassVar`s are not fields. If a hint cannot be resolved (say a name imported only under `TYPE_CHECKING`), the console says so and the annotation is read as written. -- **Messages** — public methods (including classmethods and staticmethods) become Max messages, called according to their signature: parameters with defaults are optional, `*args` takes any number of arguments, and a keyword-only parameter must have a default (a method with a required keyword-only parameter is not exposed). Argument hints (`int`, `float`, `bool`, `str`) drive the conversion from Max atoms; an unannotated parameter receives the atom as it is (an `int`, `float` or `str`). Methods named `int`, `float`, `symbol`, and `bang` map to those standard Max messages. Names Max or the object handle themselves (`filechanged`, `dsp64`, `notify`, `assist`, `loadbang`, `dblclick`, `anything`, …, and the object's own attributes `mode`, `latency` and `latencysamples`) are not exposed — as methods, or as fields; the console names any skipped this way so you can rename it. +- **Messages** — public methods (including classmethods and staticmethods) become Max messages, called according to their signature: parameters with defaults are optional, `*args` takes any number of arguments, and a keyword-only parameter must have a default (a method with a required keyword-only parameter is not exposed). Argument hints (`int`, `float`, `bool`, `str`) drive the conversion from Max atoms; an unannotated parameter receives the atom as it is (an `int`, `float` or `str`). A last parameter hinted `list[float]` (or `list[int]`, `list[str]`, `list`) or `np.ndarray`, with no `*args` after it, takes every atom left after the others — as one list, or a float64 array — so `def taps(self, values: list[float])` answers `taps 0.1 0.2 0.3`; with none left it is empty, or its default. Methods named `int`, `float`, `symbol`, and `bang` map to those standard Max messages. Names Max or the object handle themselves (`filechanged`, `dsp64`, `notify`, `assist`, `loadbang`, `dblclick`, `anything`, …, and the object's own attributes `mode`, `latency` and `latencysamples`) are not exposed — as methods, or as fields; the console names any skipped this way so you can rename it. - **Audio** — a method `process()` runs on the signal, in one of two forms chosen by its type hint: - `process(self, x: np.ndarray) -> np.ndarray` is called **once per signal vector** with a numpy array of the input and must return an array of the same length (any numeric dtype, or a list; it is converted). This is the form to use for anything that must run in real time — see `python/numpy_gain.py`, and `python/numpy_allpass.py` for a filter with feedback. The input array is reused from one call to the next: copy it if you want to keep it. - `process(self, x: float) -> float` is called **once per sample** — simplest for sketching; the call is cheap, but every line of Python in it runs once per sample (see [the performance note](#a-note-on-performance)). diff --git a/core/include/tap/python/processor.h b/core/include/tap/python/processor.h index 5f9b7b8..e105855 100644 --- a/core/include/tap/python/processor.h +++ b/core/include/tap/python/processor.h @@ -16,6 +16,11 @@ // - an optional `prepare(self, sample_rate: float, vector_size: int)` is told the audio settings // (prepare()) before the instance first processes audio, and again whenever they change // +// That is the audio object, tap.python~. With bind_audio off — tap.python, a Python class as a Max +// object without audio (docs/TAP-PYTHON-PLAN.md) — process() and prepare() are ordinary messages, +// and what a method returns is what the object outputs: call_with_output() converts the result for +// the host's outlets (see output_item), and the return hints say how many outlets (outlet_count()). +// // Threads: load(), prepare(), flush_reports() and the destructor run on the host's main thread; // set_attribute(), get_attribute() and call() on any non-audio thread; process() on the audio // thread. Each takes the GIL. A processor that is not loaded (import, class lookup or construction @@ -63,12 +68,29 @@ namespace tap::python { value_type type; }; - /// A public method of the user's class, callable through call(). + /// How a method's last positional parameter takes its atoms. + enum class rest_kind { + none, ///< one atom, as every other parameter does + list, ///< hinted list[...]: all the atoms left after the others, as one list + array, ///< hinted np.ndarray: all the atoms left after the others, as one float64 array + }; + + /// A public method of the user's class, callable through call() and call_with_output(). struct message_info { std::string name; std::vector argument_types; ///< one per positional parameter, in order std::size_t required{}; ///< how many of those have no default std::optional variadic; ///< the type of *args, if the method takes it + /// Whether the last positional parameter takes all the atoms left after the others: when it is + /// hinted list[...] or np.ndarray and the method takes no *args (plan 9.1). Its elements are + /// converted to rest_type (a list[float]'s to real; an array's are always real). + rest_kind rest{rest_kind::none}; + value_type rest_type{value_type::any}; + /// How many outlets the method's result fills: n when its return is hinted tuple[...] with n + /// members (spreads: one value per outlet), 1 otherwise — a tuple of unsaid length is output as + /// a list from one outlet. + std::size_t return_count{1}; + bool spreads{}; }; class processor { @@ -86,12 +108,17 @@ namespace tap::python { /// its class registered), which a Python method or field must not /// replace either: reserved like the list, with the same diagnostic. /// Called on the main thread during load(), with the GIL held. + /// @param bind_audio true for an audio object (tap.python~): process() is the audio + /// callback and prepare() its settings hook. False for an object + /// without audio (tap.python): both are messages like any other, + /// has_process() stays false and prepare() does nothing. explicit processor(std::string source_name, log_function log = {}, std::vector reserved_messages = {}, std::function report_ready = {}, - std::function host_answers = {}) + std::function host_answers = {}, const bool bind_audio = true) : m_source_name{std::move(source_name)} , m_log{std::move(log)} , m_reserved_messages{std::move(reserved_messages)} + , m_bind_audio{bind_audio} , m_report_ready{std::move(report_ready)} , m_host_answers{std::move(host_answers)} {} @@ -116,9 +143,22 @@ namespace tap::python { /// True while a class instance exists (attributes and messages are live). bool loaded() const noexcept { return m_instance.load() != nullptr; } - /// True while process() is bound to the class's process() method. + /// True while process() is bound to the class's process() method (never without bind_audio). bool has_process() const noexcept { return m_process_function.load() != nullptr; } + /// Whether process() and prepare() are bound as audio (the constructor's bind_audio). + bool binds_audio() const noexcept { return m_bind_audio; } + + /// How many outlets the class's messages need: the most any of them fills (message_info's + /// return_count), and at least one. Main thread, after load(). + std::size_t outlet_count() const noexcept { + std::size_t count = 1; + for (const auto& message : m_messages) { + count = (std::max)(count, message.info.return_count); + } + return count; + } + /// True when the bound process() takes a whole vector (hinted np.ndarray), false when it is /// called per sample. Main thread, after load(). bool block_mode() const noexcept { return m_block_mode; } @@ -194,6 +234,10 @@ namespace tap::python { return false; } Py_XSETREF(m_module, module); + // 9.1 (audit M5): what depends on how this kind of object binds the class — a name its + // host reserves, how process() or a tuple return binds — is said once per kind, so even + // when an object of the other kind ran the file + m_announcing_kind = announce_due(); PyObject* py_class = PyObject_GetAttrString(m_module, m_source_name.c_str()); // strong if (!py_class) { @@ -398,72 +442,43 @@ namespace tap::python { /// Call the method `name` with `args`, each coerced to its parameter's hinted type (an /// unannotated parameter takes the value as it is). The count must fit the method's /// signature: its required positional parameters at least, all of them at most unless it - /// takes *args. Exceptions are printed to the console. Returns true when the method was - /// called and returned normally. + /// takes *args, or its last parameter is hinted list[...] or np.ndarray and takes all the + /// atoms left after the others (plan 9.1). Exceptions are printed to the console. Returns true + /// when the method was called and returned normally; what it returned is dropped. bool call(const std::string_view name, const std::span args) { if (!loaded()) { return false; } - - gil_lock lock; - - const auto found = std::find_if(m_messages.begin(), m_messages.end(), - [&](const bound_message& m) { return m.info.name == name; }); - if (found == m_messages.end()) { - return false; - } - - // Take our own copies and references of everything the call uses before anything that - // could run Python code (even an allocation can trigger a GC finalizer): that could let - // a reload on another thread replace the message list under us. - const message_info info = found->info; - PyObject* function = found->function; // bound: call with the arguments only - Py_INCREF(function); - - const auto positional = info.argument_types.size(); - if (args.size() < info.required || (!info.variadic && args.size() > positional)) { - Py_DECREF(function); - std::string expected; - if (info.variadic) { - expected = "at least " + std::to_string(info.required); - } - else if (info.required == positional) { - expected = std::to_string(positional); - } - else { - expected = std::to_string(info.required) + " to " + std::to_string(positional); - } - log(log_level::error, - std::string{name} + ": expected " + expected + " argument(s), got " + std::to_string(args.size())); + gil_lock lock; + message_info info; + PyObject* result = invoke(name, args, info); + if (!result) { return false; } + Py_DECREF(result); + return true; + } - std::vector call_args; - call_args.reserve(args.size()); - bool converted = true; - for (std::size_t i = 0; i < args.size(); ++i) { - const value_type type = i < positional ? info.argument_types[i] : *info.variadic; - PyObject* item = to_python(coerce(args[i], type), type); - if (!item) { - converted = false; - break; - } - call_args.push_back(item); - } - - PyObject* result = - converted ? PyObject_Vectorcall(function, call_args.data(), call_args.size(), nullptr) : nullptr; - for (PyObject* arg : call_args) { - Py_DECREF(arg); + /// Call the method `name` as call() does, and convert what it returned for the host's outlets + /// (tap.python, plan 9.1): None outputs nothing; a bool, a number or a str one value; a list, + /// an unhinted tuple, a range or a 1-D np.ndarray a list, or the message its first element + /// names when that is a str; a return hinted tuple[...] with n members one value per outlet. + /// Anything else, or a value an outlet cannot carry (an integer past 64 bits, a list holding + /// None or another list), is reported and nothing is output. Empty when nothing is output — + /// None, an exception (printed), or a value that does not convert (reported). + output call_with_output(const std::string_view name, const std::span args) { + if (!loaded()) { + return {}; } - Py_DECREF(function); - + gil_lock lock; + message_info info; + PyObject* result = invoke(name, args, info); if (!result) { - report_exception(); - return false; + return {}; } + output out = to_output(result, info); Py_DECREF(result); - return true; + return out; } /// The audio callback: `input_count` input channels and `output_count` output channels of @@ -536,7 +551,8 @@ namespace tap::python { std::string m_source_name; log_function m_log; std::vector m_reserved_messages; - PyObject* m_module{}; // strong; main thread only + bool m_bind_audio{true}; // process() and prepare() are audio (tap.python~) + PyObject* m_module{}; // strong; main thread only // Written only under the GIL; atomic so the audio thread's lock-free "is anything // bound?" check (and loaded()) is well-defined. std::atomic m_instance{}; // strong @@ -548,9 +564,10 @@ namespace tap::python { bool m_block_mode{}; std::size_t m_inputs{1}; // the bound process()'s inputs and outputs std::size_t m_outputs{1}; - std::vector m_input_names; // main thread only - bool m_announcing{}; // this load() ran the file: see announce() - std::atomic m_loads{}; // successful load()s + std::vector m_input_names; // main thread only + bool m_announcing{}; // this load() ran the file: see announce() + bool m_announcing_kind{}; // this kind still owes the class's binding: see announce_kind() + std::atomic m_loads{}; // successful load()s // The np.ndarray each input arrives in, reused every vector: strong, its buffer held so its // memory cannot move. struct block_buffer { @@ -602,8 +619,43 @@ namespace tap::python { } } - /// How the class's audio is bound, for the line load() announces. + /// Log something true of how this kind of object binds the class — a name its host + /// reserves, how process() or a tuple return binds: once per kind (see announce_due()). + void announce_kind(const log_level level, const std::string& text) const { + if (m_announcing_kind) { + log(level, text); + } + } + + /// Whether this kind of object (audio or control) still owes what is true of the class as it + /// binds it, for the source executed last: the support module's announce_due(). Caller holds + /// the GIL; main thread, in load(). + bool announce_due() const { + PyObject* function = detail::support("announce_due"); // borrowed + PyObject* module = PyUnicode_FromString(("_tap_python_" + m_source_name).c_str()); + PyObject* kind = PyUnicode_FromString(m_bind_audio ? "audio" : "control"); + PyObject* result = + function && module && kind ? PyObject_CallFunctionObjArgs(function, module, kind, nullptr) : nullptr; + Py_XDECREF(module); + Py_XDECREF(kind); + if (!result) { + PyErr_Clear(); + return m_announcing; + } + const bool due = PyObject_IsTrue(result) == 1; + Py_DECREF(result); + return due; + } + + /// How the class is bound, for the line load() announces: its audio, or (without bind_audio) + /// its messages and outlets. std::string binding_description() const { + if (!m_bind_audio) { + const auto messages = m_messages.size(); + const auto outlets = outlet_count(); + return std::to_string(messages) + (messages == 1 ? " message, " : " messages, ") + + std::to_string(outlets) + (outlets == 1 ? " outlet" : " outlets"); + } if (!has_process()) { return "no process() bound, so the object outputs silence"; } @@ -1161,6 +1213,387 @@ namespace tap::python { Py_DECREF(result); } + // ---- messages, and what they output (plan 9.1) ------------------------------------------ + + /// Find the method `name`, convert `args` for its signature and call it: a new reference to + /// what it returned, or nullptr — an exception (printed), or a count that does not fit the + /// signature (logged). `info` is set to the method's description. Caller holds the GIL. + PyObject* invoke(const std::string_view name, const std::span args, message_info& info) { + const auto found = std::find_if(m_messages.begin(), m_messages.end(), + [&](const bound_message& m) { return m.info.name == name; }); + if (found == m_messages.end()) { + return nullptr; + } + + // Take our own copies and references of everything the call uses before anything that + // could run Python code (even an allocation can trigger a GC finalizer): that could let + // a reload on another thread replace the message list under us. + info = found->info; + PyObject* function = found->function; // bound: call with the arguments only + Py_INCREF(function); + + // A rest parameter (list[...] or np.ndarray, last) takes the atoms after the others, so + // the call may have as many as it likes, and needs no atom for the rest parameter itself + const auto positional = info.argument_types.size(); + const bool rest = info.rest != rest_kind::none; + const auto fixed = rest ? positional - 1 : positional; // the parameters taking one atom each + const auto minimum = rest ? (std::min)(info.required, fixed) : info.required; + if (args.size() < minimum || (!rest && !info.variadic && args.size() > positional)) { + Py_DECREF(function); + std::string expected; + if (rest || info.variadic) { + expected = "at least " + std::to_string(minimum); + } + else if (info.required == positional) { + expected = std::to_string(positional); + } + else { + expected = std::to_string(info.required) + " to " + std::to_string(positional); + } + log(log_level::error, + std::string{name} + ": expected " + expected + " argument(s), got " + std::to_string(args.size())); + return nullptr; + } + + std::vector call_args; + call_args.reserve(args.size() + 1); + bool converted = true; + const auto singles = rest ? (std::min)(args.size(), fixed) : args.size(); + for (std::size_t i = 0; i < singles; ++i) { + const value_type type = i < positional ? info.argument_types[i] : *info.variadic; + PyObject* item = to_python(coerce(args[i], type), type); + if (!item) { + converted = false; + break; + } + call_args.push_back(item); + } + // The rest parameter: with no atoms left it is an empty list when it has no default (it is + // required), and left to its default when it has one. + if (converted && rest && (args.size() > fixed || info.required == positional)) { + const auto atoms = args.size() > fixed ? args.subspan(fixed) : std::span{}; + PyObject* collected = collect(atoms, info.rest, info.rest_type); + if (collected) { + call_args.push_back(collected); + } + else { + converted = false; + } + } + + PyObject* result = + converted ? PyObject_Vectorcall(function, call_args.data(), call_args.size(), nullptr) : nullptr; + for (PyObject* arg : call_args) { + Py_DECREF(arg); + } + Py_DECREF(function); + + if (!result) { + report_exception(); + return nullptr; + } + return result; + } + + /// The atoms a rest parameter takes: a list of `type` values, or (an array) a float64 + /// np.ndarray. A new reference, or nullptr with an error set. Caller holds the GIL. + static PyObject* collect(const std::span atoms, const rest_kind kind, const value_type type) { + const auto element = kind == rest_kind::array ? value_type::real : type; + PyObject* list = PyList_New(static_cast(atoms.size())); + if (!list) { + return nullptr; + } + for (std::size_t i = 0; i < atoms.size(); ++i) { + PyObject* item = to_python(coerce(atoms[i], element), element); + if (!item) { + Py_DECREF(list); + return nullptr; + } + PyList_SET_ITEM(list, static_cast(i), item); // steals the reference + } + if (kind == rest_kind::list) { + return list; + } + PyObject* array = nullptr; + if (PyObject* numpy = PyImport_ImportModule("numpy")) { + array = PyObject_CallMethod(numpy, "array", "Os", list, "float64"); + Py_DECREF(numpy); + } + Py_DECREF(list); + return array; + } + + /// What `result` — returned by the method `info` — outputs: see call_with_output(). What does + /// not convert is reported, and nothing is output. Caller holds the GIL. The conversion can + /// run Python code (an array's tolist(), a number's __index__), which may let another thread + /// in: it works on its own reference and its own copy of `info`. + output to_output(PyObject* result, const message_info& info) const { + std::string why; + if (!info.spreads) { + auto item = to_output_item(result, why); + if (!why.empty()) { + report_output(info.name, why); + return {}; + } + if (!item) { + return {}; + } + output out; + out.push_back(std::move(item)); + return out; + } + + // a return hinted tuple[...] of n members: one value per outlet + PyObject* items = sequence_items(result); + const auto count = items ? static_cast(PyList_GET_SIZE(items)) : std::size_t{0}; + if (!items || count != info.return_count) { + report_output(info.name, "is hinted to return " + std::to_string(info.return_count) + + (info.return_count == 1 ? " value" : " values") + + ", one per outlet, but returned " + + (items ? std::to_string(count) + " value(s)" : described(result))); + Py_XDECREF(items); + return {}; + } + output out(count); + bool any = false; + for (std::size_t k = 0; k < count; ++k) { + out[k] = to_output_item(PyList_GET_ITEM(items, static_cast(k)), why); + if (!why.empty()) { + Py_DECREF(items); + report_output(info.name, why + " as its value " + std::to_string(k + 1)); + return {}; + } + any = any || out[k].has_value(); + } + Py_DECREF(items); + if (!any) { + return {}; + } + return out; + } + + void report_output(const std::string& name, const std::string& why) const { + log(log_level::error, name + "() " + why + " — nothing output"); + } + + /// One value as an outlet outputs it: nothing for None; a number, or `symbol ` for a str; + /// a sequence as a list, or as the message its first element names when that is a str (an + /// empty one outputs nothing). On a value an outlet cannot carry, `why` says so. Caller holds + /// the GIL. + std::optional to_output_item(PyObject* object, std::string& why) const { + if (object == detail::none()) { + return std::nullopt; + } + if (is_ndarray(object)) { + const auto dimensions = array_dimensions(object); + if (dimensions == 0) { // a 0-d array is its value + PyObject* item = PyObject_CallMethod(object, "item", nullptr); + if (!item) { + PyErr_Clear(); + why = "returned a 0-d np.ndarray whose value could not be read"; + return std::nullopt; + } + auto converted = to_output_item(item, why); + Py_DECREF(item); + return converted; + } + if (dimensions != 1) { + why = "returned a " + std::to_string(dimensions) + + "-D np.ndarray, which an outlet cannot carry (a 1-D one is a list)"; + return std::nullopt; + } + } + if (PyObject* items = sequence_items(object)) { + const auto count = static_cast(PyList_GET_SIZE(items)); + std::vector atoms; + atoms.reserve(count); + for (std::size_t i = 0; i < count; ++i) { + value atom; + std::string what; + if (!to_atom(PyList_GET_ITEM(items, static_cast(i)), atom, what)) { + Py_DECREF(items); + why = "returned a list holding " + what + " (item " + std::to_string(i + 1) + + "), which an outlet cannot carry"; + return std::nullopt; + } + atoms.push_back(std::move(atom)); + } + Py_DECREF(items); + if (atoms.empty()) { + return std::nullopt; + } + if (const auto* selector = std::get_if(&atoms.front())) { // Max's own rule + output_item message{*selector, {}}; + message.atoms.assign(std::make_move_iterator(atoms.begin() + 1), + std::make_move_iterator(atoms.end())); + return message; + } + return output_item{std::string{"list"}, std::move(atoms)}; + } + value atom; + std::string what; + if (!to_atom(object, atom, what)) { + why = "returned " + what + ", which an outlet cannot carry"; + return std::nullopt; + } + if (std::holds_alternative(atom)) { // a str is symbol (decided by plan 9.0) + return output_item{std::string{"symbol"}, {std::move(atom)}}; + } + return output_item{std::nullopt, {std::move(atom)}}; + } + + /// One element of what a method returned, as an atom: a bool (numpy's too) as 0 or 1; an + /// integer (anything with __index__) as a 64-bit one; a real number (anything with __float__) + /// as a float, NaN and infinity included; a str as a symbol; a 0-d np.ndarray as its value. + /// False for anything else — None, a sequence, a value past 64 bits — and `what` names it. + /// Caller holds the GIL; never leaves an error set. + static bool to_atom(PyObject* object, value& atom, std::string& what) { + if (object == detail::none()) { + what = "None"; + return false; + } + if (is_bool(object)) { + const int truth = PyObject_IsTrue(object); + if (truth < 0) { + PyErr_Clear(); + what = described(object); + return false; + } + atom = std::int64_t{truth}; + return true; + } + if (is_ndarray(object)) { + if (array_dimensions(object) == 0) { + PyObject* item = PyObject_CallMethod(object, "item", nullptr); + if (!item) { + PyErr_Clear(); + what = described(object); + return false; + } + const bool converted = to_atom(item, atom, what); + Py_DECREF(item); + return converted; + } + what = described(object); + return false; + } + if (PyUnicode_Check(object)) { + atom = utf8(object); + return true; + } + if (PyList_Check(object) || PyTuple_Check(object) || is_range(object)) { + what = described(object); + return false; + } + if (PyIndex_Check(object)) { + PyObject* index = PyNumber_Index(object); + if (!index) { + PyErr_Clear(); + what = described(object); + return false; + } + int overflow = 0; + const long long integer = PyLong_AsLongLongAndOverflow(index, &overflow); + if (overflow != 0) { + PyObject* text = PyObject_Repr(index); + what = utf8(text) + " (past a 64-bit integer)"; + Py_XDECREF(text); + Py_DECREF(index); + return false; + } + Py_DECREF(index); + if (integer == -1 && PyErr_Occurred()) { + PyErr_Clear(); + what = described(object); + return false; + } + atom = std::int64_t{integer}; + return true; + } + const auto* number = Py_TYPE(object)->tp_as_number; + if (number && number->nb_float) { + const double real = PyFloat_AsDouble(object); + if (real == -1.0 && PyErr_Occurred()) { + PyErr_Clear(); + what = described(object); + return false; + } + atom = real; + return true; + } + what = described(object); + return false; + } + + /// A new reference to the items of a list, a tuple, a range or a 1-D np.ndarray, as a list; + /// nullptr, with no error set, for anything else. Caller holds the GIL. + static PyObject* sequence_items(PyObject* object) { + PyObject* items = nullptr; + if (is_ndarray(object)) { + if (array_dimensions(object) == 1) { + items = PyObject_CallMethod(object, "tolist", nullptr); + } + } + else if (PyList_Check(object) || PyTuple_Check(object) || is_range(object)) { + items = PySequence_List(object); + } + if (items && !PyList_Check(items)) { + Py_CLEAR(items); + } + if (!items) { + PyErr_Clear(); + } + return items; + } + + /// Whether `object`'s type, or one of its bases, has the name `name` (a static type's name + /// includes its module: "numpy.ndarray") — so numpy's types are known without importing it. + static bool is_kind_of(PyObject* object, const std::string_view name) { + const PyTypeObject* type = Py_TYPE(object); + if (name == type->tp_name) { + return true; + } + PyObject* bases = type->tp_mro; // a tuple of the type and its bases + if (!bases || !PyTuple_Check(bases)) { + return false; + } + for (Py_ssize_t i = 0; i < PyTuple_GET_SIZE(bases); ++i) { + if (name == reinterpret_cast(PyTuple_GET_ITEM(bases, i))->tp_name) { + return true; + } + } + return false; + } + + /// A Python bool, or numpy's (numpy.bool, numpy.bool_ before numpy 2). + static bool is_bool(PyObject* object) { + return Py_TYPE(object) == Py_TYPE(Py_GetConstantBorrowed(Py_CONSTANT_TRUE)) + || is_kind_of(object, "numpy.bool") || is_kind_of(object, "numpy.bool_"); + } + + static bool is_ndarray(PyObject* object) { return is_kind_of(object, "numpy.ndarray"); } + + static bool is_range(PyObject* object) { return std::string_view{Py_TYPE(object)->tp_name} == "range"; } + + /// An np.ndarray's number of dimensions, or -1. Caller holds the GIL; leaves no error set. + static long array_dimensions(PyObject* array) { + PyObject* ndim = PyObject_GetAttrString(array, "ndim"); + const long dimensions = ndim ? PyLong_AsLong(ndim) : -1; + Py_XDECREF(ndim); + if (PyErr_Occurred()) { + PyErr_Clear(); + return -1; + } + return dimensions; + } + + /// A value's type, for a report: "a dict", "an object", "a numpy.ndarray". + static std::string described(PyObject* object) { + const std::string name{Py_TYPE(object)->tp_name}; + const bool vowel = !name.empty() && std::string_view{"aeiouAEIOU"}.find(name[0]) != std::string_view::npos; + return (vowel ? "an " : "a ") + name; + } + bool is_reserved(const std::string& name) const { return std::find(m_reserved_messages.begin(), m_reserved_messages.end(), name) != m_reserved_messages.end() || (m_host_answers && m_host_answers(name)); @@ -1215,9 +1648,10 @@ namespace tap::python { continue; } if (is_reserved(name)) { // a host attribute or message has the name (plan 2.5) - announce(log_level::error, - "the field " + name - + " is reserved by the host and is not exposed as an attribute; rename the field"); + announce_kind( + log_level::error, + "the field " + name + + " is reserved by the host and is not exposed as an attribute; rename the field"); continue; } b.attributes.push_back({name, value_type_from_hint(kind)}); @@ -1231,6 +1665,7 @@ namespace tap::python { std::string kind; // the hint kind int parameter_kind{}; bool has_default{}; + std::string element_kind; // a list hint's elements' kind; 'any' otherwise }; struct signature { @@ -1266,7 +1701,7 @@ namespace tap::python { PyObject* p = PyList_GetItem(parameters, i); // borrowed sig.parameters.push_back({utf8(PyTuple_GetItem(p, 0)), utf8(PyTuple_GetItem(p, 1)), static_cast(PyLong_AsLong(PyTuple_GetItem(p, 2))), - PyObject_IsTrue(PyTuple_GetItem(p, 3)) == 1}); + PyObject_IsTrue(PyTuple_GetItem(p, 3)) == 1, utf8(PyTuple_GetItem(p, 4))}); } if (PyErr_Occurred()) { PyErr_Clear(); @@ -1276,7 +1711,8 @@ namespace tap::python { } /// Bind the instance's public methods as messages, process() as the audio callback and - /// prepare() as the settings hook. Caller holds the GIL. + /// prepare() as the settings hook — or, without bind_audio, those two as messages too. + /// Caller holds the GIL. void collect_messages(binding& b) const { PyObject* methods = call_support("methods", b.instance); if (!methods) { @@ -1298,16 +1734,17 @@ namespace tap::python { continue; } - if (name == "prepare") { + if (m_bind_audio && name == "prepare") { Py_INCREF(method); b.prepare_function = method; } - else if (name == "process") { + else if (m_bind_audio && name == "process") { bind_process(method, b); } else if (is_reserved(name)) { - announce(log_level::error, - name + "() is reserved by the host and is not exposed as a message; rename the method"); + announce_kind( + log_level::error, + name + "() is reserved by the host and is not exposed as a message; rename the method"); } else { bind_message(name, method, b); @@ -1333,8 +1770,8 @@ namespace tap::python { Py_XDECREF(owner); if (!plain) { Py_XDECREF(fn); - announce(log_level::error, "process() must be a regular instance method (not a classmethod or " - "staticmethod); audio is not bound"); + announce_kind(log_level::error, "process() must be a regular instance method (not a classmethod or " + "staticmethod); audio is not bound"); return; } // 2.4: the positional parameters are the signal inputs, all per vector (np.ndarray) or all @@ -1352,7 +1789,7 @@ namespace tap::python { var_inputs = var_inputs || p.parameter_kind == k_var_positional; } const auto fail = [&](const std::string& why) { - announce(log_level::error, "process() " + why + "; audio is not bound"); + announce_kind(log_level::error, "process() " + why + "; audio is not bound"); Py_DECREF(fn); }; if (var_inputs) { @@ -1382,15 +1819,17 @@ namespace tap::python { } /// Bind a public method as a message, described by its signature. A keyword-only parameter - /// without a default cannot be passed from the host, so such a method is not exposed. - /// Caller holds the GIL. + /// without a default cannot be passed from the host, so such a method is not exposed. A last + /// positional parameter hinted list[...] or np.ndarray takes the atoms left after the others + /// (plan 9.1), and a return hinted tuple[...] spreads over as many outlets. Caller holds the GIL. void bind_message(const std::string& name, PyObject* method, binding& b) const { const auto sig = describe(method, name + "()"); if (!sig) { return; } - message_info info{name, {}, 0, std::nullopt}; + message_info info{name, {}, 0, std::nullopt}; + const parameter* last = nullptr; // the last positional parameter for (const auto& p : sig->parameters) { switch (p.parameter_kind) { case k_positional_only: @@ -1399,15 +1838,16 @@ namespace tap::python { if (!p.has_default) { info.required = info.argument_types.size(); } + last = &p; break; case k_var_positional: info.variadic = value_type_from_hint(p.kind); break; case k_keyword_only: if (!p.has_default) { - announce(log_level::error, name + "() has a keyword-only parameter '" + p.name - + "' without a default, which a message cannot pass; it is not " - "exposed as a message"); + announce_kind(log_level::error, name + "() has a keyword-only parameter '" + p.name + + "' without a default, which a message cannot pass; it is " + "not exposed as a message"); return; } break; @@ -1415,6 +1855,39 @@ namespace tap::python { break; } } + if (last && !info.variadic) { + if (last->kind == "list") { + info.rest = rest_kind::list; + info.rest_type = value_type_from_hint(last->element_kind); + } + else if (last->kind == "ndarray") { + info.rest = rest_kind::array; + info.rest_type = value_type::real; + } + } + + // the outlets: a tuple[...] of n members is n, one value each; a tuple that does not say + // how many is output as a list from one, which an object without audio says once — rather + // than leaving the method out, so that a class written for tap.python~ still loads whole + if (sig->return_count > 1 || (sig->return_count == 1 && sig->return_kind == "tuple")) { + if (static_cast(sig->return_count) <= k_max_channels) { + info.return_count = static_cast(sig->return_count); + info.spreads = true; + } + else if (!m_bind_audio) { + announce_kind(log_level::error, + name + "() is hinted to return " + std::to_string(sig->return_count) + + " values, more than the " + std::to_string(k_max_channels) + + " outlets an object can have; it is output as a list from one outlet"); + } + } + else if (sig->return_count < 1 && !m_bind_audio) { + announce_kind(log_level::info, + name + + "() is hinted to return a tuple without saying how many values, so it is output as " + "a list from one outlet; to output one value per outlet, say them: " + "tuple[int, str]"); + } Py_INCREF(method); b.messages.push_back({std::move(info), method}); diff --git a/core/include/tap/python/runtime.h b/core/include/tap/python/runtime.h index f2400a9..eb5908f 100644 --- a/core/include/tap/python/runtime.h +++ b/core/include/tap/python/runtime.h @@ -343,11 +343,20 @@ namespace tap::python { // staticmethods — found without running descriptors, so a property getter never runs just // because the class was loaded. Each callable is bound: call it with the arguments only. // - // describe(callable) -> ([(name, kind, parameter_kind, has_default)], return_kind, error, - // return_count, return_element_kind). parameter_kind is inspect.Parameter.kind as an int. - // return_count is how many values a return hint declares: 1, or n for tuple[a, b, ...] (-1 - // when a tuple's length is not said: tuple, tuple[float, ...]); return_element_kind is the - // hint kind of the value, or of a tuple's first element. + // describe(callable) -> ([(name, kind, parameter_kind, has_default, element_kind)], + // return_kind, error, return_count, return_element_kind). parameter_kind is + // inspect.Parameter.kind as an int; element_kind is the kind of a list hint's elements + // ('float' for list[float], 'any' for a bare list or any other hint). return_count is how many + // values a return hint declares: 1, or n for tuple[a, b, ...] (-1 when a tuple's length is not + // said: tuple, tuple[float, ...]), a hint written as a string split only at its top level + // ('tuple[list[int], dict[str, int]]' is two); return_element_kind is the hint kind of the + // value, or of a tuple's first element. + // + // announce_due(module_name, kind) -> bool. Whether an object of `kind` ('audio' for + // tap.python~, 'control' for tap.python) still owes what is true of the class as that kind + // binds it — a name one host reserves and the other does not, how process() or a tuple + // return binds — for the source executed last: true once per (source, kind), so each kind + // says it once even when the other kind's object ran the save (plan 9.1, audit M5). // // WorkerStopped: raised into a process() that has not returned when its worker is stopped // (plan 8.3; worker.h). A BaseException, like KeyboardInterrupt, so that a class's @@ -448,6 +457,21 @@ def _split_union(text): parts.append(text[start:]) return [p.strip() for p in parts if p.strip() not in ('None', '')] +def _split_top(text): + """The comma-separated arguments of a hint, split at its top level only, as written: + 'list[int], dict[str, int]' is two.""" + parts, depth, start = [], 0, 0 + for i, c in enumerate(text): + if c in '[(': + depth += 1 + elif c in '])': + depth -= 1 + elif c == ',' and depth == 0: + parts.append(text[start:i]) + start = i + 1 + parts.append(text[start:]) + return [p.strip() for p in parts] + def _unwrap(hint): """Annotated[X, ...] and Final[X] are X, however deep.""" while True: @@ -537,7 +561,7 @@ def describe(fn): hints = {} parameters = [ (p.name, hint_kind(hints.get(p.name, inspect.Parameter.empty)), int(p.kind), - p.default is not inspect.Parameter.empty) + p.default is not inspect.Parameter.empty, element_kind(hints.get(p.name, inspect.Parameter.empty))) for p in inspect.signature(fn).parameters.values() ] returned = hints.get('return', inspect.Parameter.empty) @@ -556,7 +580,7 @@ def return_shape(hint): return return_shape(parts[0]) for prefix in ('typing.Tuple[', 'Tuple[', 'tuple['): if text.startswith(prefix) and text.endswith(']'): - parts = [p.strip() for p in text[len(prefix):-1].split(',')] + parts = _split_top(text[len(prefix):-1]) if '...' in parts or parts == ['']: return -1, 'any' return len(parts), hint_kind(parts[0]) @@ -574,6 +598,45 @@ def return_shape(hint): return -1, 'any' return len(args), hint_kind(args[0]) return 1, hint_kind(hint) + +_LIST = re.compile(r'(?:typing\.)?(?:List|list)\[(.*)\]') + +def element_kind(hint): + if hint is inspect.Parameter.empty: + return 'any' + if isinstance(hint, str): + text = hint.strip() + match = _OPTIONAL.fullmatch(text) + if match: + return element_kind(match.group(1)) + match = _WRAPPED.fullmatch(text) + if match: + return element_kind(_first_argument(match.group(1))) + parts = _split_union(text) + if len(parts) == 1 and parts[0] != text: + return element_kind(parts[0]) + match = _LIST.fullmatch(text) + return hint_kind(_first_argument(match.group(1))) if match else 'any' + hint = _unwrap(hint) + origin = typing.get_origin(hint) + if origin is typing.Union or origin is types.UnionType: + args = [a for a in typing.get_args(hint) if a is not type(None)] + return element_kind(args[0]) if len(args) == 1 else 'any' + if origin is list: + args = typing.get_args(hint) + return hint_kind(args[0]) if args else 'any' + return 'any' + +_announced = {} + +def announce_due(module_name, kind): + cached = _cache.get(module_name) + source = cached[0] if cached is not None else None + key = (module_name, kind) + if source is not None and _announced.get(key) is source: + return False + _announced[key] = source + return True )"; /// Create the support module (initialize() calls this with the GIL held). diff --git a/core/include/tap/python/value.h b/core/include/tap/python/value.h index d146507..e6dec37 100644 --- a/core/include/tap/python/value.h +++ b/core/include/tap/python/value.h @@ -12,9 +12,11 @@ #include #include #include +#include #include #include #include +#include namespace tap::python { @@ -25,6 +27,23 @@ namespace tap::python { /// One argument or attribute value: an integer, a real number, or a symbol (string). using value = std::variant; + /// One message for an outlet, converted from what a method returned (tap.python, plan 9.1): + /// - no selector: a single number, the one atom (in Max, outlet_int or outlet_float); + /// - the selector "list": a list, its elements the atoms (outlet_list); + /// - any other selector: the message it names, with the atoms as arguments (outlet_anything) — + /// a `str` is `symbol `, and a sequence whose first element is a `str` the message that + /// names. + struct output_item { + std::optional selector; + std::vector atoms; + + bool operator==(const output_item&) const = default; + }; + + /// What one call outputs, outlet by outlet: [0] is the leftmost, and an empty slot outputs + /// nothing. Empty when the call outputs nothing at all. + using output = std::vector>; + /// Map a type hint's kind (see the support module's hint_kind: Optional[X] is already X) to a /// value type: `int` → integer, `float` → real, `bool` → boolean, no hint → any, anything else → /// symbol. diff --git a/core/tests/python/array_params.py b/core/tests/python/array_params.py new file mode 100644 index 0000000..c4aad4d --- /dev/null +++ b/core/tests/python/array_params.py @@ -0,0 +1,13 @@ +# Test fixture: a message parameter hinted np.ndarray takes the atoms left after the others, as a +# float64 array (plan 9.1). +import numpy as np + + +class array_params: + got: str = "" + + def take(self, values: np.ndarray) -> None: + self.got = repr((type(values).__name__, values.dtype.name, values.tolist())) + + def scaled(self, gain: float, values: np.ndarray) -> np.ndarray: + return values * gain diff --git a/core/tests/python/kinds.py b/core/tests/python/kinds.py new file mode 100644 index 0000000..a46e8cb --- /dev/null +++ b/core/tests/python/kinds.py @@ -0,0 +1,13 @@ +# Test fixture: one file loaded by an audio object and an object without audio (plan 9.1, audit +# M5): each kind is told, once, what is true of the class as it binds it. + + +class kinds: + def dsp(self) -> None: # reserved by the audio host in the tests + pass + + def spread(self) -> tuple[int, ...]: # a tuple of unsaid length: a list, said once by tap.python + return 1, 2 + + def process(self, x: float) -> float: + return x diff --git a/core/tests/python/list_params.py b/core/tests/python/list_params.py index 85f38e1..03efce7 100644 --- a/core/tests/python/list_params.py +++ b/core/tests/python/list_params.py @@ -1,4 +1,5 @@ -# Test fixture: message parameters hinted list[...] or np.ndarray (plan 9.1). +# Test fixture: message parameters hinted list[...] — the last one takes the atoms left after the +# others (plan 9.1). class list_params: @@ -6,3 +7,24 @@ class list_params: def take(self, values: list[float]) -> None: self.got = repr(values) + + def ints(self, values: list[int]) -> None: + self.got = repr(values) + + def words(self, values: list[str]) -> None: + self.got = repr(values) + + def anything_list(self, values: list) -> None: + self.got = repr(values) + + def written(self, values: "list[int]") -> None: + self.got = repr(values) + + def after(self, first: int, values: list[float]) -> None: + self.got = repr((first, values)) + + def optional(self, values: list[float] | None = None) -> None: + self.got = repr(values) + + def not_last(self, values: list[float], *more) -> None: + self.got = repr((values, more)) diff --git a/core/tests/python/outputs.py b/core/tests/python/outputs.py new file mode 100644 index 0000000..2c30737 --- /dev/null +++ b/core/tests/python/outputs.py @@ -0,0 +1,93 @@ +# Test fixture: what a method returns, and what tap.python outputs for it (plan 9.1). Each method +# returns the value CASES names; numpy's cases are there when numpy is. +import enum + +try: + import numpy as np +except ImportError: + np = None + + +class Level(enum.IntEnum): + HIGH = 3 + + +CASES = { + "none": lambda: None, + "true": lambda: True, + "false": lambda: False, + "int": lambda: 60, + "negative": lambda: -5, + "int_max": lambda: 2**63 - 1, + "int_min": lambda: -(2**63), + "int_over": lambda: 2**63, + "int_under": lambda: -(2**63) - 1, + "int_enum": lambda: Level.HIGH, + "float": lambda: 1.5, + "nan": lambda: float("nan"), + "inf": lambda: float("inf"), + "str": lambda: "C", + "empty_str": lambda: "", + "digits": lambda: "60", + "spaced": lambda: "hello world", + "list": lambda: [1, 2.5, "x"], + "message": lambda: ["note", 60, 100], + "one_word": lambda: ["start"], + "empty_list": lambda: [], + "tuple": lambda: (1, 2), + "range": lambda: range(3), + "bools": lambda: [True, False], + "holding_none": lambda: [1, None], + "nested": lambda: [1, [2]], + "big_in_list": lambda: [2**64], + "dict": lambda: {"a": 1}, + "set": lambda: {1}, + "bytes": lambda: b"ab", + "generator": lambda: (i for i in range(2)), + "object": lambda: object(), + "pair": lambda: (60, "C"), + "list_pair": lambda: [60, "C"], + "none_slot": lambda: (None, "x"), + "all_none": lambda: (None, None), + "three": lambda: (1, 2, 3), + "slot_dict": lambda: (1, {}), + "slot_list": lambda: ([1, 2], "x"), + "one": lambda: (5,), +} +if np is not None: + CASES.update({ + "np_bool": lambda: np.bool_(True), + "np_int64": lambda: np.int64(7), + "np_uint8": lambda: np.uint8(200), + "np_uint64_max": lambda: np.uint64(2**64 - 1), + "np_float32": lambda: np.float32(0.5), + "np_float64": lambda: np.float64(0.25), + "np_nan": lambda: np.float64("nan"), + "np_array": lambda: np.array([1.0, 2.0]), + "np_int_array": lambda: np.array([1, 2]), + "np_bool_array": lambda: np.array([True, False]), + "np_str_array": lambda: np.array(["a", "b"]), + "np_0d": lambda: np.array(5.0), + "np_0d_int": lambda: np.array(3), + "np_2d": lambda: np.array([[1.0, 2.0]]), + "np_empty": lambda: np.array([]), + "np_in_list": lambda: [np.float32(0.5), np.int16(3), np.bool_(False)], + "array_in_list": lambda: [np.array([1.0])], + }) + + +class outputs: + def give(self, case: str): + return CASES[case]() + + def two(self, case: str) -> tuple[int, str]: + return CASES[case]() + + def one(self, case: str) -> tuple[int]: + return CASES[case]() + + def unsaid(self, case: str) -> tuple[int, ...]: + return CASES[case]() + + def boom(self) -> int: + raise ValueError("boom() raised on purpose") diff --git a/core/tests/python/wide.py b/core/tests/python/wide.py new file mode 100644 index 0000000..3bf59e3 --- /dev/null +++ b/core/tests/python/wide.py @@ -0,0 +1,13 @@ +# Test fixture: return hints that name several outlets (plan 9.1); see wide_strings.py for the same +# written as strings that cannot be resolved. + + +class wide: + def nested(self) -> tuple[list[int], dict[str, int]]: + return [1, 2], 3 + + def triple(self) -> tuple[int, int, int]: + return 1, 2, 3 + + def single(self) -> int: + return 1 diff --git a/core/tests/python/wide_strings.py b/core/tests/python/wide_strings.py new file mode 100644 index 0000000..8ef17cb --- /dev/null +++ b/core/tests/python/wide_strings.py @@ -0,0 +1,19 @@ +# Test fixture: wide.py's return hints as strings that cannot be resolved (a name imported only for +# type checking), so they are read as written: split at their top level only (plan 9.1, audit m4). +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from nowhere import Meta # noqa: F401 — never importable: forces the as-written path + + +class wide_strings: + def nested(self) -> tuple[list[Meta], dict[str, int]]: + return [1, 2], 3 + + def triple(self) -> tuple[int, int, int]: + return 1, 2, 3 + + def single(self) -> int: + return 1 diff --git a/core/tests/test_output.cpp b/core/tests/test_output.cpp index 44d4e78..488a6d0 100644 --- a/core/tests/test_output.cpp +++ b/core/tests/test_output.cpp @@ -1,12 +1,22 @@ /// @file test_output.cpp /// @brief tap.python's output (plan 9.1): what a method returns, converted for the host's outlets; -/// the outlet count from the return hints; the audio option; list parameters. +/// the outlet count from the return hints; the audio option; list parameters; what each kind +/// of object is told of a class they share. // SPDX-License-Identifier: MIT // Copyright 2022-2026 Timothy Place. +#include +#include +#include +#include +#include +#include #include +#include #include +#include + #include "support.h" using namespace tap::python; @@ -18,20 +28,438 @@ namespace { return std::get(*p.get_attribute("got", value_type::symbol)); } + output_item number(const std::int64_t i) { + return {std::nullopt, {i}}; + } + + output_item real(const double d) { + return {std::nullopt, {d}}; + } + + output_item symbol(const std::string& s) { + return {std::string{"symbol"}, {s}}; + } + + output_item list(std::vector atoms) { + return {std::string{"list"}, std::move(atoms)}; + } + + output_item message(const std::string& selector, std::vector atoms) { + return {selector, std::move(atoms)}; + } + + std::vector word(const std::string& text) { + return {text}; + } + + const message_info* find_message(const std::vector& messages, const std::string& name) { + for (const auto& m : messages) { + if (m.name == name) { + return &m; + } + } + return nullptr; + } + + /// Whether numpy is importable: its rows and fixtures need it. CI requires it. + bool numpy_importable() { + bool found = false; + { + gil_lock lock; + PyObject* numpy = PyImport_ImportModule("numpy"); + found = numpy != nullptr; + Py_XDECREF(numpy); + PyErr_Clear(); + } + if (std::getenv("TAP_PYTHON_TEST_REQUIRE_EXAMPLES")) { + REQUIRE(found); + } + return found; + } + + /// One row of the output table: what give(case) outputs from the one outlet, or what the report says. + struct row { + const char* name; + std::optional item; ///< nothing, when not set and there is no error + const char* error; ///< a fragment of the report, when the value does not convert + bool numpy; + }; + + constexpr auto k_max = (std::numeric_limits::max)(); + constexpr auto k_min = std::numeric_limits::lowest(); + + const std::vector k_rows = { + {"none", std::nullopt, nullptr, false}, + {"true", number(1), nullptr, false}, + {"false", number(0), nullptr, false}, + {"int", number(60), nullptr, false}, + {"negative", number(-5), nullptr, false}, + {"int_max", number(k_max), nullptr, false}, + {"int_min", number(k_min), nullptr, false}, + {"int_over", std::nullopt, + "give() returned 9223372036854775808 (past a 64-bit integer), which an outlet cannot carry", false}, + {"int_under", std::nullopt, + "give() returned -9223372036854775809 (past a 64-bit integer), which an outlet cannot carry", false}, + {"int_enum", number(3), nullptr, false}, + {"float", real(1.5), nullptr, false}, + {"inf", real(std::numeric_limits::infinity()), nullptr, false}, + {"str", symbol("C"), nullptr, false}, + {"empty_str", symbol(""), nullptr, false}, + {"digits", symbol("60"), nullptr, false}, + {"spaced", symbol("hello world"), nullptr, false}, + {"list", list({std::int64_t{1}, 2.5, std::string{"x"}}), nullptr, false}, + {"message", message("note", {std::int64_t{60}, std::int64_t{100}}), nullptr, false}, + {"one_word", message("start", {}), nullptr, false}, + {"empty_list", std::nullopt, nullptr, false}, + {"tuple", list({std::int64_t{1}, std::int64_t{2}}), nullptr, false}, + {"range", list({std::int64_t{0}, std::int64_t{1}, std::int64_t{2}}), nullptr, false}, + {"bools", list({std::int64_t{1}, std::int64_t{0}}), nullptr, false}, + {"holding_none", std::nullopt, "give() returned a list holding None (item 2), which an outlet cannot carry", + false}, + {"nested", std::nullopt, "give() returned a list holding a list (item 2)", false}, + {"big_in_list", std::nullopt, + "give() returned a list holding 18446744073709551616 (past a 64-bit integer) (item 1)", false}, + {"dict", std::nullopt, "give() returned a dict, which an outlet cannot carry — nothing output", false}, + {"set", std::nullopt, "give() returned a set", false}, + {"bytes", std::nullopt, "give() returned a bytes", false}, + {"generator", std::nullopt, "give() returned a generator", false}, + {"object", std::nullopt, "give() returned an object", false}, + {"np_bool", number(1), nullptr, true}, + {"np_int64", number(7), nullptr, true}, + {"np_uint8", number(200), nullptr, true}, + {"np_uint64_max", std::nullopt, "give() returned 18446744073709551615 (past a 64-bit integer)", true}, + {"np_float32", real(0.5), nullptr, true}, + {"np_float64", real(0.25), nullptr, true}, + {"np_array", list({1.0, 2.0}), nullptr, true}, + {"np_int_array", list({std::int64_t{1}, std::int64_t{2}}), nullptr, true}, + {"np_bool_array", list({std::int64_t{1}, std::int64_t{0}}), nullptr, true}, + {"np_str_array", message("a", {std::string{"b"}}), nullptr, true}, + {"np_0d", real(5.0), nullptr, true}, + {"np_0d_int", number(3), nullptr, true}, + {"np_2d", std::nullopt, "give() returned a 2-D np.ndarray, which an outlet cannot carry (a 1-D one is a list)", + true}, + {"np_empty", std::nullopt, nullptr, true}, + {"np_in_list", list({0.5, std::int64_t{3}, std::int64_t{0}}), nullptr, true}, + {"array_in_list", std::nullopt, "give() returned a list holding a numpy.ndarray (item 1)", true}, + }; + } // namespace -// Pinned before plan 9.1 changes it: a parameter hinted list[float] is not a list to the bridge, so -// one atom arrives coerced to a symbol — a number becomes the empty symbol, as atom_getsym() says — -// and more atoms than parameters are refused. -SCENARIO("Today, a message parameter hinted list[float] receives one atom as a symbol") { +// ---- what a method returns, as the outlets output it --------------------------------------------- + +SCENARIO("What a method returns is output by the table's rules (plan 9.1)") { ensure_runtime(); + const bool numpy = numpy_importable(); log_capture log; - processor p{"list_params", log.sink()}; + processor p{"outputs", log.sink(), {}, {}, {}, false}; + REQUIRE(p.load()); + + for (const auto& r : k_rows) { + if (r.numpy && !numpy) { + continue; + } + INFO("case " << r.name); + log.clear(); + const auto out = p.call_with_output("give", word(r.name)); + if (r.error) { + CHECK(out.empty()); + CHECK(log.contains(r.error, log_level::error)); + } + else if (r.item) { + CHECK(out == output{*r.item}); + CHECK(log.lines().empty()); + } + else { + CHECK(out.empty()); + CHECK(log.lines().empty()); + } + } + + THEN("a non-finite float passes through, as the atom Max can carry") { + const auto out = p.call_with_output("give", word("nan")); + REQUIRE(out.size() == 1); + REQUIRE(out[0]); + CHECK_FALSE(out[0]->selector); + CHECK(std::isnan(std::get(out[0]->atoms.at(0)))); + if (numpy) { + const auto from_numpy = p.call_with_output("give", word("np_nan")); + REQUIRE(from_numpy.size() == 1); + CHECK(std::isnan(std::get(from_numpy[0]->atoms.at(0)))); + } + } +} + +SCENARIO("A return hinted tuple[...] outputs one value per outlet; an unhinted tuple is a list") { + ensure_runtime(); + log_capture log; + processor p{"outputs", log.sink(), {}, {}, {}, false}; + REQUIRE(p.load()); + + CHECK(p.call_with_output("two", word("pair")) == output{number(60), symbol("C")}); + CHECK(p.call_with_output("two", word("list_pair")) == output{number(60), symbol("C")}); + CHECK(p.call_with_output("two", word("slot_list")) + == output{list({std::int64_t{1}, std::int64_t{2}}), symbol("x")}); + CHECK(p.call_with_output("one", word("one")) == output{number(5)}); + CHECK(p.call_with_output("give", word("pair")) == output{list({std::int64_t{60}, std::string{"C"}})}); + CHECK(p.call_with_output("give", word("tuple")) == output{list({std::int64_t{1}, std::int64_t{2}})}); + + THEN("None in a slot outputs nothing from that outlet, and None in every slot nothing at all") { + CHECK(p.call_with_output("two", word("none_slot")) == output{std::nullopt, symbol("x")}); + CHECK(p.call_with_output("two", word("all_none")).empty()); + } + THEN("a result that is not that many values is reported, and nothing is output") { + CHECK(p.call_with_output("two", word("three")).empty()); + CHECK( + log.contains("two() is hinted to return 2 values, one per outlet, but returned 3 value(s) — nothing output", + log_level::error)); + CHECK(p.call_with_output("two", word("int")).empty()); + CHECK( + log.contains("two() is hinted to return 2 values, one per outlet, but returned an int", log_level::error)); + CHECK(p.call_with_output("one", word("int")).empty()); + CHECK(log.contains("one() is hinted to return 1 value, one per outlet, but returned an int", log_level::error)); + } + THEN("a value in a slot that does not convert is reported, and nothing is output") { + CHECK(p.call_with_output("two", word("slot_dict")).empty()); + CHECK(log.contains("two() returned a dict, which an outlet cannot carry as its value 2", log_level::error)); + } + THEN("a tuple hint that does not say how many values outputs a list from one outlet") { + CHECK(p.call_with_output("unsaid", word("tuple")) == output{list({std::int64_t{1}, std::int64_t{2}})}); + } +} + +SCENARIO("A method that raises outputs nothing, and its traceback is printed") { + ensure_runtime(); + console().clear(); + processor p{"outputs", {}, {}, {}, {}, false}; + REQUIRE(p.load()); + CHECK(p.call_with_output("boom", {}).empty()); + CHECK(console().contains("boom() raised on purpose", log_level::error)); + CHECK(p.call_with_output("no_such_method", {}).empty()); +} + +// ---- how many outlets ------------------------------------------------------------------------------- + +SCENARIO("The outlet count is the widest return hint, as an object or as a string (plan 9.1, audit m4)") { + ensure_runtime(); + const auto* name = GENERATE("wide", "wide_strings"); + processor p{name, {}, {}, {}, {}, false}; + REQUIRE(p.load()); + + const auto messages = p.messages(); + const auto* nested = find_message(messages, "nested"); + const auto* triple = find_message(messages, "triple"); + const auto* single = find_message(messages, "single"); + REQUIRE(nested); + REQUIRE(triple); + REQUIRE(single); + CHECK(nested->return_count == 2); // tuple[list[int], dict[str, int]]: two, however it is written + CHECK(nested->spreads); + CHECK(triple->return_count == 3); + CHECK(single->return_count == 1); + CHECK_FALSE(single->spreads); + CHECK(p.outlet_count() == 3); + CHECK(p.call_with_output("nested", {}) == output{list({std::int64_t{1}, std::int64_t{2}}), number(3)}); +} + +SCENARIO("An object without audio announces what it bound: its messages and outlets") { + ensure_runtime(); + log_capture log; + processor p{"outputs", log.sink(), {}, {}, {}, false}; + forget_loaded("outputs"); // this load runs the file, so logs what is true of the class + REQUIRE(p.load()); + CHECK(p.outlet_count() == 2); + CHECK(log.contains("Loaded outputs.py: 5 messages, 2 outlets", log_level::info)); + CHECK(log.contains("unsaid() is hinted to return a tuple without saying how many values, so it is output as a list " + "from one outlet", + log_level::info)); + + AND_WHEN("the same file is loaded by an audio object") { + log_capture audio_log; + processor audio{"outputs", audio_log.sink()}; + forget_loaded("outputs"); + REQUIRE(audio.load()); + THEN("it says nothing of tuples, whose returns it drops") { + CHECK_FALSE(audio_log.contains("unsaid()", log_level::info)); + } + } +} + +// ---- the audio option ----------------------------------------------------------------------------- + +SCENARIO("Without bind_audio, process() and prepare() are messages like any other (plan 9.1)") { + ensure_runtime(); + processor p{"gain", {}, {}, {}, {}, false}; + REQUIRE(p.load()); + CHECK_FALSE(p.binds_audio()); + CHECK_FALSE(p.has_process()); + CHECK(find_message(p.messages(), "process") != nullptr); + CHECK(p.call_with_output("process", std::vector{0.5}) == output{real(0.5)}); + CHECK(all_equal(render(p, 1.0), 0.0)); // no audio callback: silence + + AND_WHEN("the class has a prepare()") { + processor prepared{"prepared", {}, {}, {}, {}, false}; + REQUIRE(prepared.load()); + prepared.prepare(48000.0, 64); // nothing to tell: it is a message + CHECK(prepared.call_with_output("process", std::vector{0.0}) == output{real(0.0)}); + CHECK(prepared.call_with_output("prepare", std::vector{44100.0, std::int64_t{32}}).empty()); + CHECK(prepared.call_with_output("process", std::vector{0.0}) == output{real(44100.0)}); + } + AND_WHEN("an audio object loads the same class") { + processor audio{"gain"}; + REQUIRE(audio.load()); + THEN("process() is its audio callback, as before") { + CHECK(audio.binds_audio()); + CHECK(audio.has_process()); + CHECK(find_message(audio.messages(), "process") == nullptr); + CHECK(all_equal(render(audio, 0.5), 0.5)); + } + } +} + +// ---- what each kind of object is told --------------------------------------------------------------- + +SCENARIO("Objects of two kinds sharing a file are each told once what is true of the class as they bind it " + "(plan 9.1, audit M5)") { + ensure_runtime(); + const bool control_first = GENERATE(true, false); + forget_loaded("kinds"); + log_capture control_log; + log_capture audio_log; + processor control{"kinds", control_log.sink(), {}, {}, {}, false}; + processor audio{"kinds", audio_log.sink(), {"dsp"}}; + if (control_first) { + REQUIRE(control.load()); // runs the file + REQUIRE(audio.load()); // shares that execution + } + else { + REQUIRE(audio.load()); + REQUIRE(control.load()); + } + + THEN("the Loaded line is said once, by the object that ran the file, for what it bound") { + auto& runner = control_first ? control_log : audio_log; + auto& other = control_first ? audio_log : control_log; + CHECK(runner.contains(control_first ? "Loaded kinds.py: 3 messages, 1 outlet" + : "Loaded kinds.py: process() bound, one call per sample", + log_level::info)); + CHECK_FALSE(other.contains("Loaded kinds.py", log_level::info)); + } + THEN("each kind says what its own binding owes, whichever ran the file") { + CHECK(audio_log.contains("dsp() is reserved by the host", log_level::error)); + CHECK_FALSE(control_log.contains("dsp() is reserved", log_level::error)); + CHECK(control_log.contains("spread() is hinted to return a tuple without saying how many values", + log_level::info)); + CHECK_FALSE(audio_log.contains("spread()", log_level::info)); + } + THEN("another object of either kind on the same save says none of it again") { + log_capture again; + processor second_control{"kinds", again.sink(), {}, {}, {}, false}; + processor second_audio{"kinds", again.sink(), {"dsp"}}; + REQUIRE(second_control.load()); + REQUIRE(second_audio.load()); + CHECK(again.lines().empty()); + } +} + +// ---- list parameters ------------------------------------------------------------------------------ + +// Before 9.1 a parameter hinted list[float] was not a list to the bridge: it took one atom, coerced to +// a symbol — a number became the empty symbol, as atom_getsym() says — and more atoms were refused. +// That changed for tap.python~'s messages too: recorded in CHANGELOG.md (2.0.0). +SCENARIO("A last message parameter hinted list[...] takes the atoms left after the others (plan 9.1)") { + ensure_runtime(); + const bool bind_audio = GENERATE(true, false); // tap.python~ and tap.python alike + log_capture log; + processor p{"list_params", log.sink(), {}, {}, {}, bind_audio}; REQUIRE(p.load()); REQUIRE(p.call("take", std::vector{1.5})); - CHECK(got(p) == "''"); + CHECK(got(p) == "[1.5]"); + REQUIRE(p.call("take", std::vector{1.0, std::int64_t{2}, 3.0})); + CHECK(got(p) == "[1.0, 2.0, 3.0]"); + REQUIRE(p.call("take", std::vector{})); + CHECK(got(p) == "[]"); - CHECK_FALSE(p.call("take", std::vector{1.0, 2.0, 3.0})); - CHECK(log.contains("take: expected 1 argument(s), got 3", log_level::error)); + THEN("each atom converts to the list's element hint, as a single parameter's would") { + REQUIRE(p.call("ints", std::vector{1.7, std::int64_t{2}})); + CHECK(got(p) == "[1, 2]"); + REQUIRE(p.call("words", std::vector{std::string{"a"}, std::int64_t{1}})); + CHECK(got(p) == "['a', '']"); + REQUIRE(p.call("anything_list", std::vector{std::int64_t{1}, 2.5, std::string{"x"}})); + CHECK(got(p) == "[1, 2.5, 'x']"); + REQUIRE(p.call("written", std::vector{4.0, std::int64_t{5}})); + CHECK(got(p) == "[4, 5]"); + } + THEN("the parameters before it take one atom each, and it the rest") { + REQUIRE(p.call("after", std::vector{std::int64_t{1}})); + CHECK(got(p) == "(1, [])"); + REQUIRE(p.call("after", std::vector{std::int64_t{1}, std::int64_t{2}, std::int64_t{3}})); + CHECK(got(p) == "(1, [2.0, 3.0])"); + CHECK_FALSE(p.call("after", std::vector{})); + CHECK(log.contains("after: expected at least 1 argument(s), got 0", log_level::error)); + } + THEN("with a default and no atoms left, it keeps its default") { + REQUIRE(p.call("optional", std::vector{})); + CHECK(got(p) == "None"); + REQUIRE(p.call("optional", std::vector{std::int64_t{1}})); + CHECK(got(p) == "[1.0]"); + } + THEN("a list parameter followed by *args is not last, and takes one atom as before") { + REQUIRE(p.call("not_last", std::vector{std::int64_t{1}, std::int64_t{2}})); + CHECK(got(p) == "('', (2,))"); + } +} + +SCENARIO("A last message parameter hinted np.ndarray takes them as a float64 array: a list in, a list out") { + ensure_runtime(); + if (!numpy_importable()) { + SKIP("numpy is not importable by the embedded interpreter"); + } + processor p{"array_params", {}, {}, {}, {}, false}; + REQUIRE(p.load()); + REQUIRE(p.call("take", std::vector{std::int64_t{1}, 2.5})); + CHECK(got(p) == "('ndarray', 'float64', [1.0, 2.5])"); + REQUIRE(p.call("take", std::vector{})); + CHECK(got(p) == "('ndarray', 'float64', [])"); + CHECK(p.call_with_output("scaled", std::vector{2.0, std::int64_t{1}, std::int64_t{2}, 3.0}) + == output{list({2.0, 4.0, 6.0})}); +} + +// ---- threads -------------------------------------------------------------------------------------- + +SCENARIO("A message called from another thread while the class reloads outputs one binding's result or the other's") { + ensure_runtime(); + const std::string narrow = "class race_output:\n" + " def value(self) -> int:\n" + " return 3\n"; + const std::string wide = "class race_output:\n" + " def value(self) -> tuple[int, int]:\n" + " return 1, 2\n"; + write_script("race_output", narrow); + processor p{"race_output", {}, {}, {}, {}, false}; + REQUIRE(p.load()); + + std::atomic stop{false}; + std::atomic calls{0}; + std::atomic unexpected{0}; + std::thread caller{[&] { + while (!stop.load()) { + const auto out = p.call_with_output("value", {}); + if (out != output{number(3)} && out != output{number(1), number(2)}) { + ++unexpected; + } + ++calls; + } + }}; + int reloads = 0; + for (int i = 0; i < 40; ++i) { + write_script("race_output", i % 2 == 0 ? wide : narrow); + reloads += p.load() ? 1 : 0; + CHECK(p.outlet_count() == (i % 2 == 0 ? 2u : 1u)); + } + stop = true; + caller.join(); + CHECK(reloads == 40); + CHECK(calls.load() > 0); + CHECK(unexpected.load() == 0); } From e84bae1d6e04ce3a37a45967b77c8a675bc87b16 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Fri, 9 Oct 2026 15:03:29 -0500 Subject: [PATCH 3/6] tap.python's examples: euclid.py, scale.py and note_name.py, run on known inputs (9.1) Three things Max users write by hand, as classes for the object without audio: a Euclidean rhythm from two attributes (a bang, a list out), a list scaled with numpy (a list in as one array, a list out), and a MIDI note's name from two outlets (tuple[str, int]). Each carries default.py's comment on why a method named int or list comes last. The core battery runs them on known inputs. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- core/tests/test_examples.cpp | 70 ++++++++++++++++++++++++++++++++++++ python/euclid.py | 19 ++++++++++ python/note_name.py | 20 +++++++++++ python/scale.py | 22 ++++++++++++ 4 files changed, 131 insertions(+) create mode 100644 python/euclid.py create mode 100644 python/note_name.py create mode 100644 python/scale.py diff --git a/core/tests/test_examples.cpp b/core/tests/test_examples.cpp index 1719678..e49eccf 100644 --- a/core/tests/test_examples.cpp +++ b/core/tests/test_examples.cpp @@ -209,3 +209,73 @@ SCENARIO("stereo_width.py has two inputs and two outputs, and sets the width") { CHECK_FALSE(p.set_attribute("width", -1.0)); } } + +// ---- tap.python's examples: a Python class as a Max object without audio (plan 9.1) ---------------- + +namespace { + + output_item list_of(std::vector atoms) { + return {std::string{"list"}, std::move(atoms)}; + } + + std::vector ints(const std::vector& numbers) { + return {numbers.begin(), numbers.end()}; + } + +} // namespace + +SCENARIO("euclid.py outputs a Euclidean rhythm from its two attributes") { + ensure_runtime(); + if (!importable("attrs")) { + SKIP("attrs is not importable by the embedded interpreter"); + } + processor p{"euclid", {}, {}, {}, {}, false}; + REQUIRE(p.load()); + REQUIRE(p.attributes().size() == 2); + CHECK(p.attributes()[0].name == "steps"); + CHECK(p.attributes()[1].name == "pulses"); + CHECK(p.outlet_count() == 1); + + CHECK(p.call_with_output("bang", {}) == output{list_of(ints({1, 0, 0, 1, 0, 0, 1, 0}))}); + REQUIRE(p.set_attribute("steps", std::int64_t{5})); + REQUIRE(p.set_attribute("pulses", std::int64_t{2})); + CHECK(p.call_with_output("bang", {}) == output{list_of(ints({1, 0, 0, 1, 0}))}); + REQUIRE(p.set_attribute("pulses", std::int64_t{0})); + CHECK(p.call_with_output("bang", {}) == output{list_of(ints({0, 0, 0, 0, 0}))}); + REQUIRE(p.set_attribute("pulses", std::int64_t{9})); + CHECK(p.call_with_output("bang", {}) == output{list_of(ints({1, 1, 1, 1, 1}))}); +} + +SCENARIO("scale.py takes a list as one array, and outputs the array as a list") { + ensure_runtime(); + if (!importable("attrs") || !importable("numpy")) { + SKIP("attrs and numpy are not importable by the embedded interpreter"); + } + processor p{"scale", {}, {}, {}, {}, false}; + REQUIRE(p.load()); + CHECK(p.call_with_output("list", std::vector{std::int64_t{1}, 2.0, std::int64_t{3}}) + == output{list_of({1.0, 2.0, 3.0})}); + REQUIRE(p.set_attribute("factor", 2.0)); + REQUIRE(p.set_attribute("offset", 1.0)); + CHECK(p.call_with_output("list", std::vector{std::int64_t{1}, 2.0, std::int64_t{3}}) + == output{list_of({3.0, 5.0, 7.0})}); +} + +SCENARIO("note_name.py names a MIDI note from two outlets: the pitch class and the octave") { + ensure_runtime(); + if (!importable("attrs")) { + SKIP("attrs is not importable by the embedded interpreter"); + } + processor p{"note_name", {}, {}, {}, {}, false}; + REQUIRE(p.load()); + CHECK(p.outlet_count() == 2); + + const auto name = [&](const std::int64_t note) { return p.call_with_output("int", std::vector{note}); }; + const auto pair = [](const std::string& pitch_class, const std::int64_t octave) { + return output{output_item{std::string{"symbol"}, {pitch_class}}, output_item{std::nullopt, {octave}}}; + }; + CHECK(name(60) == pair("C", 4)); + CHECK(name(61) == pair("C#", 4)); + CHECK(name(0) == pair("C", -1)); + CHECK(name(127) == pair("G", 9)); +} diff --git a/python/euclid.py b/python/euclid.py new file mode 100644 index 0000000..965543e --- /dev/null +++ b/python/euclid.py @@ -0,0 +1,19 @@ +from attrs import define, field + + +@define +class euclid: + """A Euclidean rhythm, for tap.python: a bang outputs `steps` 0s and 1s with `pulses` of the 1s + spread as evenly as they go — 8 steps and 3 pulses is 1 0 0 1 0 0 1 0 — a list to drive a step + sequencer. + + @steps and @pulses are its attributes, so `steps 16` or an attrui changes the pattern; what + bang() returns, a list of ints, is what the object outputs. + """ + + steps: int = field(default = 8) + pulses: int = field(default = 3) + + def bang(self) -> list[int]: + steps = max(1, self.steps) + return [int((i * self.pulses) % steps < self.pulses) for i in range(steps)] diff --git a/python/note_name.py b/python/note_name.py new file mode 100644 index 0000000..53d225b --- /dev/null +++ b/python/note_name.py @@ -0,0 +1,20 @@ +from attrs import define + +NAMES = ("C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B") + + +@define +class note_name: + """A MIDI note number in, its name out, for tap.python: the pitch class from the left outlet and + the octave from the right — 60 outputs C and 4, middle C being C4. + + The return hint tuple[str, int] gives the object two outlets, one value each, output right to + left as Max objects do: the octave, then the name (as `symbol C`). + """ + + # `int` comes last on purpose: once `def int` has run, the name `int` in the class body means this + # method, so an annotation written after it would no longer mean the built-in type. (Inside method + # bodies the built-ins are unaffected.) + + def int(self, note: int) -> tuple[str, int]: + return NAMES[note % 12], note // 12 - 1 diff --git a/python/scale.py b/python/scale.py new file mode 100644 index 0000000..eca8676 --- /dev/null +++ b/python/scale.py @@ -0,0 +1,22 @@ +import numpy as np +from attrs import define, field + + +@define +class scale: + """A list in, scaled and offset with numpy, a list out, for tap.python: with @factor 2 and + @offset 1, the list 1 2 3 outputs 3 5 7. + + A last parameter hinted np.ndarray takes every atom of the message as one float64 array, and an + array returned is output as a list — so a list message runs through numpy and back. + """ + + factor: float = field(default = 1.0) + offset: float = field(default = 0.0) + + # `list` comes last on purpose: once `def list` has run, the name `list` in the class body means + # this method, so an annotation written after it would no longer mean the built-in type. (Inside + # method bodies the built-ins are unaffected.) + + def list(self, values: np.ndarray) -> np.ndarray: + return values * self.factor + self.offset From 922204f7f9760e0a5186377de2b4f059fd21a90a Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Fri, 9 Oct 2026 15:05:14 -0500 Subject: [PATCH 4/6] core/bench: a tap.python message with a list of 64 numbers, and its sentence in the ReadMe's table (9.1) tap_python_bench also times processor::call_with_output() on an object without audio: a list of 64 numbers converted in and the returned list converted back out, for a class that returns it as it came (the bridge alone) and for scale.py (one numpy array), fastest of the rounds, in the JSON as "calls". scripts/update-perf-docs.py writes the sentence beside the process() table, so the ReadMe's performance claim for tap.python is measured. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- core/bench/process_bench.cpp | 91 +++++++++++++++++++++++- core/bench/python/bench_list_identity.py | 7 ++ scripts/update-perf-docs.py | 20 +++++- 3 files changed, 115 insertions(+), 3 deletions(-) create mode 100644 core/bench/python/bench_list_identity.py diff --git a/core/bench/process_bench.cpp b/core/bench/process_bench.cpp index 178c7e7..0f8f1a2 100644 --- a/core/bench/process_bench.cpp +++ b/core/bench/process_bench.cpp @@ -14,6 +14,10 @@ // tap_python_bench --json out.json # also write the measurements (scripts/update-perf-docs.py) // tap_python_bench --seconds 4 --runs 7 // +// It also times a message to an object without audio (tap.python, plan 9.1): a list of 64 numbers +// through processor::call_with_output(), converted in and back out, as the external's messages are +// called from Max's main or scheduler thread. +// // Run it on an otherwise idle machine, from a Release build. #include @@ -22,6 +26,7 @@ #include #include #include +#include #include #include #include @@ -50,6 +55,20 @@ namespace { {"numpy_gain", "per vector: numpy_gain.py, a gain"}, {"numpy_allpass", "per vector: numpy_allpass.py, the same allpass filter"}, }; + // Messages to an object without audio, each with a list of k_message_atoms numbers: the bridge + // alone, then an example doing numpy work. + struct message_subject { + const char* name; // the class file + const char* message; // the method + const char* description; // for the table + }; + constexpr message_subject k_message_subjects[] = { + {"bench_list_identity", "list", "returns its list (the bridge alone)"}, + {"scale", "list", "scale.py, the list as one array, scaled with numpy"}, + }; + constexpr std::size_t k_message_atoms = 64; + constexpr std::size_t k_message_calls = 20000; // per round + constexpr double k_sample_rates[] = {48000.0, 96000.0}; constexpr std::size_t k_vector_sizes[] = {64, 512}; // Max's default signal vector, and a large one @@ -94,7 +113,38 @@ namespace { return elapsed.count() / seconds_of_audio; } - void write_json(const std::string& path, const std::vector& results) { + /// One message subject, and the time each round's call took. + struct call_measurement { + std::string subject; + std::string description; + std::vector seconds; // per call, one per round + + double fastest() const { return *std::min_element(seconds.begin(), seconds.end()); } + + double median() const { + auto sorted = seconds; + std::sort(sorted.begin(), sorted.end()); + return sorted[sorted.size() / 2]; + } + }; + + /// The time one call of `message` with `args` takes on `p`, from `calls` of them. + double call_once(processor& p, const char* message, const std::vector& args, + const std::size_t calls) { + const auto start = std::chrono::steady_clock::now(); + for (std::size_t i = 0; i < calls; ++i) { + const auto out = p.call_with_output(message, args); + if (out.empty()) { + std::fprintf(stderr, "%s output nothing\n", message); + std::exit(1); + } + } + const std::chrono::duration elapsed = std::chrono::steady_clock::now() - start; + return elapsed.count() / static_cast(calls); + } + + void write_json(const std::string& path, const std::vector& results, + const std::vector& calls) { std::ofstream out{path}; out << "{\n \"python\": \"" << Py_GetVersion() << "\",\n \"measurements\": [\n"; for (std::size_t i = 0; i < results.size(); ++i) { @@ -104,6 +154,13 @@ namespace { << ", \"vector_size\": " << r.vector_size << ", \"load\": " << r.load() << ", \"median\": " << r.median() << "}" << (i + 1 < results.size() ? ",\n" : "\n"); } + out << " ],\n \"calls\": [\n"; + for (std::size_t i = 0; i < calls.size(); ++i) { + const auto& c = calls[i]; + out << " {\"subject\": \"" << c.subject << "\", \"description\": \"" << c.description + << "\", \"atoms\": " << k_message_atoms << ", \"seconds\": " << c.fastest() + << ", \"median\": " << c.median() << "}" << (i + 1 < calls.size() ? ",\n" : "\n"); + } out << " ]\n}\n"; } @@ -164,6 +221,23 @@ int main(int argc, char** argv) { } } } + std::vector> message_processors; + std::vector calls; + std::vector list_args; + for (std::size_t i = 0; i < k_message_atoms; ++i) { + list_args.emplace_back(0.5 * static_cast(i)); + } + for (const auto& s : k_message_subjects) { + message_processors.push_back(std::make_unique(s.name, log, std::vector{}, + std::function{}, + std::function{}, false)); + if (!message_processors.back()->load()) { + std::fprintf(stderr, "could not load %s (are attrs and numpy importable?)\n", s.name); + return 1; + } + calls.push_back({s.name, s.description, {}}); + } + for (int round = -1; round < runs; ++round) { // round -1 warms up, untimed for (std::size_t i = 0; i < results.size(); ++i) { auto& r = results[i]; @@ -172,6 +246,13 @@ int main(int argc, char** argv) { r.loads.push_back(load); } } + for (std::size_t i = 0; i < calls.size(); ++i) { + const double seconds = + call_once(*message_processors[i], k_message_subjects[i].message, list_args, k_message_calls); + if (round >= 0) { + calls[i].seconds.push_back(seconds); + } + } } std::printf("%-22s %-7s %-5s %-7s %-7s %s\n", "class", "rate", "vs", "load", "median", "cost"); @@ -183,8 +264,14 @@ int main(int argc, char** argv) { load * 100.0, r.median() * 100.0, per_call, r.block ? "us/vector" : "ns/sample"); } + std::printf("\n%-22s %-9s %-9s %s\n", "message", "atoms", "fastest", "median"); + for (const auto& c : calls) { + std::printf("%-22s %-9zu %6.2f us %6.2f us\n", c.subject.c_str(), k_message_atoms, c.fastest() * 1e6, + c.median() * 1e6); + } + if (!json_path.empty()) { - write_json(json_path, results); + write_json(json_path, results, calls); } return 0; } diff --git a/core/bench/python/bench_list_identity.py b/core/bench/python/bench_list_identity.py new file mode 100644 index 0000000..e7acd16 --- /dev/null +++ b/core/bench/python/bench_list_identity.py @@ -0,0 +1,7 @@ +# Benchmark fixture (plan 9.1): a tap.python message that returns its list as it came — what the +# bridge costs a message: 64 atoms converted in, the list converted back out. + + +class bench_list_identity: + def list(self, values: list[float]) -> list[float]: + return values diff --git a/scripts/update-perf-docs.py b/scripts/update-perf-docs.py index 5a8c1b6..a85a76e 100644 --- a/scripts/update-perf-docs.py +++ b/scripts/update-perf-docs.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # SPDX-License-Identifier: MIT # Copyright 2022-2026 Timothy Place. -"""Measure what process() costs and write the table into ReadMe.md (plan 6.3). +"""Measure what process() costs, and a tap.python message, and write them into ReadMe.md (plan 6.3, 9.1). python3 scripts/update-perf-docs.py # build core/bench (Release), run it, update ReadMe.md python3 scripts/update-perf-docs.py --max # also measure in Max (macOS; quit Max first) @@ -145,6 +145,23 @@ def comparison(results: dict) -> list[str]: "vector takes two, and 96 at 96 kHz, so it takes one — a delay shorter than the vector costs more."] +def messages(results: dict) -> list[str]: + """A sentence on what a tap.python message costs, from the measurements (plan 9.1).""" + calls = {c["subject"]: c for c in results.get("calls", [])} + if "bench_list_identity" not in calls or "scale" not in calls: + return [] + atoms = calls["bench_list_identity"]["atoms"] + + def microseconds(subject: str) -> str: + return f"{calls[subject]['seconds'] * 1e6:.2g} µs" + + return ["", f"A message to `tap.python` with a list of {atoms} numbers, each converted in and the list the " + f"method returns converted back out — called as Max's main or scheduler thread calls it, never the " + f"audio thread — costs {microseconds('bench_list_identity')} when the class returns the list as it " + f"came (the bridge alone), and {microseconds('scale')} for `scale.py`, which takes it as one numpy " + f"array."] + + def table(results: dict, python: Path) -> str: rows: dict[tuple, dict] = {} for m in results["measurements"]: @@ -162,6 +179,7 @@ def table(results: dict, python: Path) -> str: lines.append(f"| {description} — {form} | {cost(row[48000.0])} | {percent(row[48000.0]['load'])} | " f"{percent(row[96000.0]['load'])} |") lines += comparison(results) + lines += messages(results) lines += [ "", f"The share of one core: each row timed once per round for seven rounds, interleaved, keeping its " From 4fb6c514edad875753f5451c1920dc5e5867a1d2 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Fri, 9 Oct 2026 15:07:49 -0500 Subject: [PATCH 5/6] The plan: 9.1 done, and the core as built; CLAUDE.md on call_with_output() and the new examples Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- CLAUDE.md | 6 ++++-- docs/PRODUCTION-PLAN.md | 2 +- docs/TAP-PYTHON-PLAN.md | 26 ++++++++++++++++---------- 3 files changed, 21 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f76a1e3..c99ff7e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,9 @@ built yet. signatures) that `processor.h` builds its descriptions from), `value.h` (the Max-atom value model and its coercion rules, which reproduce `atom_getlong`/`atom_getfloat`/`atom_getsym`), `processor.h` (load/reload, class introspection, attribute and message dispatch, `prepare()`, and `process()` — per sample, or - per vector when the input is hinted `np.ndarray` — plus `flush_reports()`), `worker.h` (worker + per vector when the input is hinted `np.ndarray` — plus `flush_reports()`; and, with `bind_audio` + off for `tap.python`, `call_with_output()`, which converts what a method returns for the outlets + by the plan's output table, and `outlet_count()` from the return hints: plan 9.1), `worker.h` (worker mode, plan 2.5: `process()` on a thread of its own, a fixed number of vectors behind an audio thread that only copies through a lock-free ring and never takes the GIL). New CPython-facing behavior goes here, never in the wrapper. CMake target `tap::python` (`core/CMakeLists.txt`). @@ -43,7 +45,7 @@ built yet. - **`python/`** — the user's script folder in the package (and the examples: `default.py`, `numpy_gain.py`, `allpass.py`, `numpy_allpass.py` — the same filter per vector, checked equal sample for sample by the core battery — `stereo_width.py`, two inputs and two outputs, and - `allpass-doc.ipynb`). + `allpass-doc.ipynb`; and for `tap.python`, without audio: `euclid.py`, `scale.py`, `note_name.py`). - **`runtime-tests/`** — tests that run inside a real Max (plan 6.1): Cycling '74's max-test harness (submodule), patchers generated by `make_patchers.py` (edit the generator, never the patchers), fixtures (`python/maxtest_*.py`, copied into `python/` for a run) and `run.py`, which installs the diff --git a/docs/PRODUCTION-PLAN.md b/docs/PRODUCTION-PLAN.md index 80b32bb..fc566f9 100644 --- a/docs/PRODUCTION-PLAN.md +++ b/docs/PRODUCTION-PLAN.md @@ -808,7 +808,7 @@ row shipped what only a host platform could show. Windows (#45), Max 9.1.5, the same answers on both, in TAP-PYTHON-PLAN.md under 9.0: the `init/` mapping works; `get` needs the class's `dumpout` method; `int`, `float`, `bang` and `list` never reach a class-level `anything`; a `str` is output as `symbol `.* -- [ ] **9.1 The core:** output items and their conversion in `value.h`; `message_info::return_count` +- [x] **9.1 The core** (#46)**:** output items and their conversion in `value.h`; `message_info::return_count` (depth-aware for string hints), `outlet_count()`, `call_with_output()`; the `bind_audio` option, gating the tuple rule; a last parameter hinted `list[…]` or `np.ndarray` taking the remaining atoms (both objects; the old behavior pinned first, the change recorded — a contract change, so diff --git a/docs/TAP-PYTHON-PLAN.md b/docs/TAP-PYTHON-PLAN.md index 0f9b706..f098e51 100644 --- a/docs/TAP-PYTHON-PLAN.md +++ b/docs/TAP-PYTHON-PLAN.md @@ -98,7 +98,7 @@ returns. The rules reproduce how Max objects and `js` behave, so a patch sees wh | an `int` (anything with `__index__`: `np.int64`, an `IntEnum`) | an int (`t_atom_long`, 64-bit; a value past it is reported) | | a `float` (anything with `__float__` and no `__index__`: `np.float32`) | a float; a non-finite value passes through as the atom Max can carry (`tap.python~` zeroes them for the audio's sake; a control value is the class's to make) | | a `str` | `symbol `: one symbol, whatever it holds (`"hello world"` is one symbol, `"60"` the symbol and not the number). *Decided by the 9.0 spike, in Max:* output as the message it names, the strings `list`, `int`, `float`, `symbol`, `bang` and `""` are not data — dropped, an error in every receiver, a real bang — while `symbol ` reaches `sel`, a message box's `$1` and every other receiver as itself ([what 9.0 found](#what-90-found), 6). To output the message a string names, return it in a list (`["start"]`, the next row) | -| a sequence: a `list`, a `tuple` without a `tuple[…]` hint, a `range`, or a 1-D `np.ndarray` | a list, each element an atom by the rules above; if the first element is a `str`, the message it names with the rest as arguments (Max's own rule: `["note", 60, 100]` outputs `note 60 100`); an empty sequence outputs nothing; an element that is not an atom (`None`, a nested sequence) is reported and the list is not output | +| a sequence: a `list`, a `tuple` without a `tuple[…]` hint, a `range`, or a 1-D `np.ndarray` (a 0-d one is its value) | a list, each element an atom by the rules above; if the first element is a `str`, the message it names with the rest as arguments (Max's own rule: `["note", 60, 100]` outputs `note 60 100`); an empty sequence outputs nothing; an element that is not an atom (`None`, a nested sequence) is reported and the list is not output | | a sequence of *n* values, from a method hinted `-> tuple[…]` with *n* members | one value per outlet, outlets *n*…1, right to left, each by these rules (`None` in a slot outputs nothing from that outlet); a result that is not a sequence of exactly *n* values is reported | | anything else: a `dict`, a `set`, `bytes`, a generator, a 2-D array, an object | reported, with its type; nothing output (a `dict` as a Max dictionary is a later item) | @@ -176,14 +176,16 @@ races a widening reload against a second thread's messages (TSan on the Linux le did (D6): - **`value.h`** — beside `value` (one atom): `output_item`, a message to output — a selector or - none, and its atoms (what `outlet_anything` / `outlet_list` / `outlet_int` take) — and - `output`, the per-outlet items of one call. The conversion from a Python object to an + none, and its atoms (what `outlet_anything` / `outlet_list` / `outlet_int` take: no selector is + one number, the selector `list` a list, any other the message it names, a `str` being `symbol + `) — and `output`, the per-outlet items of one call (empty: nothing at all). The conversion from a Python object to an `output_item` lives in the core (the table above; `np.bool_` recognized by its `__mro__` name as `hint_kind` does, without importing numpy), with its errors as diagnostics through the processor's log, so the Max side only maps items onto `outlet_*` calls. -- **`processor.h`** — `message_info` gains `return_count` (from `describe()`'s `return_shape`, - made depth-aware for string hints); `outlet_count()` is the widest among the messages (at least - one); a new **`call_with_output()`** returns the converted `output` (empty for `None` or a +- **`processor.h`** — `message_info` gains `return_count` and `spreads` (from `describe()`'s + `return_shape`, made depth-aware for string hints; a `tuple[…]` of more than 64 members is a list, + said once) and `rest`/`rest_type` for a last parameter hinted `list[…]` or `np.ndarray`; + `outlet_count()` is the widest among the messages (at least one); a new **`call_with_output()`** returns the converted `output` (empty for `None` or a failure) beside the existing `bool call()`, which `tap.python~` keeps (C++ cannot overload on the return type alone); the constructor's `bind_audio` — off, `process`/`prepare` are bound as messages, `has_process()` is false, `prepare()` is a no-op; the unsaid-length tuple rule applies @@ -192,9 +194,13 @@ did (D6): - **Announce-once per kind (audit M5).** The class diagnostics that depend on the object kind — a name reserved by one host and not the other, the tuple rule — are announced once per *(file, kind)*, not once per file: the loader keeps what it announced for each kind against the source - it executed (`announce_due(name, kind)`), and a processor announces what its kind owes even when - the other kind ran the save. The `Loaded` line stays once per save, from whichever ran it, and - says what that object bound — "4 messages, 2 outlets" or "process() bound, one call per vector". + it executed (`announce_due(name, kind)`, the kinds `audio` and `control`), and a processor + announces what its kind owes even when the other kind ran the save. The `Loaded` line stays once + per save, from whichever ran it, and says what that object bound — "4 messages, 2 outlets" or + "process() bound, one call per vector". As built (9.1): a name its host reserves, everything + `process()`'s binding says, a keyword-only parameter and the tuple rules are per kind; what is + true of the class whatever binds it — a class that will not load or instantiate, a hint that does + not resolve, an attribute whose type changed — stays once per save. - **Tests** — `test_output.cpp`: every row of the table above from a fixture whose methods return each kind; the outlet count from the hints, object and string, nested; an unhinted tuple as a list against a hinted one as outlets; an unsaid-length tuple hint as a list with one notice; the @@ -352,7 +358,7 @@ third was Windows-only. file database records each, and the Documentation window lists the package under Package Docs; an `extras/` patcher is in the Extras menu** (seen on the Mac; which of the window's tabs shows which file is 9.4's to look at, when it writes them). -- [ ] **9.1 The core: output, outlets and the audio option.** `value.h`'s `output_item`/`output` +- [x] **9.1 The core: output, outlets and the audio option** (#46). `value.h`'s `output_item`/`output` and the Python-to-output conversion; `message_info::return_count` (depth-aware for strings), `outlet_count()`, `call_with_output()`; `bind_audio`, gating the tuple rule; the `list[…]`/`np.ndarray` final parameter with the old behavior pinned first; announce-once per From 1b94df2e83f3d08fa203e91f5e58fea84ae830d7 Mon Sep 17 00:00:00 2001 From: Timothy Place Date: Fri, 9 Oct 2026 15:17:20 -0500 Subject: [PATCH 6/6] The plan: what the message bench measured, and when the ReadMe's table is next regenerated Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz --- docs/TAP-PYTHON-PLAN.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/TAP-PYTHON-PLAN.md b/docs/TAP-PYTHON-PLAN.md index f098e51..4e09b99 100644 --- a/docs/TAP-PYTHON-PLAN.md +++ b/docs/TAP-PYTHON-PLAN.md @@ -368,7 +368,10 @@ third was Windows-only. length against results of the wrong length), and `test_examples.cpp` running the three new examples on known inputs. A `core/bench` row for a message call with a list of 64 atoms, written by `scripts/update-perf-docs.py` with the others, so the ReadMe's performance sentence is - measured. No Max code changes; `tap.python~`'s battery and glue test unchanged and green; the + measured. *(9.1: the row and the script's sentence are in; the ReadMe's table is regenerated on + the next measurement on an idle machine, 9.6 at the latest — on 2026-10-09, with macOS's indexing + running, a message with 64 numbers in and out measured 5.6 µs for the bridge alone and 15 µs for + `scale.py`, and `main` and the branch measured alike back to back.)* No Max code changes; `tap.python~`'s battery and glue test unchanged and green; the audio bench numbers unchanged (the audio path does not touch the new code). - [ ] **9.2 The shared glue.** `tap.python_tilde_{attribute,message,cglue,filewatch,package}.h` become `python_glue` (the trampolines instantiated per host through `Host::self()`), in