The Python binding (kpy/): klammertext.Machine from a script

Assembled from klammertext-dev ed13dfaa5b7a.  kpy/klammertext.cpp is a
CPython extension module giving a Python script an instance of the
Machine class -- ktext in-process, set up through the same functions the
command uses.  Errors map one-to-one to Python exceptions under the C++
names; an @eval's Python exception is chained as __cause__.  Built by
make -C mac, found through PYTHONPATH (env/runtime.env sets it), tested
by tst/kpy_test.sh.  Three engine changes came with it: Error::message(),
set_command_state(), and the @eval error report carrying its traceback.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uv7KWxafinDPraswEf4GsC

kpy/Makefile

@@ -0,0 +1,51 @@
+# kpy/ -- the Python binding of the Klammermachine.
+#
+# klammertext.cpp is a CPython extension module (see its header comment).
+# Like ref/reflect.so and sks/document/document.so it links against
+# libklammertext.so and shares the engine's class layouts, so it is rebuilt
+# whenever they are (mac/Makefile's "all" runs "make -C kpy"; com/Makefile's
+# "redo" and dbg/rebuild.sh clean it -- a clean that misses a directory is a
+# mixed-object hazard, not a tidiness one).
+#
+# The module's filename carries the interpreter's ABI tag
+# (klammertext.cpython-3XX-<arch>.so) from python3-config, the same tool
+# makefile.env takes the include and link flags from: the module is bound to
+# the ONE Python the library was built against, by decision.  The library
+# already links that libpython, so the link line is the commands' link line
+# with $(SHARED) in place of $(EXPORT_DYNAMIC).
+
+K := $(KLAMMERTEXT_HOME)
+
+include $(K)/env/makefile.env
+
+LIBDIR := $(K)/lib
+LIBRARY := $(LIBDIR)/libklammertext.so
+
+EXT_SUFFIX := $(shell python3-config --extension-suffix)
+MODULE := klammertext$(EXT_SUFFIX)
+
+# "../lib": the module sits in $(K)/kpy, one level below $(K).
+KPY_LDFLAGS := $(SHARED) -Wl,-rpath,'$(ORIGIN)/../lib' -L$(LIBDIR)
+
+OBJECTS := klammertext.o
+DEPFILES := $(OBJECTS:.o=.d)
+
+DEPFLAGS = -MMD -MP -MF $(@:.o=.d)
+
+.PHONY: all clean
+
+all : $(MODULE)
+
+%.o : %.cpp
+	@echo Compiling $<
+	$(CXX) -c $(CPPFLAGS) $(CXXFLAGS) $(DEPFLAGS) $< -o $@
+
+$(MODULE) : $(OBJECTS) $(LIBRARY)
+	$(CXX) $(CPPFLAGS) $(CXXFLAGS) $(KPY_LDFLAGS) $(LDFLAGS) \
+		-o $@ $(OBJECTS) -lklammertext $(LDLIBS)
+
+clean :
+	rm -f $(OBJECTS) $(DEPFILES) klammertext.*.so *~
+	rm -rf __pycache__
+
+-include $(DEPFILES)