twenty-three wrong programs and what each is told

[tamnd]

DX2 asks for a misuse suite in both clients, and this is the Python half of it, against the same list the engine answers in crates/zu/tests/misuse.rs. Clear is the hard word in "a clear error for every deliberately wrong program", so the suite spells it out as three things a message has to do. It names the thing the caller named, being the file they opened, the column they appended to, the parameter they passed. It says what was expected instead wherever there is something to say. And it is the engine's own sentence rather than a syscall's, because "failed to fill whole buffer" is a true statement about a read that tells nobody which file was not a database.

Clear also means the right class, since a Python caller catches classes and reads messages afterwards. A mistake the program made is a ProgrammingError, a value Python has and zu does not is a TypeError, a value of the right type and the wrong shape is a ValueError, and a file that is there and is not a database now raises ConnectionError rather than InternalError. That last one is the same typo as a file that is not there, landing on a real file, and telling somebody to file a bug about their own path would be the wrong answer twice.

No crash is the suite running at all. No leak is checked twice, from outside the call that would cause one: every case is followed by a read on the connection it was aimed at, and the failing connects are repeated five hundred times, which is past the descriptor limit a process starts with, after which a database is opened and written to prove the descriptors are there and gc is asked whether any connection outlived its test.

An appender the collector took while it still held rows is the one mistake that cannot be reported where it happens, so it warns: a ResourceWarning naming the table and the rows it discarded. Flushing from a destructor is the other answer and is not available to this client, because a collector runs whenever it likes, including while another thread is inside a statement on the same connection. Going quietly is the failure mode worth a warning, since a loop that appended a million rows and never closed otherwise leaves an empty database and no complaint about it. The warning also puts aside whatever exception is being raised while it goes out, so it is an aside rather than something that replaces the failure the caller is about to see.

The last test is the half of a misuse suite that is usually missing: the programs that look wrong and are not. A parameter no statement reads, a label nothing carries, a comparison across types, a result read twice, a second close(), and a stop that arrives with nothing running are each a decision, and a decision nobody wrote down is a decision somebody reverses by accident. The interrupt case is where the two clients differ on purpose and the test says why: this one clears before every statement, because the thread that asked cannot know whether the statement it meant to stop had already finished, and a Ctrl-C pressed a moment too late would otherwise end the next thing the notebook runs.

The engine pin moves to the commit carrying the Rust half, which also names the file in every failure the operating system raised. Value arrives with Graph and BindingTable variants, so a reference goes to Python as the string that names it, the way the shell and the ABI's JSON already send it, and Arrow refuses it by name because Arrow has no type for it.

Local: ruff, cargo fmt, cargo clippy --all-targets -D warnings, 436 tests and the 945 case corpus, all green.