9.1 The core for tap.python: what a method returns, as output; outlets from the hints; the audio option

[tap]

Plan item 9.1 (docs/TAP-PYTHON-PLAN.md, "The core"). Everything that tap.python (a Python class as a Max object without audio) needs from the host-independent core lands here, with tests. There is no Max code change: the Max object is 9.3. tap.python~'s battery and glue test pass unchanged, with one deliberate exception: the list[…] parameter change below.

What's in it

What a method returns, as output (value.h, processor.h)

• output_item is one message for an outlet: a selector and its atoms. No selector means one number; the selector list means a list; any other selector is the message it names. output is what each outlet emits from one call.
• processor::call_with_output() sits beside call() and converts the result by the plan's output table:
  • None outputs nothing.
  • A bool, number or str is one value. A str is symbol <s>, as the 9.0 spike decided.
  • A list, unhinted tuple, range or 1-D array is a list; when its first element is a str, it's the message that names instead.
  • A 0-d array is its value.
  • A return hinted tuple[…] gives one value per outlet.
• Anything an outlet can't carry is reported and nothing is output: an integer past 64 bits, a list holding None or another list, a dict, a 2-D array.
• numpy's types are recognized by name without importing numpy. I checked the conversion code for CPython data symbols (the delay-loaded Windows external can't use them); there are none in a Release build.

Outlets

• message_info gains return_count and spreads, and outlet_count() gives the widest return hint.
• The support module now splits a return hint written as a string only at its top level, so 'tuple[list[int], dict[str, int]]' counts 2 outlets, not 3 (audit m4).

The audio option

• The processor's constructor takes bind_audio. With it off, process() and prepare() are ordinary messages, has_process() stays false, and prepare() does nothing.
• With it off, a tuple hint that doesn't say how many values is output as a list from one outlet, and the console says so once.

A last parameter hinted list[…] or np.ndarray takes all the atoms left after the other parameters, as a list or as a float64 array. This applies to tap.python~ too.

• It is a contract change: before, such a parameter took one atom converted to a symbol, so a number arrived as the empty string, and extra atoms were refused.
• The first commit pins that old behaviour with a test; the change then updates the test.
• It's recorded in a new CHANGELOG 2.0.0 — unreleased section and in the ReadMe's Messages paragraph.

Announcements per kind of object (audit M5)

• Some diagnostics depend on how a kind of object binds the class: a name its host reserves, process()'s binding, a keyword-only parameter, the tuple rules. These are now said once per (save, kind), so the audio and control kinds each say theirs even when the other kind's object ran the file.
• What's true of the class whatever binds it (a class that won't load or instantiate, a hint that won't resolve, an attribute whose type changed) is still said once per save.
• The Loaded line says what that object bound, e.g. Loaded outputs.py: 5 messages, 2 outlets.

Examples (python/): euclid.py (a Euclidean rhythm: bang in, list out), scale.py (a list scaled with numpy: list in, list out) and note_name.py (a MIDI note's name from two outlets, tuple[str, int]).

Bench

• tap_python_bench now also times a message with a list of 64 numbers, converted in and back out. In Release on this Mac it costs 5.6 µs for the bridge alone and 15 µs for scale.py.
• update-perf-docs.py writes that as a sentence beside the process() table. I did not regenerate the ReadMe here. With macOS's indexing running, every row came out 20–35% slower and noisier than the 30 September table. main and this branch measured alike back to back, so it's the machine, not the change. Today's figures are in the plan; the table gets regenerated at the next idle measurement (9.6 at the latest).

Tests

test_output.cpp, 10 scenarios and 396 assertions:

• the output table as one data-driven test over its edges: 64-bit limits, NaN and infinity, numpy scalars of each family, 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;
• bind_audio off;
• two kinds of object sharing one file, each order;
• list and array parameters;
• a raising method;
• a message called while the class reloads on another thread.

test_examples.cpp runs the three new examples on known inputs.

On this Mac:

• the core battery passes 111/111, and 111/111 under ThreadSanitizer;
• tap.python~'s glue test passes;
• clang-format and clang-tidy-18 (as in style.yml) are clean.

CI will run Linux (ASan/UBSan, TSan) and Windows.

Docs

• The plan: 9.1 ticked in both plan files, and "The core" updated as built.
• CLAUDE.md: notes on call_with_output() and the new examples.

🤖 Generated with Claude Code

https://claude.ai/code/session_019rVV9SkjkWmiBXFMT4whkz