Avoid loop in initialisation of exception types

jeff5 · jeff5 · commit f813238c0b8a · 2025-02-15T19:22:30.000Z
diff --git a/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTest.java b/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTest.java
@@ -1,4 +1,4 @@
-// Copyright (c)2024 Jython Developers.
+// Copyright (c)2025 Jython Developers.
 // Licensed to PSF under a contributor agreement.
 package uk.co.farowl.vsj4.runtime;
 
@@ -41,6 +41,7 @@
  * JVM. (See the {@code kernelTest} target in the build.)
  */
 @DisplayName("Without any preparation")
+@SuppressWarnings("static-method")
 class TypeInitTest {
 
     /**
@@ -49,7 +50,7 @@ class TypeInitTest {
      * subclass with {@code @BeforeAll}.
      */
     @BeforeAll
-    static void setUpClass() {};
+    static void setUpClass() {}
 
     /** After setUp() a type exists for {@code object}. */
     @Test
@@ -97,7 +98,6 @@ void lookup_type_type() {
     }
 
     /** After setUp() all type implementations have the same type. */
-    @SuppressWarnings("static-method")
     @Test
     @DisplayName("Subclasses of PyType share a type object")
     void type_subclasses_share_type() {
@@ -119,7 +119,6 @@ void type_subclasses_share_type() {
      * {@code Double} as a found Java type before the Python type
      * {@code float} can adopt it.
      */
-    @SuppressWarnings("static-method")
     @Test
     @DisplayName("we can look up a type for Double.class")
     void lookup_type_double() {
diff --git a/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestNameError.java b/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestNameError.java
@@ -0,0 +1,44 @@
+// Copyright (c)2025 Jython Developers.
+// Licensed to PSF under a contributor agreement.
+package uk.co.farowl.vsj4.runtime;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Test that the Python type system comes into operation in a consistent
+ * state after referencing the class {@link PyNameError}. Most of the
+ * tests are in the superclass.
+ */
+@DisplayName("After getting PyNameError.TYPE ...")
+@SuppressWarnings("static-method")
+class TypeInitTestNameError extends TypeInitTest {
+
+    /** Initialised in {@link #setUpClass()}. */
+    static PyType type;
+
+    /** Start by creating an instance of {@code PyNameError}. */
+    @BeforeAll
+    static void setUpClass() { type = PyNameError.TYPE; }
+
+    @Test
+    @DisplayName("PyNameError.TYPE is not null")
+    void type_not_null() { assertNotNull(type); }
+
+    @Test
+    @DisplayName("PyExc.NameError is not null")
+    void name_error_not_null() { assertNotNull(PyExc.NameError); }
+
+    @Test
+    @DisplayName("PyExc.KeyError is not null")
+    void key_error_not_null() { assertNotNull(PyExc.KeyError); }
+
+    @Test
+    @DisplayName("PyExc.UnboundLocalError is not null")
+    void unbound_local_error_not_null() {
+        assertNotNull(PyExc.UnboundLocalError);
+    }
+}
diff --git a/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestPyExc.java b/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestPyExc.java
@@ -0,0 +1,42 @@
+// Copyright (c)2025 Jython Developers.
+// Licensed to PSF under a contributor agreement.
+package uk.co.farowl.vsj4.runtime;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Test that the Python type system comes into operation in a consistent
+ * state after referencing a type through {@link PyExc}. Most of the
+ * tests are in the superclass.
+ */
+@DisplayName("After getting PyExc.UnboundLocalError ...")
+@SuppressWarnings("static-method")
+class TypeInitTestPyExc extends TypeInitTest {
+
+    /** Initialised in {@link #setUpClass()}. */
+    static PyType type;
+
+    /** Start by touching the type object {@code UnboundLocalError}. */
+    @BeforeAll
+    static void setUpClass() { type = PyExc.UnboundLocalError; }
+
+    @Test
+    @DisplayName("The result is not null")
+    void object_not_null() { assertNotNull(type); }
+
+    @Test
+    @DisplayName("PyExc.TypeError is not null")
+    void typeerror_not_null() { assertNotNull(PyExc.TypeError); }
+
+    @Test
+    @DisplayName("PyExc.StopIteration is not null")
+    void stopiter_not_null() { assertNotNull(PyExc.StopIteration); }
+
+    @Test
+    @DisplayName("PyExc.KeyError is not null")
+    void keyerror_not_null() { assertNotNull(PyExc.KeyError); }
+}
diff --git a/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestReentrant.java b/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestReentrant.java
@@ -1,4 +1,4 @@
-// Copyright (c)2024 Jython Developers.
+// Copyright (c)2025 Jython Developers.
 // Licensed to PSF under a contributor agreement.
 package uk.co.farowl.vsj4.runtime;
 
@@ -25,7 +25,7 @@ class TypeInitTestReentrant extends TypeInitTest {
 
     /** Start by using a complex Python type defined in Java. */
     @BeforeAll
-    static void setUpClass() { object = new MyOther(); };
+    static void setUpClass() { object = new MyOther(); }
 
     /** A simple type defined in Java. */
     static class MyClass {
diff --git a/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestRegistry.java b/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestRegistry.java
@@ -1,4 +1,4 @@
-// Copyright (c)2024 Jython Developers.
+// Copyright (c)2025 Jython Developers.
 // Licensed to PSF under a contributor agreement.
 package uk.co.farowl.vsj4.runtime;
 
@@ -21,5 +21,5 @@ class TypeInitTestRegistry extends TypeInitTest {
 
     /** Start by touching the type registry singleton itself. */
     @BeforeAll
-    static void setUpClass() { registry = PyType.registry; };
+    static void setUpClass() { registry = PyType.registry; }
 }
diff --git a/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestStopIteration.java b/rt4core/src/kernelTest/java/uk/co/farowl/vsj4/runtime/TypeInitTestStopIteration.java
@@ -0,0 +1,39 @@
+// Copyright (c)2025 Jython Developers.
+// Licensed to PSF under a contributor agreement.
+package uk.co.farowl.vsj4.runtime;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Test that the Python type system comes into operation in a consistent
+ * state after creating an instance of {@link PyStopIteration}, which
+ * references a type through {@link PyExc} in its static initialisation.
+ * Most of the tests are in the superclass.
+ */
+@DisplayName("After constructing a PyStopIteration ...")
+@SuppressWarnings("static-method")
+class TypeInitTestStopIteration extends TypeInitTest {
+
+    /** Initialised in {@link #setUpClass()}. */
+    static Object object;
+
+    /** Start by creating an instance of {@code PyStopIteration}. */
+    @BeforeAll
+    static void setUpClass() { object = new PyStopIteration(); }
+
+    @Test
+    @DisplayName("PyStopIteration.TYPE is not null")
+    void type_not_null() { assertNotNull(PyStopIteration.TYPE); }
+
+    @Test
+    @DisplayName("PyExc.TypeError is not null")
+    void typeerror_not_null() { assertNotNull(PyExc.TypeError); }
+
+    @Test
+    @DisplayName("PyExc.StopIteration is not null")
+    void stopiter_not_null() { assertNotNull(PyExc.StopIteration); }
+}
diff --git a/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyAttributeError.java b/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyAttributeError.java
@@ -1,4 +1,4 @@
-// Copyright (c)2024 Jython Developers.
+// Copyright (c)2025 Jython Developers.
 // Licensed to PSF under a contributor agreement.
 package uk.co.farowl.vsj4.runtime;
 
@@ -12,7 +12,7 @@ public class PyAttributeError extends PyBaseException {
     /** The type object of Python {@code AttributeError} exceptions. */
     public static final PyType TYPE = PyType.fromSpec(
             new TypeSpec("AttributeError", MethodHandles.lookup())
-                    .base(PyExc.Exception)
+                    .base(Exception)
                     .add(Feature.REPLACEABLE, Feature.IMMUTABLE)
                     .doc("Attribute not found."));
 
diff --git a/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyBaseException.java b/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyBaseException.java
@@ -24,10 +24,33 @@
  * {@link #setType(Object)} with types represented by the same Java
  * class (which obviously cannot change).
  * <p>
- * A Java {@code try-catch} construct intended to catch Python
- * exceptions should catch {@code PyBaseException}. If it is intended to
- * catch only specific kinds of Python exception it must examine the
- * type and re-throw the unwanted exceptions.
+ * CPython prohibits class-assignment involving built-in types directly.
+ * For example {@code FloatingPointError().__class__ = E} and its
+ * converse are not allowed. There seems to be no structural reason to
+ * prohibit it, but we do so for compatibility.
+ * <p>
+ * The implementation follows CPython closely, where the implementation
+ * of many exception types is shared with multiple others. This allows
+ * multiple inheritance and class assignment amongst user-defined
+ * exceptions, with diverse built-in bases, in ways that may be
+ * surprising. The following is valid in Python: <pre>
+ * class TE(TypeError): __slots__=()
+ * class FPE(FloatingPointError): __slots__=()
+ * TE().__class__ = FPE
+ * class E(ZeroDivisionError, TypeError): __slots__=()
+ * E().__class__ = FPE
+ * </pre>In order to meet expectations set by CPython, the Java
+ * representation in Java is correspondingly shared. For example
+ * {@code TypeError}, {@code FloatingPointError} and
+ * {@code ZeroDivisionError} must share a representation. In fact they
+ * are defined in this class, to share the representation of
+ * {@code BaseException}.
+ * <p>
+ * Since different Python exceptions are represented by the same
+ * classes, we cannot use a Java {@code catch} clause to select them. We
+ * must catch the representation class of the intended Python exception,
+ * and re-throw it if it does not match. Method {@link #only(PyType)} is
+ * provided to make this simpler.
  *
  * @implNote It would have been convenient, when catching exceptions in
  *     Java, if the different classes of Python exception could have
@@ -40,11 +63,14 @@
 // Compare CPython PyBaseExceptionObject in pyerrors.c
 public class PyBaseException extends RuntimeException
         implements WithClassAssignment, WithDict {
-    private static final long serialVersionUID = 1L;
+
+    /** Allow the type system package access. */
+    private static final MethodHandles.Lookup LOOKUP = MethodHandles
+            .lookup().dropLookupMode(MethodHandles.Lookup.PRIVATE);
 
     /** The type object of Python {@code BaseException} exceptions. */
-    public static final PyType TYPE = PyType.fromSpec(
-            new TypeSpec("BaseException", MethodHandles.lookup())
+    public static final PyType TYPE =
+            PyType.fromSpec(new TypeSpec("BaseException", LOOKUP)
                     .add(Feature.REPLACEABLE, Feature.IMMUTABLE)
                     .doc("Common base class for all exceptions"));
 
@@ -55,8 +81,6 @@ public class PyBaseException extends RuntimeException
     // XXX dictionary required
     Map<Object, Object> dict;
 
-    // XXX align constructor more directly to CPython.
-
     /**
      * The arguments given to the constructor, which is also the
      * arguments from {@code __new__} or {@code __init__}. Not
@@ -237,6 +261,85 @@ protected Object __repr__() throws Throwable {
         return sj.toString();
     }
 
-    // plumbing -------------------------------------------------------
+    // Python exceptions sharing this representation -----------------
 
+    /**
+     * Permit a sub-class to create a type object for a built-in
+     * exception that extends a single base, with the addition of no
+     * fields or methods, and therefore has the same Java representation
+     * as its base.
+     *
+     * @param excbase the base (parent) exception
+     * @param excname the name of the new exception
+     * @param excdoc a documentation string for the new exception type
+     * @return the type object for the new exception type
+     */
+    // Compare CPython SimpleExtendsException in exceptions.c
+    // ... or (same to us) MiddlingExtendsException
+    protected static PyType extendsException(PyType excbase,
+            String excname, String excdoc) {
+        TypeSpec spec = new TypeSpec(excname, LOOKUP).base(excbase)
+                // Share the same Java representation class as base
+                .primary(excbase.javaClass())
+                // This will be a replaceable type.
+                .add(Feature.REPLACEABLE, Feature.IMMUTABLE)
+                .doc(excdoc);
+        return PyType.fromSpec(spec);
+    }
+
+    /** {@code Exception} extends {@link PyBaseException}. */
+    protected static PyType Exception =
+            extendsException(TYPE, "Exception",
+                    "Common base class for all non-exit exceptions.");
+    /** {@code TypeError} extends {@code Exception}. */
+    protected static PyType TypeError = extendsException(Exception,
+            "TypeError", "Inappropriate argument type.");
+    /** {@code LookupError} extends {@code Exception}. */
+
+    protected static PyType LookupError = extendsException(Exception,
+            "LookupError", "Base class for lookup errors.");
+    /** {@code IndexError} extends {@code LookupError}. */
+    protected static PyType IndexError = extendsException(LookupError,
+            "IndexError", "Sequence index out of range.");
+    /** {@code ValueError} extends {@link Exception}. */
+    protected static PyType ValueError =
+            extendsException(Exception, "ValueError",
+                    "Inappropriate argument value (of correct type).");
+
+    /** {@code ArithmeticError} extends {@link Exception}. */
+    protected static PyType ArithmeticError =
+            extendsException(Exception, "ArithmeticError",
+                    "Base class for arithmetic errors.");
+    /** {@code FloatingPointError} extends {@link ArithmeticError}. */
+    protected static PyType FloatingPointError =
+            extendsException(ArithmeticError, "FloatingPointError",
+                    "Floating point operation failed.");
+    /** {@code OverflowError} extends {@link ArithmeticError}. */
+    protected static PyType OverflowError =
+            extendsException(ArithmeticError, "OverflowError",
+                    "Result too large to be represented.");
+    /** {@code ZeroDivisionError} extends {@link ArithmeticError}. */
+    protected static PyType ZeroDivisionError = extendsException(
+            ArithmeticError, "ZeroDivisionError",
+            "Second argument to a division or modulo operation was zero.");
+
+    /*
+     * Warnings are Exception objects, but do not get thrown (I think),
+     * being used as "categories" in the warnings module.
+     */
+    /** {@code Warning} extends {@link Exception}. */
+    protected static PyType Warning = extendsException(Exception,
+            "Warning", "Base class for warning categories.");
+    /** {@code DeprecationWarning} extends {@link Warning}. */
+    protected static PyType DeprecationWarning = extendsException(
+            Warning, "DeprecationWarning",
+            "Base class for warnings about deprecated features.");
+    /** {@code RuntimeWarning} extends {@link Warning}. */
+    protected static PyType RuntimeWarning = extendsException(Warning,
+            "RuntimeWarning",
+            "Base class for warnings about dubious runtime behavior.");
+
+    // plumbing ------------------------------------------------------
+
+    private static final long serialVersionUID = 1L;
 }
diff --git a/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyExc.java b/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyExc.java
diff --git a/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyKeyError.java b/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyKeyError.java
diff --git a/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyNameError.java b/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyNameError.java
diff --git a/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyStopIteration.java b/rt4core/src/main/java/uk/co/farowl/vsj4/runtime/PyStopIteration.java
