jeff5 · Mar 14, 2025 · Mar 14, 2025 · Mar 14, 2025 · Mar 14, 2025 · Oct 13, 2026
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 This is the development repository of Jython,
 the implementation of Python in Java.
 
-You are looking at the branch intended to support version 3.8 of Python:
+You are looking at the branch intended to support version 3.x of Python:
 it doesn't build anything useful right now.
 Jython 3.x is not yet a viable product you can use in applications.
 Head over to [the 2.7 branch](https://github.com/jython/jython/tree/master)
@@ -14,8 +14,8 @@ to find the current release.
 
 ## Target
 
-Along with good language and runtime compatibility with CPython 3.8,
-Jython 3.8 is intended to provide substantial support of the Python ecosystem,
+Along with good language and runtime compatibility with CPython 3.11,
+Jython 3.11 is intended to provide substantial support of the Python ecosystem,
 and solid Java integration.
 
 For more about the target see the
@@ -34,7 +34,7 @@ pull requests, documentation changes and e-mail discussions.
 
 The current focus is to establish a foundation for the run-time
 that makes good use of the dynamic language features of the JVM.
-There are just enough classes here to illustrate the architectural ideas
+There is a growing set of classes here to test the architectural ideas
 underpinning the new foundation.
 
 The code of the Jython 2 implementation is also present on this branch,

diff --git a/build-tools/python/lib/compile_examples.py b/build-tools/python/lib/compile_examples.py
@@ -1,12 +1,13 @@
-# Reading compiled Python files
+# Generate compiled Python files as test material
 
 import sys, os.path
 import marshal, py_compile, dis
 
 # Normally you don't get a .pyc file if you just run a program.
 # You do get a .pyc file from compiling a module.
-# It is written in ./__pycache__ and called NAME.cpython-311.pyc
-
+# It is written in ./__pycache__ and called NAME.cpython-VERSION.pyc
+# and we use this to generate .pyc as test material for the byte
+# code interpreter.
 CACHE = '__pycache__'
 COMPILER = 'cpython-311'
 

diff --git a/build-tools/python/lib/core/PyFloat.py b/build-tools/python/lib/core/PyFloat.py
@@ -1,6 +1,6 @@
 # PyFloat.py: A generator for Java files that define the Python float
 
-# Copyright (c)2021 Jython Developers.
+# Copyright (c)2025 Jython Developers.
 # Licensed to PSF under a contributor agreement.
 
 # This generator writes PyFloatMethods.java and PyFloatBinops.java .
@@ -312,13 +312,13 @@ def special_methods(self, e):
 
         # Emit the unary operations
         for op in self.UNARY_OPS:
-            self.emit_heading(e, op.name)
+            self.emit_heading(e, op)
             for t in self.ACCEPTED_CLASSES:
                 self.special_unary(e, op, t)
 
         # Emit the binary operations op(T, Object)
         for op in self.BINARY_OPS:
-            self.emit_heading(e, op.name)
+            self.emit_heading(e, op)
             for vt in self.ACCEPTED_CLASSES:
                 self.special_binary(e, op, vt, OBJECT_CLASS)
 
@@ -328,12 +328,13 @@ def special_binops(self, e):
         # Emit the binary operations and comparisons
         for op in self.BINARY_OPS:
             if op.class_specific:
-                self.emit_heading(e, op.name)
+                self.emit_heading(e, op)
                 for vt in self.ACCEPTED_CLASSES:
                     for wt in self.OPERAND_CLASSES:
                         self.special_binary(e, op, vt, wt)
 
     def special_unary(self, e, op:UnaryOpInfo, t):
+        self.emit_unary_javadoc(e, op, 'self')
         e.emit('static ').emit(op.return_type.name).emit(' ')
         e.emit(op.name).emit('(').emit(t.name).emit(' self) {')
         with e.indentation():
@@ -350,6 +351,7 @@ def special_binary(self, e, op:BinaryOpInfo, t1, t2):
         reflected = op.name.startswith('__r') and \
             op.name not in ("__rshift__", "__round__", "__repr__")
         n1, n2 = 'vw' if not reflected else 'wv'
+        self.emit_binary_javadoc(e, op, n1, n2)
         e.emit('static ').emit(op.return_type.name).emit(' ')
         e.emit(op.name).emit('(')
         e.emit(t1.name).emit(' ').emit(n1).emit(', ')

diff --git a/build-tools/python/lib/core/PyLong.py b/build-tools/python/lib/core/PyLong.py
@@ -1,6 +1,6 @@
 # PyLong.py: A generator for Java files that define the Python int
 
-# Copyright (c)2021 Jython Developers.
+# Copyright (c)2025 Jython Developers.
 # Licensed to PSF under a contributor agreement.
 
 # This generator writes PyLongMethods.java and PyLongBinops.java .
@@ -394,6 +394,34 @@ class PyLongGenerator(ImplementationGenerator):
             lambda x, y: f'(double){y} / (double){x}',
             True),
 
+        # These produce very poor code, because the shift is promoted
+        # needlessly to a BigInteger. The int << shift is probably
+        # incorrect.
+        # BinaryOpInfo('__lshift__', OBJECT_CLASS, WorkingType.BIG,
+        #     binary_intmethod,
+        #     lambda x, y: f'{x}.shiftLeft(toShift({y}))',
+        #     lambda x, y: f'{x} << toShift({y})', 
+        #     lambda x, y: f'{x} << toShift({y})',
+        #     True),
+        # BinaryOpInfo('__rlshift__', OBJECT_CLASS, WorkingType.BIG,
+        #     binary_intmethod,
+        #     lambda x, y: f'{y}.shiftLeft(toShift({x}))',
+        #     lambda x, y: f'{y} << toShift({x})', 
+        #     lambda x, y: f'{y} << toShift({x})',
+        #     True),
+        # BinaryOpInfo('__rshift__', OBJECT_CLASS, WorkingType.BIG,
+        #     binary_intmethod,
+        #     lambda x, y: f'{x}.shiftRight(toShift({y}))',
+        #     lambda x, y: f'{x} >> toShift({y})', 
+        #     lambda x, y: f'{x} >> toShift({y})',
+        #     True),
+        # BinaryOpInfo('__rrshift__', OBJECT_CLASS, WorkingType.BIG,
+        #     binary_intmethod,
+        #     lambda x, y: f'{y}.shiftRight(toShift({x}))',
+        #     lambda x, y: f'{y} >> toShift({x})', 
+        #     lambda x, y: f'{y} >> toShift({x})',
+        #     True),
+
         BinaryOpInfo('__and__', OBJECT_CLASS, WorkingType.INT,
             binary_intmethod,
             lambda x, y: f'{x}.and({y})',
@@ -467,13 +495,13 @@ def special_methods(self, e):
 
         # Emit the unary operations
         for op in self.UNARY_OPS:
-            self.emit_heading(e, op.name)
+            self.emit_heading(e, op)
             for t in self.ACCEPTED_CLASSES:
                 self.special_unary(e, op, t)
 
         # Emit the binary operations op(T, Object)
         for op in self.BINARY_OPS:
-            self.emit_heading(e, op.name)
+            self.emit_heading(e, op)
             for vt in self.ACCEPTED_CLASSES:
                 self.special_binary(e, op, vt, OBJECT_CLASS)
 
@@ -483,12 +511,13 @@ def special_binops(self, e):
         # Emit the binary operations and comparisons
         for op in self.BINARY_OPS:
             if op.class_specific:
-                self.emit_heading(e, op.name)
+                self.emit_heading(e, op)
                 for vt in self.ACCEPTED_CLASSES:
                     for wt in self.OPERAND_CLASSES:
                         self.special_binary(e, op, vt, wt)
 
     def special_unary(self, e, op:UnaryOpInfo, t):
+        self.emit_unary_javadoc(e, op, 'self')
         e.emit('static ').emit(op.return_type.name).emit(' ')
         e.emit(op.name).emit('(').emit(t.name).emit(' self) {')
         with e.indentation():
@@ -505,6 +534,7 @@ def special_binary(self, e, op:BinaryOpInfo, t1, t2):
         reflected = op.name.startswith('__r') and \
             op.name not in ("__rshift__", "__round__", "__repr__")
         n1, n2 = 'vw' if not reflected else 'wv'
+        self.emit_binary_javadoc(e, op, n1, n2)
         e.emit('static ').emit(op.return_type.name).emit(' ')
         e.emit(op.name).emit('(')
         e.emit(t1.name).emit(' ').emit(n1).emit(', ')

diff --git a/build-tools/python/lib/core/PyUnicode.py b/build-tools/python/lib/core/PyUnicode.py
@@ -1,6 +1,6 @@
 # PyUnicode.py: A generator for Java files that define the Python str
 
-# Copyright (c)2021 Jython Developers.
+# Copyright (c)2025 Jython Developers.
 # Licensed to PSF under a contributor agreement.
 
 # This generator writes PyUnicodeMethods.java and PyUnicodeBinops.java .
@@ -243,15 +243,13 @@ def special_methods(self, e):
 
         # Emit the unary operations
         for op in self.UNARY_OPS:
-            e.emit_line(f'// {"-"*(60-len(op.name))} {op.name}')
-            e.emit_line()
+            self.emit_heading(e, op)
             for t in self.ACCEPTED_CLASSES:
                 self.special_unary(e, op, t)
 
         # Emit the binary operations op(T, Object)
         for op in self.BINARY_OPS:
-            e.emit_line(f'// {"-"*(60-len(op.name))} {op.name}')
-            e.emit_line()
+            self.emit_heading(e, op)
             for vt in self.ACCEPTED_CLASSES:
                 self.special_binary(e, op, vt, OBJECT_CLASS)
 
@@ -261,8 +259,7 @@ def special_binops(self, e):
         # Emit the binary operations and comparisons
         for op in self.BINARY_OPS:
             if op.class_specific:
-                e.emit_line(f'// {"-"*(60-len(op.name))} {op.name}')
-                e.emit_line()
+                self.emit_heading(e, op)
                 for vt in self.ACCEPTED_CLASSES:
                     for wt in self.OPERAND_CLASSES:
                         self.special_binary(e, op, vt, wt)
@@ -287,6 +284,7 @@ def left_justify(self, text):
         return clean
 
     def special_unary(self, e, op:UnaryOpInfo, t):
+        self.emit_unary_javadoc(e, op, 'self')
         e.emit('static ').emit(op.return_type.name).emit(' ')
         e.emit(op.name).emit('(').emit(t.name).emit(' self) {')
         with e.indentation():
@@ -299,6 +297,7 @@ def special_binary(self, e, op:BinaryOpInfo, t1, t2):
         reflected = op.name.startswith('__r') and \
             op.name not in ("__rrshift__", "__round__", "__repr__")
         n1, n2 = 'vw' if not reflected else 'wv'
+        self.emit_binary_javadoc(e, op, n1, n2)
         e.emit('static ').emit(op.return_type.name).emit(' ')
         e.emit(op.name).emit('(')
         e.emit(t1.name).emit(' ').emit(n1).emit(', ')

diff --git a/build-tools/python/lib/core/base.py b/build-tools/python/lib/core/base.py
@@ -1,6 +1,6 @@
 # base.py: foundations for source-code generation from templates
 
-# Copyright (c)2021 Jython Developers.
+# Copyright (c)2025 Jython Developers.
 # Licensed to PSF under a contributor agreement.
 
 # Module: evo1.generate.base
@@ -81,8 +81,8 @@ def emit_object_template(self, e, src):
         e.emit_line(" */")
 
     # Emit a rule (comment) above a block of implementations
-    def emit_heading(self, e, name:str):
-        e.emit_line(f'// {"-"*(60-len(name))} {name}')
+    def emit_heading(self, e, op:OpInfo):
+        e.emit_line(f'// {"-"*(60-len(op.name))} {op.name}')
         e.emit_line()
 
     # Emit methods selectable by a single type
@@ -93,6 +93,21 @@ def special_methods(self, e):
     def special_binops(self, e):
         pass
 
+    def emit_unary_javadoc(self, e, op:OpInfo, n:str='self'):
+        '''Emit Javadoc of a unary special method'''
+        e.emit_line(f'/** Unary special method {{@code {op.name}}}.')
+        e.emit_line(f'    @param {n} target')
+        e.emit_line(f'    @return {{@code self.{op.name}()}} */')
+        e.emit_line('')
+
+    def emit_binary_javadoc(self, e, op:OpInfo, n1:str, n2:str):
+        '''Emit Javadoc of a binary special method'''
+        e.emit_line(f'/** Binary special method {{@code {op.name}}}.')
+        e.emit_line(f'    @param {n1} left operand')
+        e.emit_line(f'    @param {n2} right operand')
+        e.emit_line(f'    @return {{@code {n1}.{op.name}({n2})}} */')
+        e.emit_line('')
+
     def emit_object_plumbing(self, e):
         pass
 

diff --git a/build.gradle b/build.gradle
@@ -1,7 +1,7 @@
 /*
- * build.gradle
+ * $projectDir/build.gradle
  *
- * Build file for the Jython Project, a multi-project build.
+ * Root project build file for the Jython Project, a multi-project build.
  */
 
 plugins {
@@ -25,7 +25,7 @@ plugins {
 // Versions are specified in this grammar:
 // <major> . <minor> ( . <micro> )? ( <release> <serial> )? ( - <word> )?
 
-version = '3.11.0a1'
+version = '3.11.0a2'
 
 // Valid examples (please preserve in comments):
 //version = '2.7.2a2'
@@ -35,17 +35,18 @@ version = '3.11.0a1'
 //version = '2.7.2'
 
 group = 'org.python'
+description = 'Jython - Python for the Java Platform'
+
 
 // ---------------- Miscellaneous configuration --------------------------------
 
 allprojects {
 
     apply plugin: 'java'
-    // We support Java 11 onwards officially.
-    sourceCompatibility = '17'
 
     // Same configuiration all sub-projects
     tasks.withType(JavaCompile) {
+        sourceCompatibility = '17'
         options.encoding = 'UTF-8'
         options.debug = true
 
@@ -58,12 +59,12 @@ allprojects {
 
     tasks.withType(Javadoc) {
         options.encoding = 'UTF-8'
-        options.showFromPackage()
     }
 
     repositories {
         mavenLocal()
-        // Jython is distributed through Maven Central. Get our dependencies there too.
+        // Jython is distributed through Maven Central.
+        // Get our dependencies there too.
         mavenCentral()
     }
 }