Log Chipmunk level errors with standard logging module

Author: viblo

CHANGELOG.rst

@@ -2,6 +2,13 @@
 Changelog 
 =========
 
+..
+  Pymunk x.x.x
+  ------------
+  Changes:
+  - Fixed issue with SlideJoint when changing body_type.
+  - Log Chipmunk level erros with logging module
+
 Pymunk 6.8.1 (2024-06-05)
 -------------------------
 

Chipmunk2D

@@ -311,6 +311,22 @@ Note that the version of Pymunk used must be the same for the code saving as
 the version used when loading the saved object.
 
 
+Asserts and error handling
+==========================
+
+Pymunk uses asserts to guard against bad input, for example to guard against 
+adding the same Shape twice to a Space. Should an assert fail it can be 
+handled the normal Python way, for example with a try/catch. 
+
+There are also asserts deeper in Pymunk, in the underlying Chipmunk library. 
+These guards against both bad input that is not possible to check from the 
+Pymunk side, and against bad simulation state that can happen for various 
+reasons in the middle of the simulation. These are normally not recoverable, 
+and will result in a hard crash if failed. The problem will be logged using 
+the standard Python logging module, with the logger name "pymunk" (or a child 
+of it). 
+
+
 Additional info
 ===============
 

docs/src/overview.rst

@@ -30,6 +30,12 @@
 This is the main containing module of Pymunk. It contains among other things
 the very central Space, Body and Shape classes.
 
+Pymunk uses the standard logging module to log helpful information. It does 
+that under the "pymunk" name. If you do not do anything setup, it will print
+WARNING and higher messages to stderr. (Note that you most likely do not want 
+to set logLevel to DEBUG, since Pymunk might log a lot of debug level 
+messages mostly useful during development of Pymunk itself.)
+
 """
 
 __docformat__ = "reStructuredText"
@@ -69,10 +75,6 @@
 cp = _chipmunk_cffi.lib
 ffi = _chipmunk_cffi.ffi
 
-import logging
-
-logging.getLogger(__name__).addHandler(logging.NullHandler())
-# logging.basicConfig(level=0)
 
 from . import _version
 from .arbiter import Arbiter
@@ -89,6 +91,10 @@
 from .transform import Transform
 from .vec2d import Vec2d
 
+# import logging
+# logging.getLogger(__name__).addHandler(logging.NullHandler())
+# logging.basicConfig(level=0)
+
 version: str = _version.version
 """The release version of this pymunk installation.
 Valid only if pymunk was installed from a source or binary

pymunk/__init__.py

@@ -313,3 +313,9 @@ def ext_cpDampedRotarySpringTorqueFunc(
 def ext_cpArbiterIteratorFunc(_arbiter, data):  # type: ignore
     arbiters = ffi.from_handle(data)
     arbiters.append(_arbiter)
+
+
+# cpMessage / log override
+@ffi.def_extern()
+def ext_pyLog(formattedMessage):
+    _logger.error(ffi.string(formattedMessage).decode())

pymunk/_callbacks.py

@@ -78,6 +78,7 @@
     include_dirs=[os.path.join("Chipmunk2D", "include")],
     sources=sources,
     libraries=libraries,
+    define_macros=[("CP_OVERRIDE_MESSAGE", None)],
 )
 
 if __name__ == "__main__":

pymunk/pymunk_extension_build.py

@@ -43,4 +43,6 @@ extern "Python" {
     cpFloat ext_cpMarchSampleFunc(cpVect point, void *data);
     void ext_cpMarchSegmentFunc(cpVect v0, cpVect v1, void *data);
 
+    // custom method for logging (override of CP_MESSAGE)
+    void ext_pyLog(const char *formattedMessage);
 }

pymunk_cffi/callbacks_cdef.h

@@ -1,3 +1,6 @@
+#include <stdio.h>
+#include <stdarg.h>
+
 #include "chipmunk/chipmunk_private.h"
 
 //
@@ -455,4 +458,33 @@ cpFloat defaultSpringForce(cpDampedSpring *spring, cpFloat dist){
 
 cpFloat defaultSpringTorque(cpDampedRotarySpring *spring, cpFloat relativeAngle){
 	return (relativeAngle - spring->restAngle)*spring->stiffness;
-}
+}
+
+
+//
+// Functions to forward logs (printfs) to python code instead of directly printing to stderr
+//
+
+//Python side, already formatted message
+void ext_pyLog(const char *formattedMessage); 
+
+//Chipmunk side, follows existing function declaration
+void cpMessage(const char *condition, const char *file, int line, int isError, int isHardError, const char *message, ...)
+{
+   	ext_pyLog((isError ? "Aborting due to Chipmunk error: " : "Chipmunk warning: "));
+    
+    static char formattedMessage[256];
+    formattedMessage[0] = 0;
+
+    va_list vargs;
+	va_start(vargs, message); {	
+        vsnprintf(formattedMessage, sizeof(formattedMessage), message, vargs);
+		ext_pyLog(formattedMessage);
+	} va_end(vargs);
+    
+    snprintf(formattedMessage, sizeof(formattedMessage), "\tFailed condition: %s", condition);
+	ext_pyLog(formattedMessage);
+	
+    snprintf(formattedMessage, sizeof(formattedMessage), "\tSource: %s:%d", file, line);
+	ext_pyLog(formattedMessage);	
+}